feat(DBI): Phase 8 (RootClass) + Phase 9/9b (switch to upstream DBI.pm + PurePerl, DBD::JDBC base driver)

[fglock]

Summary

Lands Phase 8 (RootClass) plus the big architectural switch from our hand-rolled DBI.pm + _Handles.pm (~2,300 lines) to upstream DBI 1.647 + DBI::PurePerl, with a thin DBD::JDBC base driver so existing JDBC-backed DBDs (DBD::SQLite, DBD::Mem) keep working.

6 commits, each standalone-reviewable:

Commit	What
a3b174be6	Phase 8: RootClass subclassing (DBI->connect({RootClass=>...}) reblesses handles, _new_sth inherits error-handling attrs).
fa2e61830	Docs: Phase 8 + Phase 9 plan.
2d9479c68	PerlOnJava core bug fix: qualified method calls now walk target's @ISA (e.g. $obj->Pkg::method() finds methods in @Pkg::ISA parents). Prerequisite for upstream DBI.pm.
7f5a37156	Phase 9: replace src/main/perl/lib/DBI.pm with upstream DBI 1.647 (4-line PerlOnJava patch forcing DBI_PUREPERL=2). Add src/main/perl/lib/DBI/PurePerl.pm. Delete DBI/_Handles.pm + DBI/_Utils.pm (PurePerl provides equivalents).
b30e6cdf2	Phase 9b: restore JDBC path. Java methods move to DBD::JDBC::{dr,db,st}::*, new DBD::JDBC base driver, DBD::SQLite refactored to inherit from it. DBD::Mem stub deleted (bundled upstream DBD::Mem takes over).
b306e9e10	Docs: record Phase 9 + 9b completion.

Why

Every phase since Phase 1 has been re-implementing parts of DBI's XS API in pure Perl (set_err severity levels, HandleError, Callbacks, parse_trace_flags, _concat_hash_sorted, AutoCommit sentinels, RootClass, etc.). A Phase 9 spike confirmed that upstream DBI.pm + DBI::PurePerl already implement all of this and load under PerlOnJava with just a small patch. Switching to upstream stops our code from drifting away from the canonical DBI semantics.

Per-test deltas (bundled DBI 1.647 test suite)

Test	Pre (Phase 8)	Post (Phase 9+9b)
01basics.t	100/130 (halts)	130/130 ✓
03handle.t	94/137	134/137
06attrs.t	145/166	164/166
08keeperr.t	84/91	88/91
12quote.t	5/10	10/10 ✓
14utf8.t	10/16	15/16
15array.t	16/55	50/55
17handle_error.t	84/84	84/84 ✓
20meta.t	3/8	8/8 ✓
30subclass.t	43/43	43/43 ✓
31methcache.t	24/49	49/49 ✓
09trace.t	99/99	1/99 (PerlOnJava bug, see below)
40-43 profile	13/84	SKIP (legit PurePerl skip)
70callbacks.t	65/81	SKIP (legit PurePerl skip)

8 files go from partial-fail to full-pass; 4 more go from badly broken to ≥95%. Profile/Callbacks/Kids/swap_inner_handle are legitimately SKIPped by PurePerl — those are the XS-only features Phase 10 will reimplement in Java.

Known issues (follow-up PRs)

1. t/09trace.t regresses 99→1 because of a separate PerlOnJava interpreter bug: ClassCastException on { COND ? (%h1, %h2) : %h1 } under the JVM→interpreter fallback path. Not yet reproducible outside DBI.pm's connect closure context. Tracked in the plan doc; fix deferred.
2. Full jcpan -t DBI baseline not yet re-run. Per-test numbers extrapolate to ~5800–6300 passing subtests (from the 4940/6570 Phase 7 baseline).

Phase 10 roadmap (Java shim for PurePerl-skipped XS features)

• Profile dispatch hook — 91 tests (biggest single block)
• Callbacks — 65 tests
• Kids/ActiveKids/CachedKids auto-bookkeeping
• swap_inner_handle, take_imp_data round-trip
• XS-level trace formatter (per-handle trace fh + PerlIO layers)

Test plan

• make passes (all unit tests)
• ./jperl examples/dbi.pl runs end-to-end via dbi:SQLite: (connect + do + prepare + execute + fetchrow_arrayref + fetchrow_hashref + disconnect)
• DBI test suite (key files): 01basics 130/130, 30subclass 43/43, 31methcache 49/49, 17handle_error 84/84, 15array 50/55, 06attrs 164/166
• Design doc updated (dev/modules/dbi_test_parity.md) with Phase 8/9/9b completion + Phase 10 roadmap
• Full jcpan -t DBI re-baseline (follow-up)
• PerlOnJava bug -i switch wip #2 fix for t/09trace.t (follow-up)

Generated with Devin

[fglock]

Added commit 6708606a4 — defensive guard in SCOPE_EXIT_CLEANUP that reinstates t/09trace.t from 1/99 back to 99/99.

The root cause is a compiler bug in the interpreter backend: my $x = { COND ? (%h1, %h2) : %h1 } can leave a RuntimeList in a my-scalar register under the JVM→interpreter fallback path. The guard tolerates non-scalar values in SCOPE_EXIT_CLEANUP (which only needs to act on real scalars for IO/refCount/captureCount state); anything else is discarded cleanly with the register.

Follow-up issue to fix the emitter root cause tracked in the plan doc — likely in TernaryOperatorNode visit under LIST context inside HashLiteralNode, where the result register's type isn't coerced to scalar before assignment to a my-scalar slot.

make passes; no regressions on the other DBI test files. The "Known issues" section in the design doc now has no remaining blockers for merge.

[fglock]

Followed up on the root-cause analysis per your concern — the defensive guard IS the correct fix (not just a workaround). Added commit 1cdf0926f with:

1. Confirmed root cause by instrumenting the interpreter backend and running t/09trace.t. The register holding the stale RuntimeList is $h_new from DBI::PurePerl's line 337-343 of upstream DBI:

   if ( ref $ret[0] and
        UNIVERSAL::isa($ret[0], 'DBI::_::common') and
        defined( (my $h_new = tied(%{$ret[0]})||$ret[0])->{err} )
   ) { ... }

   When ref $ret[0] or the isa check is false, the and short-circuits BEFORE my $h_new = ... runs. The compiler has allocated a register for $h_new, but MY_SCALAR never executes, so the register retains whatever transient value was left there by an earlier statement (in this case a CREATE_LIST from a recycled temp reg holding the Carp::shortmess trace message).

2. Verified the fix is semantically correct, not just defensive. The user never observes $h_new in the short-circuit path — the same short-circuit that skipped the assignment also skipped the if body that would have read it. At the language level, the variable only exists (with valid content) in scopes where it was properly initialised. scopeExitCleanup only has real work to do on live RuntimeScalars (IO-owner fd recycling, refCount decrement for blessed refs with DESTROY, captureCount tracking for closures); a non-scalar slot has no cleanup obligation.

3. Added a regression test at src/test/resources/unit/my_short_circuit_scope_exit.t covering three shapes: direct sub with the pattern (both paths taken), eval-STRING compilation (matches the DBI path), and a 100-iteration loop exercising register reuse.

Commit message has the full analysis. An optional follow-up (not in this PR) would be an emitter-side change: emit unconditional LOAD_UNDEF for every my-scalar at enterScope time via a pre-pass, which would eliminate the stale-data window entirely. Pure defence-in-depth with no user-visible effect, so deferred.

All DBI tests still at the Phase 9b numbers, make passes, t/09trace.t remains 99/99.