[nicoloboschi]

Summary

Fixes #1944. Retain returned 500 DPY-1003: the executed statement does not return rows on Oracle, turning test-python-client-oracle and test-typescript-client-oracle red.

Cause

#1930 changed the retain document-ownership gate to a single-statement upsert:

INSERT INTO documents (...) VALUES (...)
ON CONFLICT (id, bank_id) DO UPDATE SET content_hash = documents.content_hash
RETURNING content_hash

PostgreSQL runs this as-is. The Oracle adapter rewrites ON CONFLICT DO UPDATE to a MERGE — and Oracle MERGE cannot carry a RETURNING clause, so the rewritten statement returns no rows and the fetchval fails with DPY-1003.

Fix

Move the lock-and-read step behind a dialect-aware DataAccessOps.lock_document_for_write method (mirrors the existing strategy pattern that keeps if backend_type checks out of business logic):

• PostgreSQL — keeps the single-statement INSERT ... ON CONFLICT DO UPDATE ... RETURNING. DO UPDATE always takes the row lock atomically, preserving fix(retain): pre-extraction freshness recheck + serialize concurrent same-doc writers #1930's deadlock fix.
• Oracle — splits into two statements: an idempotent insert (IGNORE_ROW_ON_DUPKEY_INDEX, the same idiom already used by enqueue_graph_maintenance) followed by SELECT content_hash ... FOR UPDATE. Concurrent same-document inserters block on the duplicate key until the holder commits, so writers still serialize.

Both return the pre-existing hash ('__pending__' for a freshly inserted row), driving the later-batch takeover check unchanged.

Tests

tests/test_lock_document_for_write.py:

• PG functional coverage of the placeholder→stored-hash transition and (id, bank_id) isolation (runs in the default suite against pg).
• Translator tests pinning the root cause (the old upsert rewrites to a MERGE that drops RETURNING) and that the Oracle fallback's SELECT ... FOR UPDATE translates cleanly.

End-to-end Oracle coverage comes from the existing test-*-client-oracle CI jobs that the issue reported failing.

Scope

Only the broken DO UPDATE ... RETURNING site is rerouted. The two ON CONFLICT DO NOTHING + SELECT FOR UPDATE sites (zero-facts / no-batch paths) already translate correctly on Oracle and are left unchanged.