docs: categorize rejected xerial tests in the manifest

upstream-xerial_sqlite-jdbc.manifest

@@ -11,8 +11,9 @@
 # Selection rationale. The conformance suite selects tests that exercise JDBC
 # behavior through ordinary SQL, so the Hrana transport can satisfy them
 # unchanged. Tests that drive sqlite-jdbc's native extension API, connection
-# configuration surface, or known libSQL parity gaps stay upstream. Each
-# selected and rejected class from the pinned 3.53.4.0 test tree is listed.
+# configuration surface, or known libSQL parity gaps, or that depend on a
+# server build flag, stay upstream. Each selected and rejected class from the
+# pinned 3.53.4.0 test tree is listed.
 
 # Selected support code.
 # selected: src/test/java/org/sqlite/Utils.java -- compile-option assumptions shared by selected tests; not a test class.
@@ -33,32 +34,61 @@
 # selected: src/test/java/org/sqlite/SavepointTest.java -- savepoint creation, rollback, and release over ordinary SQL.
 
 # Rejected tests.
-# rejected: src/test/java/org/sqlite/BackupTest.java -- drives sqlite-jdbc's native backup API; Hrana exposes no backup primitive.
-# rejected: src/test/java/org/sqlite/BusyHandlerTest.java -- registers native busy-handler callbacks that Hrana does not expose.
-# rejected: src/test/java/org/sqlite/CollationTest.java -- registers JVM collations through sqlite-jdbc's native extension API.
-# rejected: src/test/java/org/sqlite/ConnectionTest.java -- exercises sqlite-jdbc URL, open-mode, and resource-loading configuration that has no Hrana equivalent; covered JDBC paths are asserted by selected tests.
-# rejected: src/test/java/org/sqlite/ErrorMessageTest.java -- asserts sqlite-jdbc wording and native result codes; sqld returns different messages and error codes.
-# rejected: src/test/java/org/sqlite/ExtendedCommandTest.java -- exercises sqlite-jdbc's dot-command parser, not the JDBC API.
-# rejected: src/test/java/org/sqlite/ExtensionTest.java -- loads native SQLite extensions; the libSQL server does not permit extension loading.
-# rejected: src/test/java/org/sqlite/JDBCTest.java -- mixes driver URL handling, extension loading, and sqlite-jdbc read-only configuration; broad driver-level coverage is asserted by selected tests.
-# rejected: src/test/java/org/sqlite/ListenerTest.java -- update, commit, rollback, and authorizer hooks require native callbacks unavailable over Hrana.
-# rejected: src/test/java/org/sqlite/MathFunctionsTest.java -- passes only when the server binary was compiled with SQLITE_ENABLE_MATH_FUNCTIONS; the sqld image build is not pinned to that option.
-# rejected: src/test/java/org/sqlite/MultipleClassLoaderTest.java -- verifies sqlite-jdbc's native library loading per class loader; libSQL has no native library.
-# rejected: src/test/java/org/sqlite/ProgressHandlerTest.java -- registers native progress callbacks that Hrana does not expose.
-# rejected: src/test/java/org/sqlite/QueryTest.java -- imports sqlite-jdbc's SQLiteConfig and FastDateFormat classes and drives query timeouts; the conversion getters it exercises are covered by selected ResultSetTest cases.
-# rejected: src/test/java/org/sqlite/ReadUncommittedTest.java -- depends on sqlite-jdbc shared-cache and read-uncommitted connection configuration; sqld does not expose it.
-# rejected: src/test/java/org/sqlite/SerializeTest.java -- serializes and restores a native database image; Hrana has no equivalent.
-# rejected: src/test/java/org/sqlite/SQLiteConfigTest.java -- tests sqlite-jdbc's configuration object, not the JDBC API.
-# rejected: src/test/java/org/sqlite/SQLiteConnectionPoolDataSourceTest.java -- tests sqlite-jdbc DataSource and pooling classes that libSQL does not provide.
-# rejected: src/test/java/org/sqlite/SQLiteDataSourceTest.java -- tests sqlite-jdbc DataSource classes that libSQL does not provide.
-# rejected: src/test/java/org/sqlite/SQLiteJDBCLoaderTest.java -- tests the native SQLite library loader.
-# rejected: src/test/java/org/sqlite/TransactionTest.java -- asserts SQLite file-locking and multi-connection wait behavior that a single sqld server cannot reproduce; commit visibility is covered by InsertQueryTest.
-# rejected: src/test/java/org/sqlite/TypeMapTest.java -- #95 rejects connection type maps with SQLFeatureNotSupportedException because java.sql makes them optional, while xerial stores a map it never applies; the control run cannot assert both, so the class stays upstream.
-# rejected: src/test/java/org/sqlite/UDFCustomErrorTest.java -- registers JVM UDFs and inspects native error callbacks.
-# rejected: src/test/java/org/sqlite/UDFTest.java -- registers JVM UDFs through sqlite-jdbc's native extension API.
-# rejected: src/test/java/org/sqlite/util/OSInfoTest.java -- tests sqlite-jdbc's OS and native-library detection utility.
-# rejected: src/test/java/org/sqlite/architecture/CodingRulesTest.java -- ArchUnit rules over sqlite-jdbc source conventions; not runtime JDBC behavior.
-# rejected: src/test/java/org/sqlite/architecture/TestCodingRulesTest.java -- ArchUnit rules over sqlite-jdbc test conventions; not runtime JDBC behavior.
+# Rejection categories. Every rejected line carries one bracketed
+# category tag after "--", distinguishing permanent exclusions from
+# addressable ones that a bounded change could reverse:
+#   [permanent: native-extension-api] -- the native extension API:
+#     requires sqlite-jdbc's in-process native extension API (JVM
+#     UDFs, collations, busy/progress/listener callbacks, extension
+#     loading, native backup or serialization); Hrana exposes no
+#     equivalent, so this cannot be reversed without a new Hrana or
+#     native primitive.
+#   [permanent: sqlite-jdbc-configuration-surface] -- the
+#     sqlite-jdbc configuration surface: exercises sqlite-jdbc's
+#     configuration surface instead of portable JDBC over SQL
+#     (SQLiteConfig, DataSource and pooling classes, URL/open-mode
+#     handling, native-library loader and OS detection, dot-command
+#     parser, ArchUnit source rules); libSQL provides no counterpart.
+#   [permanent: remote-model-semantics] -- remote-model semantics:
+#     asserts local-file or in-process SQLite semantics (file locking,
+#     shared cache, native error wording and codes, or a deliberate
+#     driver-contract divergence) that a single remote sqld server
+#     over Hrana cannot reproduce.
+#   [addressable: build-flag-dependence] -- build-flag dependence:
+#     depends only on how the server binary is built; the math
+#     functions case could be selected if the sqld build enables
+#     SQLITE_ENABLE_MATH_FUNCTIONS, so it is addressable rather than
+#     permanent, with the fix being to pin that build flag.
+# Permanent means the class stays upstream unless the underlying
+# Hrana, sqld, or sqlite-jdbc surface changes; addressable means a
+# bounded build change (math functions, if the sqld build enables
+# SQLITE_ENABLE_MATH_FUNCTIONS) could reverse it.
+# rejected: src/test/java/org/sqlite/BackupTest.java -- [permanent: native-extension-api] drives sqlite-jdbc's native backup API; Hrana exposes no backup primitive.
+# rejected: src/test/java/org/sqlite/BusyHandlerTest.java -- [permanent: native-extension-api] registers native busy-handler callbacks that Hrana does not expose.
+# rejected: src/test/java/org/sqlite/CollationTest.java -- [permanent: native-extension-api] registers JVM collations through sqlite-jdbc's native extension API.
+# rejected: src/test/java/org/sqlite/ConnectionTest.java -- [permanent: sqlite-jdbc-configuration-surface] exercises sqlite-jdbc URL, open-mode, and resource-loading configuration that has no Hrana equivalent; covered JDBC paths are asserted by selected tests.
+# rejected: src/test/java/org/sqlite/ErrorMessageTest.java -- [permanent: remote-model-semantics] asserts sqlite-jdbc wording and native result codes; sqld returns different messages and error codes.
+# rejected: src/test/java/org/sqlite/ExtendedCommandTest.java -- [permanent: sqlite-jdbc-configuration-surface] exercises sqlite-jdbc's dot-command parser, not the JDBC API.
+# rejected: src/test/java/org/sqlite/ExtensionTest.java -- [permanent: native-extension-api] loads native SQLite extensions; the libSQL server does not permit extension loading.
+# rejected: src/test/java/org/sqlite/JDBCTest.java -- [permanent: sqlite-jdbc-configuration-surface] mixes driver URL handling, extension loading, and sqlite-jdbc read-only configuration; broad driver-level coverage is asserted by selected tests.
+# rejected: src/test/java/org/sqlite/ListenerTest.java -- [permanent: native-extension-api] update, commit, rollback, and authorizer hooks require native callbacks unavailable over Hrana.
+# rejected: src/test/java/org/sqlite/MathFunctionsTest.java -- [addressable: build-flag-dependence] passes only when the server binary was compiled with SQLITE_ENABLE_MATH_FUNCTIONS; the sqld image build is not pinned to that option, so this could be selected if the sqld build is pinned to enable SQLITE_ENABLE_MATH_FUNCTIONS (math functions).
+# rejected: src/test/java/org/sqlite/MultipleClassLoaderTest.java -- [permanent: sqlite-jdbc-configuration-surface] verifies sqlite-jdbc's native library loading per class loader; libSQL has no native library.
+# rejected: src/test/java/org/sqlite/ProgressHandlerTest.java -- [permanent: native-extension-api] registers native progress callbacks that Hrana does not expose.
+# rejected: src/test/java/org/sqlite/QueryTest.java -- [permanent: sqlite-jdbc-configuration-surface] imports sqlite-jdbc's SQLiteConfig and FastDateFormat classes and drives query timeouts; the conversion getters it exercises are covered by selected ResultSetTest cases.
+# rejected: src/test/java/org/sqlite/ReadUncommittedTest.java -- [permanent: remote-model-semantics] depends on sqlite-jdbc shared-cache and read-uncommitted connection configuration; sqld does not expose it.
+# rejected: src/test/java/org/sqlite/SerializeTest.java -- [permanent: native-extension-api] serializes and restores a native database image; Hrana has no equivalent.
+# rejected: src/test/java/org/sqlite/SQLiteConfigTest.java -- [permanent: sqlite-jdbc-configuration-surface] tests sqlite-jdbc's configuration object, not the JDBC API.
+# rejected: src/test/java/org/sqlite/SQLiteConnectionPoolDataSourceTest.java -- [permanent: sqlite-jdbc-configuration-surface] tests sqlite-jdbc DataSource and pooling classes that libSQL does not provide.
+# rejected: src/test/java/org/sqlite/SQLiteDataSourceTest.java -- [permanent: sqlite-jdbc-configuration-surface] tests sqlite-jdbc DataSource classes that libSQL does not provide.
+# rejected: src/test/java/org/sqlite/SQLiteJDBCLoaderTest.java -- [permanent: sqlite-jdbc-configuration-surface] tests the native SQLite library loader.
+# rejected: src/test/java/org/sqlite/TransactionTest.java -- [permanent: remote-model-semantics] asserts SQLite file-locking and multi-connection wait behavior that a single sqld server cannot reproduce; commit visibility is covered by InsertQueryTest.
+# rejected: src/test/java/org/sqlite/TypeMapTest.java -- [permanent: remote-model-semantics] #95 rejects connection type maps with SQLFeatureNotSupportedException because java.sql makes them optional, while xerial stores a map it never applies; the control run cannot assert both, so the class stays upstream.
+# rejected: src/test/java/org/sqlite/UDFCustomErrorTest.java -- [permanent: native-extension-api] registers JVM UDFs and inspects native error callbacks.
+# rejected: src/test/java/org/sqlite/UDFTest.java -- [permanent: native-extension-api] registers JVM UDFs through sqlite-jdbc's native extension API.
+# rejected: src/test/java/org/sqlite/util/OSInfoTest.java -- [permanent: sqlite-jdbc-configuration-surface] tests sqlite-jdbc's OS and native-library detection utility.
+# rejected: src/test/java/org/sqlite/architecture/CodingRulesTest.java -- [permanent: sqlite-jdbc-configuration-surface] ArchUnit rules over sqlite-jdbc source conventions; not runtime JDBC behavior.
+# rejected: src/test/java/org/sqlite/architecture/TestCodingRulesTest.java -- [permanent: sqlite-jdbc-configuration-surface] ArchUnit rules over sqlite-jdbc test conventions; not runtime JDBC behavior.
 
 # First conformance batch.
 src/test/java/org/sqlite/Utils.java