feat(trino): append and upsert

[carolsimone]

Fifth runtime PR of the write-modes series (spec R5). Depends on the engine-port PR (#75, contract 0.8.0); stacked on #77 (DuckDB) locally — base is feat/write-modes-duckdb; retarget to main as the stack merges.

• Risks first (spec section 8): a probe pins Trino 483 MERGE on Iceberg — update and insert in one statement from a stage table, insert-only MERGE, failure on format_version 1 (target unchanged), failure when two stage rows match one target row. All four held as written; no fallback was needed.
• Refactor (D20): _create_stage / _insert_batches / _drop_stage shared by load, append, _upsert; load unchanged in behavior.
• TrinoAdapter(WarehouseAdapter, AppendCapable, UpsertCapable): table_columns (information_schema, lowercased lookup, LookupError when absent); append = stage + one INSERT ... SELECT; _upsert = stage + one MERGE (no WHEN MATCHED when every column is in the key). One Iceberg commit per write; the stage drop afterwards is best-effort and only logged; zero rows create no stage.
• ensure_table(..., primary_key=...): no constraint DDL; a key with format_version below 2 is rejected before any DDL.
• The engine-contract conformance suite runs in the trino integration job, plus checks that a failed append or upsert leaves no stage table.

🤖 Generated with Claude Code

https://claude.ai/code/session_0137E9XmyUXhwPTRrtNfivDw

[carolsimone]

Automated code review (OCR delegation mode) over the full branch diff (26 changed files, +3013/−131): no critical/high/medium findings. One low-severity observation inline, plus one low-severity note on contract/continuo_engine_contract/keys.py (not part of this PR's diff): its ensure_unique_key docstring promises repeated keys are named "in order of first appearance", but that ordering comes from pyarrow's group_by, whose key order is not contractual — consider softening the docstring or sorting the repeated keys. Coverage: 26/26 files reviewed.

[carolsimone]

Low (boundary condition): This guard only fires when the config explicitly sets format_version. If the target table already exists at Iceberg format v1 (e.g. created before the node became an upsert node) and the config omits format_version, the upsert fails later at the MERGE with a raw Trino error instead of this clear ValueError. This mirrors the postgres adapter's deliberate fail-at-ON CONFLICT stance, so it may be intentional — but Trino could cheaply detect it by reading format_version from {table}$properties when the table already exists and a key is set.

[carolsimone]

Verified — intentional, and I'm leaving it. The guard is deliberately config-only (documented at adapter.py:590-594): it rejects an explicit format_version < 2 before any DDL, and otherwise lets the engine reject a live-state mismatch at MERGE. That mirrors the postgres adapter's deliberate fail-at-ON CONFLICT stance for a missing key constraint, so pre-introspecting the live table would make trino stricter than postgres for the same class of problem.

The gap you describe is also narrow: modern Trino defaults new Iceberg tables to format v2, so a MERGE only hits v1 on a replace→upsert migration of a table that was explicitly created at v1. A cheap live check is possible here — the adapter already reads "schema"."table$properties" in _table_location — but the exact $properties key for the format version isn't something I can verify without the live Trino+Iceberg stack, and shipping a wrong key name would degrade the error (a RuntimeError from the probe) rather than improve it. If you'd like the clearer error for the migration case, I'll add it as a follow-up with an integration-test case that pins the property key against the real stack.

[carolsimone]

On the review-body note about keys.py ensure_unique_key: agreed the docstring over-promises — "in order of first appearance" leans on pyarrow group_by's key order, which isn't contractual. It's in already-merged code (contract, from #75), outside this PR's diff, so I'm not touching keys.py here. Batching it with the other merged-code cleanups into a small PR off main (softening the docstring; the repeated-key list is diagnostic only, so no need to sort it). The main branch review on this PR reported no critical/high/medium findings.