[magnusp]

Fixes #78

Three-layer contract. Hrana 3 over HTTP supplies the stream/baton transport: a begin is a request with a null baton, commit and rollback close their stream, and the server expires idle streams. java.sql supplies the JDBC lifecycle (auto-commit flag, commit/rollback rules, exception typing). xerial sqlite-jdbc is the behavioral reference for the transaction mode names and the no-op commit/rollback with no work.

Red

At origin/main (c496e38), section 2 still claims read-write transactions issue BEGIN IMMEDIATE eagerly at the start of the transaction pipeline. That is the contract #99 removed. Evidence: /tmp/xerial-parity-i78/lane-1-regression.log (trunk half contains the stale claim; head half does not).

Green

Section 2 now documents the implemented contract of LibsqlConnection after #99, #108, and #109:

• lazy begin: setAutoCommit(false) sends nothing; the next statement begins on a new stream;
• the configured begin mode, TransactionMode.DEFERRED (default), IMMEDIATE, or EXCLUSIVE, set with LibsqlConnection.setTransactionMode;
• commit and rollback close the stream and do not re-begin;
• the next statement begins a new stream with a null baton;
• sqld idle-stream expiry and why an idle non-auto-commit connection holds no stream, including the remaining mid-transaction limit;
• the mapped in-transaction errors at executeStatement, executeBatchResults, beginTransaction, and endTransaction, with the BatchUpdateException wrapping;
• the failure states for a failed begin, commit, and rollback.

The #83 section now states that the transaction begins lazily on the first statement.

Lanes

• Lane 1, regression: trunk vs head section read side by side; the stale claim is gone at the head. /tmp/xerial-parity-i78/lane-1-regression.log
• Lane 2, begin-mode claim: checked against LibsqlConnection beginPending(), beginTransaction(), and TransactionMode; matches. /tmp/xerial-parity-i78/lane-2-specific.log
• Lane 3, stream expiry: lazy begin and post-commit close are checked against LibsqlTransactionLifecycleIT idle cases; the remaining open-transaction expiry limit is documented.
• Lane 4, fenced commands: the edited section contains no shell fences. /tmp/xerial-parity-i78/lane-4-commands.log
• Lane 5 and 9, references: every referenced path exists; 0 missing. /tmp/xerial-parity-i78/lane-5-refs.log
• Lane 6, diff: one file changed. /tmp/xerial-parity-i78/lane-6-diff.log
• Lane 7, render: fences balanced, headings and list structure intact, ToC anchor resolves. /tmp/xerial-parity-i78/lane-7-render.log
• Lane 8, validate: ./mvnw -q validate exits 0. /tmp/xerial-parity-i78/lane-8-validate.log
• Lane 10, fresh-agent follow: skipped, a fresh agent cannot be spawned from this owner session.
• Unit lane: grep -n 'BEGIN' IMPLEMENTATION_BUGS_AND_RESOLUTIONS.md and a claim-by-claim read against LibsqlConnection.
• Perf: ./mvnw -pl libsql-jdbc test three runs interleaved at c496e38 and d00127d; trunk median 2.13 s, head median 2.13 s (/tmp/xerial-parity-i78/perf-times.log). Docs-only, so no code delta.

Divergences and extra edits

• Section 2 is retitled Transaction Lifecycle over Hrana (Lazy Begin and WAL Locks) because the section now covers the whole transaction contract, not only WAL upgrades; the ToC anchor is updated.
• Two stale pre-existing references outside section 2 are corrected so the doc-wide reference check passes: HranaHttpClient.java to LibsqlHttpClient.java, and HranaJsonCodec.java to DirectHranaJsonCodec.java.
• The doc states the remaining limit plainly: the driver does not detect an expired baton, so a transaction left open across the server idle timeout can still fail.

Base: c496e38. Head: d00127d.