docs: Java API ref, C++/Java GSG variants, DB_TXN_SNAPSHOT_SAFE

[gburd]

Completes the libdb documentation set the DocBook migration left out: the Java
API reference, the C++/Java Getting-Started guide variants, and the SSI flag
docs + a flag reconcile. All work flows through the existing docs pipeline
(docs_src/build.py, version single-sourced at 5.3.33) and the docs.yml gates.

Task 1 — Java API reference (regenerated from source)

lang/java is a supported binding but the old docs/java/ Javadoc was never
migrated. Rather than extract the frozen 2013 HTML, this regenerates it
from lang/java/src/ so it always matches the current code.

• New build_java_api() in docs_src/build.py runs javadoc over the public
  com.sleepycat.* packages (the historical published set; excludes bundled
  ASM, compat shims, and db.internal/persist.impl/util.keyrange
  internals — -sourcepath spans all of lang/java/src so references still
  resolve) into docs-build/html/java-api/ (a gitignored build artifact).
• -Xdoclint:none keeps the 2005-era doc-comment HTML warnings-only under
  javadoc 21; version-stamped -windowtitle/-doctitle; -notimestamp.
  Guarded on javadoc availability (skip-with-note, like the PDF path).
• flake devShell gains pkgs.jdk so CI's nix develop has javadoc.
• index.md links it under API reference, noted as javadoc-generated (not
  part of the Markdown no-loss gate).
• Wired automatically: make docs / ninja docs / docs.yml all drive
  build.py.

Spot-check: docs-build/html/java-api/index.html lists com.sleepycat.db;
Database.html, Environment.html, Transaction.html render with methods
(e.g. Transaction: abort, commit, prepare). 237 class pages.

Task 2 — C++/Java Getting-Started guide variants

The three GSG guides were migrated C-only. The CXX/JAVA variants are extracted
from the gh-pages DocBook archive with the proven extract.py into cxx/ and
java/ subdirs (each with its own _meta.toml, order from the source TOC).
Guide landings become C/C++/Java language pickers; index.md links all three.

Retention (verify.py vs gh-pages source, --threshold 0.99):

guide	variant	pages	word-retention	hard-drops
gsg	C++	37	100.00%	0
gsg	Java	62	100.00%	0
gsg_txn	C++	38	100.00%	0
gsg_txn	Java	39	100.00%	0
gsg_db_rep	C++	26	100.00%	0
gsg_db_rep	Java	25	100.00%	0

gsg_txn's 7 diagram JPEGs are copied into each variant's img/; per-language
code samples preserved verbatim. Each variant's titled _meta.toml also yields
its own PDF book (19 books total now, all validated).

The generated java-api/ tree carries doc-comment cross-links to the old
DocBook layout that dangle here; it's a build artifact outside the no-loss
gate, so docs.yml's lychee link-check excludes it via --exclude-path.

Task 3 — DB_TXN_SNAPSHOT_SAFE + flag reconcile

DB_TXN_SNAPSHOT_SAFE (0x800) is our SSI addition (SI + Cahill serializable
conflict detection), undocumented until now. Wording verified against the
engine (src/txn/txn.c, src/lock/lock.c, src/env/env_method.c):

• api/c/txnbegin.md — the flag: implies DB_TXN_SNAPSHOT, layers
  serializable conflict detection, may abort with DB_SNAPSHOT_UNSAFE /
  DB_SNAPSHOT_CONFLICT, and cannot be prepared for 2PC (prepare → EINVAL).
  Also documented DB_TXN_FAMILY (the one other missing txn_begin flag).
• api/c/envset_flags.md — SSI is per-transaction only (env OK_FLAGS
  accepts DB_TXN_SNAPSHOT but not _SAFE).
• guides/gsg_txn/isolation.md + guides/programmer_reference/transapp_read.md
  — a Serializable Snapshot Isolation subsection (SI vs SSI, the return codes,
  the 2PC restriction).
• guides/programmer_reference/program_errorret.md — the
  DB_SNAPSHOT_UNSAFE (-30967) and DB_SNAPSHOT_CONFLICT (-30968) codes.

Flag reconcile (docs_src/_migrate/flag-reconcile.md): every txn_begin
flag is now documented; DB_READ_COMMITTED/DB_READ_UNCOMMITTED/DB_MPOOL_AIO
were already documented. DB_DATABASE_LOCKING and DB_NOFLUSH remain
undocumented set_flags flags but are pre-existing non-SSI gaps, left out of
this SSI-focused pass. There is no DB_TXN_SNAPSHOT_UNSAFE flag —
DB_SNAPSHOT_UNSAFE is a return code.

Validation

• build.py: 1690 HTML + 789 man + Java API + 19 PDF books, all v5.3.33.
• build.py --selfcheck: OK.
• Completeness gate (man_coverage.py --ci): PASS (all public functions
  documented; SNAPSHOT_SAFE is a flag, not a method — method gate unaffected).
• Spelling gate: PASS (verbatim legacy typos in the new variants baselined,
  matching the C variant; one stale csharp.md baseline entry trimmed).
• Internal link check (lychee offline, java-api excluded): 0 errors.
• Man-lint (mandoc -Tlint): 0 ERRORS.
• Re-verified existing api/c (470 pages, 100%) and gsg C-variant (37 pages,
  100%) against gh-pages: no regression (extract.py untouched).

No src/ engine changes (Task 3 is docs about the flag). No AWS / other
workflows touched except docs.yml (java-api link-check exclude).

[github-actions]

Coccinelle convention checks

No new violations. ✅

Resolved since baseline (2) -- update dist/cocci/baseline.txt to lock these in.

rule_mutex_unbalanced|MUTEX_UNBALANCED|src/crypto/mersenne/mt19937db.c|return (ret);
rule_mutex_unbalanced|MUTEX_UNBALANCED|src/mp/mp_register.c|return (ret);

[github-actions]

ABI diff vs v5.3.33 (libabigail — authoritative)

Removed exported symbols (nm -D, _NNNN version suffix normalized)

None.

---

Advisory: libabigail/nm is the authoritative binary-ABI check; Coccinelle is complementary source-level early warning. See dist/cocci/README.md.