[magnusp]

Why

JDBC 4.3 Appendix B lists native getters for DATALINK, NCLOB, SQLXML,
and ROWID, plus the ASCII and national character streams, and this driver
threw SQLFeatureNotSupportedException for all of them. PR-3 adds those
read paths and the two missing parameter setters so the oracle's B-1, B-3,
and the listed cells of B-6 can go green.

What changed

• New LibsqlNClob, LibsqlSQLXML, and LibsqlRowId wrappers in the
  driver package. Each holds the materialized value of one column and every
  read after free() throws SQLException.
• getURL parses DATALINK text through URI.toURL() and throws
  SQLException (with MalformedURLException as the cause) when the text is
  not an absolute URL.
• getNClob, getSQLXML, and getRowId build the new wrappers over the
  stored text or bytes. getObject routes NCLOB, SQLXML, ROWID, and
  DATALINK to the same wrappers, so the object type and the typed getter
  agree.
• getAsciiStream reads the text as US-ASCII bytes and
  getNCharacterStream delegates to getNString.
• setSQLXML binds the SQLXML content as text. setRowId binds the bytes as
  a BLOB, the one representation getRowId reads back unchanged.
• SQLXML and ROWID join the declared-type registry so
  ResultSetMetaData.getColumnType, getColumnClassName, and getObject
  resolve them instead of falling back to the storage class.
• LibsqlClob is no longer final, so LibsqlNClob reuses it: SQLite
  stores national and regular text identically.

setArray and setRef still throw; PR-5 decides their status. No Appendix B
assertion was relaxed.

Scope

Read and bind only. No change to the declared-type model beyond the two new
registry rows, no change to JdbcValueConverter, no wiring change, no new
dependency, no interaction change.

Tradeoffs

• SQLXML.getSource and setResult throw SQLFeatureNotSupportedException.
  The wrapper is a read-only view over stored text; callers read it through
  getString or getCharacterStream. Parsing XML is left to the caller.
• setRowId binds a BLOB rather than text because text would lossily decode
  bytes that are not valid UTF-8, and the round trip is the contract.
• B-6 total failures rise (461 -> 627) even though 25 listed cells go green.
  The six new getters now succeed on columns whose Table B-6 row lists no
  conversion, and PR-6 adds the per-getter supported set that rejects them.

Blast Radius

• getObject return type changes for four declared types: DATALINK now
  returns URL, NCLOB NClob, SQLXML SQLXML, ROWID RowId. All four
  previously returned the storage-class value (String/Integer/byte[]).
• ResultSetMetaData now reports Types.SQLXML/Types.ROWID and the matching
  class names for SQLXML- and ROWID-declared columns instead of the
  storage fallback.
• Six ResultSet getters and two PreparedStatement setters stop throwing.
  LibsqlResultSetTest no longer lists them as unsupported.
• getAsciiStream replaces non-ASCII characters with ?, which is the
  US-ASCII encoder's contract; it is not a UTF-8 alias.
• LibsqlClob loses final; no public API change (package-private class).

Verification

Unit, at head 4067d42:

1. ./mvnw -q -pl libsql-jdbc -Dtest='Jdbc4AppendixBReadTest#b1NaturalGetterReturnsDeclaredJavaType' -Dsurefire.failIfNoSpecifiedTests=false test
   -> Tests run: 34, Failures: 3. Down from 7; the three left
   (ARRAY, STRUCT, REF) belong to PR-5.
2. ./mvnw -q -pl libsql-jdbc -Dtest='Jdbc4AppendixBReadTest#b6GetterHonoursSupportedJdbcTypes' -Dsurefire.failIfNoSpecifiedTests=false test
   -> Tests run: 972, Failures: 627. Listed-cell ("must support") failures
   are 2, down from 27: getArray on ARRAY and getRef on REF, both
   PR-5. The rest are the "must reject" cells PR-6 owns.
3. ./mvnw -q -pl libsql-jdbc test
   -> Tests run: 1503, Failures: 634, Errors: 0. Every failure is in
   Jdbc4AppendixBReadTest; all 17 other test classes pass, including
   Jdbc4AppendixBSetObjectTest (B-5) at 33/0. B-3 fell from 7 to 3
   (ARRAY, STRUCT, REF).
4. ./mvnw -q spotless:check -> exit 0.

New tests in Jdbc4AppendixBReadTest: b1UrlGetterParsesAbsoluteTextAndRejectsTheRest,
b3NewWrappersReadBackTheirContent (length, substring, both streams),
b3FreedWrappersRejectFurtherReads (NClob, SQLXML, Clob, Blob), and
b3RowIdComparesAndCopiesItsBytes. LibsqlPreparedStatementTest adds
rowIdAndSqlXmlParametersBindTheirContent and
rowIdBoundAsBlobReadsBackTheSameBytes.

Live lanes and the perf probe are not run here; this PR stops at STACK-READY
for the root's swarm.

[magnusp]

Verdict: CLEAN at 4067d42. Base 0ea436c, branch task/238-pr-3-wrappers, parent PR #241.

Ten lanes PASS at the verdict head. Transcripts are under /tmp/swarm-pr-3/.

Lane	Check	Result
1	Regression against trunk	trunk throws SQLFeatureNotSupportedException from getURL; head returns the URL
2	Malformed DATALINK	SQLException: Bad value for type URL: not a url
3	getNClob	length 3, text abc
4	getSQLXML	text <a/>
5	getRowId	bytes rowid-1
6	getAsciiStream	reader abc
7	getNCharacterStream	reader abc
8	setSQLXML round trip	stored text <a/>
9	setRowId round trip	stored blob, bytes match
10	Wrapper free	reads after free throw SQLException for NClob and SQLXML

Units are 1,503 tests, 634 failures, 0 errors. B-1 is down from 7 to 3 and B-3 from 7 to 3, both leaving only the PR-5 types. The B-6 listed-cell failures are down from 27 to 2. The B-6 total rose to 627 because the new getters now answer unlisted cells that PR-5's supported-set gate must reject, which is the plan's sequence. Spotless is clean.

The integration suite at this head is 146 tests, 26 failures, down from 45 at PR-2 and 63 at the baseline. The remaining rows are the ARRAY, STRUCT, and REF types owned by PR-5.

Perf is PASS. Over 100,000 calls, getURL p99 is 1.6 microseconds and the other three new getters are under 0.1 microseconds, all far below the 50 microsecond budget. The timestamp control is unchanged within measurement noise across three interleaved rounds.

CI is red only where Appendix B is red, by design. No review-bot comments to triage.

STACK-READY. PR-4 branches from this head.

[magnusp]

Verdict correction, evidence. The stale-jar run's output was not preserved. The corrected run is the worktree failsafe report at /tmp/opencode/libsql-238/pr-3/libsql-itests/target/failsafe-reports, 146 tests and 26 failures, after installing the head. The owner's report assigned the B-6 supported-set gate to PR-6; the plan and the shipped code assign it to PR-5. That is a report wording error, not a verdict change.

[magnusp]

Superseded by #247. The verified stack tip at 0861960 landed as one commit on main (e41cac1) because the main ruleset requires green required checks at every head, and the Appendix B oracle is red until the last link. The verdict and review record on this PR are unchanged.