[tae898]

What

Stacked on #25 (which is on #23's Antora component): the base is docs/packages-and-postgres-sqlite-pages. Merge after #25, or retarget to main once it lands.

New page docs/modules/ROOT/pages/how-to/concurrency.adoc, "Concurrency, processes and crashes", plus its nav.adoc entry. It covers only what is specific to the bindings: threads sharing one Database, several writers and the retry rule, asyncio, processes and fork, signals and crashes, and free-threaded Python 3.14t. Engine isolation levels and WAL durability are linked with xrefs (arcadedb::concepts/transactions.adoc#isolation and #wal-flush-durability), not repeated.

Every number on the page is from the probe study of 2026-10-24 (JVM wheel 26.10.2.post1, native wheel 26.10.2.dev1, Python 3.12.13, and the native wheel on 3.14.5 free-threaded). The tables are generated from the study's RESULT lines, not typed. Each number sits next to its setup (threads, operations, run count, build), and each recommendation names its run count. The probe scripts and logs are local to the benchmark notes and are not in this repository yet; the page says so.

What the page says (and where it differs from the first draft)

• Several writers: an atomic SQL update (SET n = n + 1) with a retry lost 0 updates in 6 of 6 runs (2 retry styles, 3 builds). Reading with SELECT and writing back a Python-computed value under the default isolation lost updates even with every conflict retried: with the bindings' run_in_transaction 1,137 of 12,000 on the JVM build and 201 of 12,000 on native; with an own loop 2,883 and 331. The same read-modify-write under REPEATABLE_READ with an own retry loop lost 0 in 3 of 3 runs (one per build). So the bindings' retry helper loses nothing only when the update is atomic in the statement; with read-modify-write it still lost updates. The page gives the BEGIN ISOLATION REPEATABLE_READ loop as code.
• Processes: spawn with one database per process worked (1 run per build, 4 workers). Fork after a database was created: on the JVM build a child that used the inherited Database hung (both os.fork and multiprocessing with fork); on the native build every fork-after variant exited 0 in its single run. The page reports that and does not recommend fork-after on either build, because one observation is too few.
• Signals: fix: give SIGINT and SIGTERM back to Python after the JVM starts #26 is still open, so the page describes the behaviour and links the PR instead of saying "fixed in". JVM build, SIGINT with a transaction open and the main thread in one time.sleep(120): no reaction within 60 s in 5 of 5 runs (a busy child reacted in 5 of 5); SIGTERM exit status -6 in 10 of 10. Native: no hang and -15 in every run. kill -9: 0 acknowledged commits lost in 20 of 20 runs on each build (5 of 5 on 3.14t); no uncommitted row visible and CHECK DATABASE clean after any of the 60 signal runs. The page says plainly that a process kill is not a power loss.
• Dropped from the draft because no probe log backs it: "close() of the AsyncExecutor is final". Reworded: the 3.14t runs are shorter (3 minutes of load, 500 operations per writer, 10 iterations per task), which the draft had not said; the largest event-loop stall is given per call style instead of one figure.

Checked locally

Antora build with the main ArcadeDB docs (arcadedb-docs, branch docs/arcadedb-python-component) and this branch as sources: exit code 0, no warning or error from this component, and the xrefs resolve (arcadedb/concepts/transactions.html#isolation and #wal-flush-durability, packages.html#drivers, the #26 link). The retry loop on the page ran against the JVM wheel with 4 threads on one record (600 of 600 increments), as a functional check only; that run is not a number on the page. pre-commit has no hook for AsciiDoc here, so there was nothing to run on these files. A script compared every number on the page with the study's README and logs.

Not requested from a reviewer yet; the 24-hour practice for Roberto applies.

🤖 Generated with Claude Code