docs: publish canonical xerial conformance statement

Author: magnusp

libsql-conformance/README.md

@@ -4,6 +4,99 @@ This module runs a selected subset of the xerial `sqlite-jdbc` test sources agai
 libSQL over the Hrana protocol. It is a compatibility check for the JDBC driver, not a
 claim that a `jdbc:sqlite:` URL is served by a local SQLite file.
 
+## Conformance status
+
+This section is the canonical answer to "have we reached conformance with
+xerial?". The short answer is: yes for the selected subset below, verified
+against the reference probe; no for full xerial parity, and full parity is
+not the goal. The exclusions are deliberate compromises of running SQLite
+semantics remotely over Hrana, grouped below. Per-test selection, rejection,
+and divergence reasons are
+recorded in [`../upstream-xerial_sqlite-jdbc.manifest`](../upstream-xerial_sqlite-jdbc.manifest);
+this statement does not duplicate them.
+
+### Selected subset and reference probe
+
+The suite vendors the pinned xerial `sqlite-jdbc` 3.53.4.0 test tree and
+selects the tests that exercise JDBC behavior through ordinary SQL, so the
+Hrana transport can satisfy them unchanged. The manifest selects 13 test
+classes plus the shared `Utils` support class: `ResultSetTest`,
+`InsertQueryTest`, `FetchSizeTest`, `CachedRowSetTest`, `JSON1Test`,
+`MetadataLeakTest`, `PreparedStatementThreadTest`,
+`ResultSetWithoutResultsTest`, `RSMetaDataTest`, `DBMetaDataTest`,
+`StatementTest`, `PrepStmtTest`, and `SavepointTest`. The remaining 26
+classes in the pinned tree stay upstream for the reasons in the manifest. Deliberate divergences
+in a selected test, where the Hrana connection lifecycle makes the original
+behavior impossible, are recorded as `# divergence:` lines in the same
+manifest.
+
+The reference probe is the `xerial-control` Maven profile defined in
+[`pom.xml`](pom.xml): it runs the same vendored manifest against the pinned
+xerial 3.53.4.0 driver instead of the libSQL driver. Both drivers are on the test class path, so the control run removes
+every visible driver and registers the xerial driver explicitly, and the
+build rejects a hand-set `conformance.control.driver` so the probe can only
+be selected through the profile. Run it with:
+
+```bash
+./mvnw -pl libsql-conformance -am -Pxerial-control verify
+```
+
+Run the libSQL conformance suite itself, against the pinned sqld image,
+with:
+
+```bash
+./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.
+
+### Three-layer contract
+
+When the layers disagree, the contract is:
+
+1. Hrana 3 is the source of truth for transport, values, metadata,
+   batching, transactions, and error reporting. The protocol is specified
+   in [`../vendor/HRANA_3_SPEC.md`](../vendor/HRANA_3_SPEC.md); where
+   xerial behavior would require a primitive Hrana does not expose, the
+   Hrana behavior wins.
+2. `java.sql` is the source of truth for the JDBC surface. Where JDBC
+   makes a feature optional or defines the observable behavior, the
+   driver follows `java.sql`, even when xerial chooses differently.
+3. xerial is a behavioral reference and the conformance foundation, never
+   a copy target. Its tests define the selected subset and the control
+   probe; its driver internals, configuration surface, and native
+   behaviors are not reproduced.
+
+### Compromise categories
+
+Full parity is impossible without changing what the driver is: a remote
+Hrana client with no local file, no shared connection, and no native
+library. The rejected classes in the manifest group into four compromise
+categories, each with a concrete example:
+
+| Category | Why parity is impossible | Example |
+|---|---|---|
+| Native extension API | The test registers JVM callbacks or loads native code in-process; Hrana exposes no equivalent primitive, so this cannot be reversed without a new Hrana or native primitive. | `UDFTest` registers JVM user-defined functions through sqlite-jdbc's native extension API. |
+| sqlite-jdbc configuration surface | The test exercises xerial's own configuration, `DataSource`, loading, or source conventions instead of portable JDBC over SQL; libSQL provides no counterpart. | `SQLiteConfigTest` tests the `SQLiteConfig` object, not the JDBC API. |
+| Remote-model semantics | The test asserts local-file or in-process SQLite semantics (file locking and multi-connection waits, shared cache, native error wording and codes) that a single remote sqld server over Hrana cannot reproduce; see "Hrana over HTTP" in `../vendor/HRANA_3_SPEC.md` for the baton and stream-expiry model behind this. | `TransactionTest` asserts SQLite file-locking and multi-connection wait behavior. |
+| Build-flag dependence | The test passes only when the server binary is built with a compile-time option that the pinned sqld image does not guarantee; this is addressable by pinning the server build, not by driver work. | `MathFunctionsTest` requires the server binary to be compiled with `SQLITE_ENABLE_MATH_FUNCTIONS`. |
+
+The first three categories are permanent: the class stays upstream unless
+the underlying Hrana, sqld, or sqlite-jdbc surface changes. Build-flag
+dependence is the exception: the class stays upstream only until the sqld
+build is pinned to enable the flag.
+
+### Savepoint support
+
+Savepoints were the last addressable JDBC-surface gap. The driver now
+implements `Connection.setSavepoint()`, `setSavepoint(String)`,
+`rollback(Savepoint)`, and `releaseSavepoint(Savepoint)` as SQLite
+`SAVEPOINT`, `RELEASE`, and `ROLLBACK TO` statements over Hrana, and
+`DatabaseMetaData.supportsSavepoints()` returns `true`. `SavepointTest` is
+selected, so no JDBC-surface gap remains. No new server primitive was
+needed.
+
 ## URL mapping
 
 The conformance driver maps `jdbc:sqlite:` URLs to sqld namespaces so the vendored