[stugorf]

Problem and change

Relates to #19. Adds keyword-only timeout=None in seconds to CypherEngine.execute, execute_batches and CypherQuery.execute. One monotonic deadline includes planning and pauses between reads. Zero expires immediately; negative, nonfinite and unrepresentable values raise ValueError.

Native pyarrow.RecordBatchReader is preserved. Initial expiry raises TimeoutError; expired reads raise ArrowInvalid with Query timeout exceeded. A watchdog releases owned streams during consumer idle time. Close/drop and ordinary errors also release resources. Timed contexts install a private DataFusion join guard, including rejected nested-loop candidates; ordinary contexts remain reusable.

Validation

Head a641cf25cbe34db25245ce2543140af5b735d30e; frozen parent 81ef524be83db4abb626394dd4940121a45751e2. Focused checks and regression details record commands, results, documentation and compatibility. The release receipt pins wheel/archive identity and 487 installed tests.

Both complete workloads pass unchanged goldens in memory and lazy modes. Retained first-pass geometric mean speedups are below (greater than one is faster). Per-query results and paired investigations remain in the audit archive.

Workload/mode	Main	Actual parent
Q30 memory	0.970	0.985
Q30 lazy	0.969	1.010
IC memory	1.146	1.042
IC lazy	1.113	0.976

Measurements use the same Apple M4 Max (16 cores, 128 GiB), macOS 26.6.2 arm64 and Python 3.13.17, with Q30 revision 6260689 and IC revision c185123. Reproduction instructions pin settings, data checksums, locks and commands. The frozen main baseline is code-identical to current main 90114f3; the equivalence check also verifies clean prospective main-target merges.

This is a coordinated draft. Preserve its frozen-head outcomes and apply the shared corrections in the qualified integration; changing the actual target requires requalification. The accepted combined engine source is 7d2ef3e; its current-main documentation merge is 5fe24cd.

The standalone 8,192-work budget passes its own gates, including the fixed-size IC6 investigation. The combined target retains the tested 1,024-work bound and matching tests after rejecting the larger-budget combined variant. External runner adoption remains outside this submission; keep #19 open.

User impact

execute, execute_batches and CypherQuery.execute gain keyword-only timeout=None in seconds. Initial expiry raises TimeoutError; stream expiry raises ArrowInvalid with Query timeout exceeded. Native readers remain. API docs, stubs and examples cover cooperative limits; external runner adoption remains open.

Review ledger · Current contribution guide

Audit archive: 47,675,190 bytes; SHA-256 b3486fb30a34639c830b5d49353b3838f96369f95df959ac35f85511f7f8b2de. The small current-main supplement preserves the documentation update. Original absolute paths in receipts map to included records through the archive index.

Submitted by David Hughes (@stugorf), with AI Collaboration.

[prrao87]

This change merged into an intermediate branch, not main. It reached main through #55, which brought in the final integrated version of this work with every original commit kept on its branch. Follow-up fixes from review are listed there.