feat(jdbc): comply with JDBC 4.3 Appendix B type mapping (#247)

## Why

The driver mapped result values by storage class, so the declared type
did not control metadata or `getObject`, and `setObject` ignored the
target type. JDBC 4.3 Appendix B is the oracle. Seven stacked pull
requests implement it. The stack cannot land link by link because the
`main` ruleset requires the full build green at every head, and the
Appendix B oracle is red until the last link. This PR lands the verified
tip as one commit.

## What changed

- Add the Appendix B oracle suite and the vendor table, then resolve one
JDBC type per declared column for metadata and `getObject`.
- Honor the `setObject` target type, add the missing getters and LOB
wrappers, and support the offset temporal types.
- Mark `ARRAY`, `STRUCT`, `REF`, `JAVA_OBJECT`, and `DISTINCT` N/A and
reject unlisted Table B-6 conversions.
- Publish the compliance profile, quarantine the four xerial tests that
conflict with the spec, and record the policy.

## Scope

The seven stacked PRs are #239, #240, #241, #242, #243, #244, and #245.
No unrelated changes. `vendor/JDBC4-TYPE-MAPPING.md` is the oracle.

## Tradeoffs

- The five unrepresentable types throw instead of emulating them.
- The conformance quarantine is method-level. The lost checks are named
in `libsql-conformance/README.md`.
- An expression column with no `decltype` keeps the storage fallback,
documented as a profile exception.

## Blast Radius

Metadata and `getObject` now follow the declared type, so a `BIGINT`
holding 42 returns `Long`, and an unlisted getter conversion throws. The
default build was red from #239 through #245 by design and is green at
this tip.

## Verification

- `clean verify` at `0861960`: 2,006 tests, 0 failures, 7 skipped, about
63 seconds.
- Appendix B unit 1,050 of 1,050, integration 148 of 148, conformance
270 of 270 with 7 skipped.
- Clean clone at the same SHA: unit 1,510 of 1,510, integration 148 of
148.
- Each link has a verdict and ten live lanes. The verdict comments are
on #239 through #245.

Author: magnusp

AGENTS.md

@@ -134,6 +134,17 @@ DOCKER_CONFIG="$PWD/libsql-conformance/src/test/docker-config" \
 
 Use the absolute path shown. A relative `DOCKER_CONFIG` is resolved against the fork's working directory, not the shell's.
 
+### JDBC 4.3 Appendix B policy
+
+JDBC 4.3 Appendix B is the oracle for type mapping. The source is [`vendor/JDBC4-TYPE-MAPPING.md`](vendor/JDBC4-TYPE-MAPPING.md).
+
+- When Appendix B and sqlite-jdbc disagree, Appendix B wins. A conformance test that encodes the xerial behavior is quarantined in `libsql-conformance`, not copied.
+- Keep sqlite-jdbc parity only where Appendix B is silent. Parity never overrides a defined Appendix B conversion.
+- `ARRAY`, `STRUCT`, `REF`, `JAVA_OBJECT`, and `DISTINCT` are N/A. The driver throws `SQLFeatureNotSupportedException` and does not emulate them.
+- An expression column has no declared type. Its storage-class fallback is a documented exception in [`docs/jdbc-appendix-b-compliance.md`](docs/jdbc-appendix-b-compliance.md), not a supported Appendix B row.
+
+The compliance profile is [`docs/jdbc-appendix-b-compliance.md`](docs/jdbc-appendix-b-compliance.md). Run the commands in [`README.md`](README.md) before changing a type mapping.
+
 ---
 
 ## 5. Coding Standards & Conventions

README.md

@@ -84,6 +84,41 @@ mise exec -- ./mvnw clean verify
 mise exec -- ./mvnw spotless:apply
 ```
 
+### JDBC 4.3 Appendix B checks
+
+Run the Appendix B unit suite.
+
+```bash
+./mvnw -q -pl libsql-jdbc -Dtest='Jdbc4AppendixB*' -Dsurefire.failIfNoSpecifiedTests=false test
+```
+
+Run the full `libsql-jdbc` unit suite.
+
+```bash
+./mvnw -q -pl libsql-jdbc test
+```
+
+Run the Appendix B server suite. The install step puts the current driver in the local repository. Under the nono sandbox, the Docker config path is required.
+
+```bash
+./mvnw -q -DskipTests install -pl libsql-hrana-codec,libsql-client,libsql-jdbc
+DOCKER_CONFIG="$PWD/libsql-conformance/src/test/docker-config" ./mvnw -pl libsql-itests -Dit.test=Jdbc4AppendixBTypeMappingIT -Dtest=NoSuchTest -Dsurefire.failIfNoSpecifiedTests=false verify
+```
+
+Run the xerial conformance suite.
+
+```bash
+./mvnw -pl libsql-conformance -am verify
+```
+
+Run the full gate.
+
+```bash
+DOCKER_CONFIG="$PWD/libsql-conformance/src/test/docker-config" ./mvnw clean verify
+```
+
+The compliance profile is in [`docs/jdbc-appendix-b-compliance.md`](docs/jdbc-appendix-b-compliance.md).
+
 ## Contributing
 
 We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines and development workflow, and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for community standards.

docs/jdbc-appendix-b-compliance.md

@@ -47,8 +47,32 @@ with:
 ./mvnw -pl libsql-conformance -am verify
 ```
 
-Last green result: 272 tests, 7 skipped, with `SavepointTest` included. The
-parity queue (#54) closed at 268 tests, 7 skipped.
+Last green result: 270 tests, 7 skipped, with `SavepointTest` included. The
+count excludes the four Appendix B quarantines below and includes the two
+harness tests for the quarantine.
+
+### Appendix B quarantines
+
+JDBC 4.3 Appendix B is the oracle. Four selected xerial test methods assert
+behavior that Appendix B replaces. They stay in the vendored tree and still
+run in the `xerial-control` profile, but `XerialQuarantine` excludes them from
+the libSQL run. The full type profile is in
+[`../docs/jdbc-appendix-b-compliance.md`](../docs/jdbc-appendix-b-compliance.md).
+
+| Test | Why the xerial expectation is quarantined |
+|---|---|
+| `org.sqlite.StatementTest#bytesTest` | xerial allows `getBytes` on a declared `BLOB`. Table B-6 lists `getBytes` only for `BINARY`, `VARBINARY`, and `LONGVARBINARY`. |
+| `org.sqlite.RSMetaDataTest#columnTypes` | xerial reports a declared `NCHAR` as `Types.CHAR`. Appendix B defines `NCHAR` as its own JDBC type, so the driver reports `Types.NCHAR`. |
+| `org.sqlite.RSMetaDataTest#testGetColumnClassName` | xerial reports a declared `BLOB` as `java.lang.Object`. Table B-3 maps `BLOB` to `java.sql.Blob`. |
+| `org.sqlite.PrepStmtTest#getObject` | xerial returns an `Integer` for `getObject` on a declared `BIT`. Table B-3 maps `BIT` to `Boolean`. |
+
+The exclusion is method-level, so each method also loses checks that do not
+conflict with Appendix B:
+
+- `StatementTest#bytesTest` also loses its BLOB `setBytes`/`getBytes` round trip.
+- `RSMetaDataTest#columnTypes` also checks other column types that do not conflict, including the INTEGER family, text, numeric, boolean, date and timestamp types, plus DECIMAL precision and scale.
+- `RSMetaDataTest#testGetColumnClassName` also checks the INTEGER, VARCHAR, and DOUBLE class names.
+- `PrepStmtTest#getObject` also checks other `getObject` rows (INTEGER, FLOAT, untyped, VARCHAR and BLOB columns) and the typed getters above them.
 
 ### Three-layer contract
 

libsql-conformance/README.md

@@ -16,6 +16,8 @@
 import java.util.concurrent.atomic.AtomicInteger;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.io.TempDir;
+import org.junit.platform.engine.TestDescriptor;
+import org.junit.platform.engine.support.descriptor.MethodSource;
 
 /**
  * Exercises the conformance harness itself, without a running sqld container where possible.
@@ -63,6 +65,54 @@ void fileMemoryUriIsNotRetained() {
         assertThat(memoryMode.retained()).isFalse();
     }
 
+    @Test
+    void quarantineExcludesOnlyTheAppendixBConflicts() {
+        XerialQuarantine quarantine = new XerialQuarantine();
+
+        for (XerialQuarantine.Quarantined quarantined : XerialQuarantine.QUARANTINED) {
+            assertThat(
+                            quarantine
+                                    .apply(
+                                            descriptor(
+                                                    quarantined.className(),
+                                                    quarantined.methodName()))
+                                    .excluded())
+                    .as("%s#%s", quarantined.className(), quarantined.methodName())
+                    .isTrue();
+        }
+
+        assertThat(quarantine.apply(descriptor("org.sqlite.ResultSetTest", "next")).included())
+                .as("an unconflicted xerial test")
+                .isTrue();
+    }
+
+    @Test
+    void quarantineIsInactiveDuringTheXerialControlRun() {
+        String previous = System.getProperty(XerialControl.ENABLED_PROPERTY);
+        System.setProperty(XerialControl.ENABLED_PROPERTY, "xerial");
+        try {
+            XerialQuarantine quarantine = new XerialQuarantine();
+            for (XerialQuarantine.Quarantined quarantined : XerialQuarantine.QUARANTINED) {
+                assertThat(
+                                quarantine
+                                        .apply(
+                                                descriptor(
+                                                        quarantined.className(),
+                                                        quarantined.methodName()))
+                                        .included())
+                        .as("control run keeps %s#%s", quarantined.className(),
+                                quarantined.methodName())
+                        .isTrue();
+            }
+        } finally {
+            if (previous == null) {
+                System.clearProperty(XerialControl.ENABLED_PROPERTY);
+            } else {
+                System.setProperty(XerialControl.ENABLED_PROPERTY, previous);
+            }
+        }
+    }
+
     @Test
     void queryStringIsPartOfTheFileNamespace() {
         XerialConformanceDriver.Target readOnly =
@@ -163,6 +213,19 @@ void stopReportsASwallowedCleanupFailure() {
         }
     }
 
+    private static TestDescriptor descriptor(String className, String methodName) {
+        MethodSource source = MethodSource.from(className, methodName);
+        return (TestDescriptor)
+                Proxy.newProxyInstance(
+                        TestDescriptor.class.getClassLoader(),
+                        new Class<?>[] {TestDescriptor.class},
+                        (proxy, method, args) ->
+                                switch (method.getName()) {
+                                    case "getSource" -> java.util.Optional.of(source);
+                                    default -> null;
+                                });
+    }
+
     private static Connection wrap(Connection connection, String namespace) {
         return wrap(connection, namespace, ignored -> {});
     }

libsql-conformance/src/test/java/com/github/magnusp/libsql/conformance/XerialHarnessTest.java

@@ -0,0 +1,59 @@
+package com.github.magnusp.libsql.conformance;
+
+import java.util.List;
+import org.junit.platform.engine.FilterResult;
+import org.junit.platform.engine.TestDescriptor;
+import org.junit.platform.engine.support.descriptor.MethodSource;
+import org.junit.platform.launcher.PostDiscoveryFilter;
+
+/**
+ * Quarantines the xerial tests whose expectations Appendix B replaces.
+ *
+ * <p>These tests assert sqlite-jdbc behavior that JDBC 4.3 Appendix B defines differently. They
+ * stay in the vendored tree and still run in the {@code xerial-control} profile, where the
+ * reference driver is the subject. They are excluded only from the libSQL run, and the reason is
+ * kept here so the exclusion cannot become an unexplained skip.
+ */
+public final class XerialQuarantine implements PostDiscoveryFilter {
+
+    /** One upstream test method whose xerial expectation conflicts with Appendix B. */
+    record Quarantined(String className, String methodName, String reason) {}
+
+    static final List<Quarantined> QUARANTINED =
+            List.of(
+                    new Quarantined(
+                            "org.sqlite.StatementTest",
+                            "bytesTest",
+                            "xerial allows getBytes on a declared BLOB; Table B-6 lists getBytes"
+                                    + " only for BINARY, VARBINARY and LONGVARBINARY"),
+                    new Quarantined(
+                            "org.sqlite.RSMetaDataTest",
+                            "columnTypes",
+                            "xerial reports a declared NCHAR as Types.CHAR; Appendix B defines"
+                                    + " NCHAR as its own JDBC type, so the driver reports Types.NCHAR"),
+                    new Quarantined(
+                            "org.sqlite.RSMetaDataTest",
+                            "testGetColumnClassName",
+                            "xerial reports a declared BLOB as java.lang.Object; Table B-3 maps"
+                                    + " BLOB to java.sql.Blob"),
+                    new Quarantined(
+                            "org.sqlite.PrepStmtTest",
+                            "getObject",
+                            "xerial returns an Integer for getObject on a declared BIT; Table B-3"
+                                    + " maps BIT to Boolean"));
+
+    @Override
+    public FilterResult apply(TestDescriptor descriptor) {
+        if (XerialControl.isEnabled()
+                || !(descriptor.getSource().orElse(null) instanceof MethodSource source)) {
+            return FilterResult.included("Appendix B quarantine is inactive for this run");
+        }
+        for (Quarantined quarantined : QUARANTINED) {
+            if (quarantined.className().equals(source.getClassName())
+                    && quarantined.methodName().equals(source.getMethodName())) {
+                return FilterResult.excluded(quarantined.reason());
+            }
+        }
+        return FilterResult.included("not quarantined");
+    }
+}

libsql-conformance/src/test/java/com/github/magnusp/libsql/conformance/XerialQuarantine.java

@@ -0,0 +1 @@
+com.github.magnusp.libsql.conformance.XerialQuarantine