Merge feature/nitrite-bridge, and release 5.2.0

Brings in `nitrite-bridge`, the Nitrite adapter for the dbinspect wire
protocol, together with the skip-without-decoding paging work the branch also
carried.

The module is deliberately outside the reactor `<modules>` —
`org.dizitart:dbinspect-bridge` is not on Maven Central until the dbinspect
release, so a build of a clean checkout would fail on it. Build it on its own
with `dbinspect-bridge` installed locally.

Everything goes to 5.2.0. CHANGELOG.md carries the detail. Reactor green
(1634 + 93 + 104 tests), bridge green (76 tests) over MVStore, RocksDB and
in-memory.

Author: anidotnet

CHANGELOG.md

@@ -1,3 +1,32 @@
+## Release 5.2.0 - Aug 30, 2026
+
+### New Features
+
+- **`nitrite-bridge` — inspect a running Nitrite database from a desktop client.** The Nitrite adapter for the `dbinspect` wire protocol: collections and handed-in repositories as browsable stores, schema inferred by sampling documents and always flagged as inferred, paging over `FindOptions` skip/limit/orderBy, the JSON filter DSL, and watch over Nitrite's collection subscription. The engine-neutral core it plugs into is `org.dizitart:dbinspect-bridge`, which has no database in its dependency tree at all.
+  - **Row editing is behind `allowWrite`, and whole-store `snapshot` behind `allowSnapshot`** — both `false` unless the embedding application asks, and absent from the reported capabilities while they are. A row is addressed by `_id`; an update is partial; `changes: 0` means the row was not there. `_id` inside an update's `values` is refused, because Nitrite merges an update document and it would rewrite the identity of the row it just matched.
+  - **`regex` is off unless `allowRegex` is set**, and length-capped with a nested-quantifier check when it is on. `java.util.regex` backtracks and a match cannot be interrupted, so the default is the mitigation that matters.
+  - Every client-supplied store name is resolved against the set the adapter reported. `Nitrite.getCollection` creates a collection that does not exist, so an unchecked name would let a paired client make one; writes go through the same allow-list.
+  - The module is deliberately **absent from the reactor `<modules>`**: `dbinspect-bridge` is not on Maven Central until the dbinspect release, so a build of a clean checkout would fail on it. Build it on its own, with `dbinspect-bridge` installed locally.
+
+- **The bridge can open a transaction** (`docs/PROTOCOL.md` §3.1). A transaction is a second adapter over the same database rather than a mode on the first, so one connection's uncommitted documents can never reach another connection's reads. Nitrite's transaction lives above the storage engine — a `TransactionStore` buffers the writes and a journal replays them on commit — so this works identically on MVStore, RocksDB and in memory.
+  - `capabilities.transactions` follows `allowWrite`: that flag is the permission, this reports what the engine can undo. The transactional twin reports it `false`, because Nitrite does not nest one.
+  - `listStores` counts through the transaction, since a total that left out the rows the person just staged is not read-your-own-writes.
+
+### Performance
+
+- Paging a collection no longer costs every row before the page - `find(filter, skipBy(n).limit(m))` now advances the storage iterator without decoding what it passes over.
+  - `BoundedStream` skipped by calling `next()` on the iterator beneath it, and that iterator is below the document layer: it deserialised **every skipped document** in order to throw it away. Page latency was therefore linear in the page number - about 9 µs per skipped row on both persistent stores - so a 50 000-row collection paged at 200 rows took 3 ms for the first page and 350 ms for the two-hundredth. It is an ordinary browse, not an edge case.
+  - New `SkippableIterator`, implemented by the storage-level iterators that can do better and by nothing else. `BoundedStream` uses it when it is there and falls back to the loop when it is not, so a stream that has to look at a document to know whether to skip it - a collection-scan filter, a blocking sort - is unaffected and still correct.
+  - **MVStore descends the tree by index.** An MVStore page records how many entries sit beneath it, so `MVMap.getKey(n)` is a O(log n) descent rather than a scan; the skip seeks with it and continues from a cursor. Measured over 50 000 rows, 200 to a page: p95 **583.9 ms → 5.8 ms**, and the first and last pages now cost the same 0.1 ms.
+  - **RocksDB steps the native iterator.** There is no seek-by-index to use, but the decode is what a skipped row actually cost; advancing past one is now a memcmp inside the block the iterator is already on. p95 **3.8 ms** over the same 50 000 rows.
+  - An index scan skips its own id set the same way, without the map lookup and decode `next()` would have paid for each row.
+
+### Issue Fixes
+
+- Fix the index dirty marker not being persisted ([#1281](https://github.com/nitrite/nitrite-java/pull/1281))
+  - `markDirty()` flipped `isDirty` on the `IndexMeta` that `get()` returned and never put it back, so nothing told the store the entry had changed and the new value was not guaranteed to be written. Both `beginIndexing()` and `endIndexing()` go through it, so the marker was unreliable in both directions: an index left half-built by a crash could come back reading as clean, and a completed one could stay marked dirty and be rebuilt on the first write after every open.
+
+
 ## Release 5.1.0 - Aug 22, 2026
 
 ### Improvements

nitrite-bom/pom.xml

@@ -4,7 +4,7 @@
     <parent>
         <groupId>org.dizitart</groupId>
         <artifactId>nitrite-java</artifactId>
-        <version>5.1.0</version>
+        <version>5.2.0</version>
     </parent>
 
     <artifactId>nitrite-bom</artifactId>

nitrite-bridge/README.md

@@ -0,0 +1,90 @@
+# nitrite-bridge
+
+Inspect a running Nitrite database from a desktop client, over a paired, loopback-by-default
+connection.
+
+This artifact is the **Nitrite adapter only**. The wire protocol, pairing, transport and the
+release guard are in `org.dizitart:dbinspect-bridge`, which knows about no database at all — so a
+JVM developer inspecting an H2, MapDB or JDBC database takes that artifact and writes their own
+adapter, and nothing about that path routes through a Nitrite repository.
+
+```java
+BridgeServer bridge = DbInspect.start(
+    DbInspect.options("my_app", List.of(
+        NitriteAdapter.builder(db, "main", "app data")
+            .repositories(orders, customers)
+            .build())));
+```
+
+## Two things to know before you ship it
+
+**Declare `INTERNET`.** A bridge binds a socket; on Android, without the permission it fails with
+a `SecurityException` that reads like a bug in us.
+
+**Keep it out of your release build.** Everything below is off unless you turn it on, but the
+strongest guard is the artifact not being there at all:
+
+- **Desktop** — `provided` scope, *and* `-Ddbinspect.bridge.enabled=true` at launch. Two signals,
+  neither of which survives into a production launch script by accident.
+- **Android** — `debugImplementation`. An application has no command line, so the system property
+  can never be set and a guard requiring it could never be satisfied; the packaging is the guard,
+  which is a stronger property rather than a weaker one. R8 shrinking is **not** the guard.
+
+Both example applications carry a script that greps the built artifact for the protocol strings,
+and both build twice so the check has a negative control.
+
+## Capabilities, and what is off by default
+
+`edit`, `snapshot` and `regex` are off unless you asked for them on that adapter — `allowWrite`,
+`allowSnapshot`, `allowRegex` on the builder. What is off is *absent from the reported
+capabilities*, not merely refused at call time, so the client greys it out rather than offering
+something that will fail.
+
+**A row is addressed by `_id`.** With `allowWrite(true)`, `updateRow` and `deleteRow` take the
+value the grid showed in that column — a `long` here, and the bracketed `[1755…]NO₂` rendering is
+accepted too, so an id pasted from another runtime's grid works. `_id` inside an update's `values`
+is refused: Nitrite merges an update document, so it would rewrite the identity of the row it just
+matched. An update is partial, and `changes: 0` means the row was not there, which is an answer
+rather than an error.
+
+`capabilities.filterOps` reports what this implementation actually has. Two notes on it:
+
+- **`exists` needs nitrite 5.0.0**, which is the floor this artifact sets. It tests presence only:
+  a field explicitly set to null is present and matches, and "does not have the field" is `not`
+  around it, never `exists` with `value: false`.
+- **`text` needs a full-text index on the field.** Nitrite's own query planner refuses a text
+  filter it cannot serve from an index, and `filterOps` is a flat operator list that cannot say
+  "text, but only on `bio`". The adapter refuses per field, with a message that names the fix.
+
+## Repositories are handed in; collections are discovered
+
+`listRepositories()` answers with entity names, and an entity name is not a `Class`. Turning one
+back into a type means loading a class named by a paired client, and the underlying document
+collection cannot be reached by name either — `getCollection` refuses a name a repository owns,
+and re-opening the map behind one would give you a second collection object with its own event
+bus, so `watch` would silently never fire.
+
+So pass the repositories you want inspected. One that was not passed in is not listed, rather than
+listed and unopenable.
+
+## Building it
+
+`dbinspect-bridge` is not on Maven Central yet, so this module is deliberately **not** in
+`nitrite-java`'s `<modules>` — a clean checkout could not resolve it and the whole reactor would
+fail. Install the core, then build this on its own:
+
+```bash
+mvn -f <dbinspect>/jvm/dbinspect-bridge/pom.xml install
+mvn -f nitrite-bridge/pom.xml test
+```
+
+## Examples
+
+| Path | What it is |
+|---|---|
+| `example/` | a plain `java -jar` desktop application, and `tool/verify_release_jar.sh` |
+| `example-android/` | a native Android (Kotlin) application, and `tool/verify_release_apk.sh` |
+
+Both are browsable from the desktop client, and the dbinspect conformance suite passes unmodified
+against either. `tool/run_reference_bridge.sh` starts a bridge over a memory, MVStore or RocksDB
+database for the suite to be pointed at.

nitrite-bridge/example-android/app/MinSdk.md

@@ -0,0 +1,48 @@
+# minSdk 26, and what pinned it
+
+`PLAN.md` §6 M3 asks for a floor set by measurement rather than assumption, and for the finding
+that set it. Here is both. Measured 2026-08-06 with AGP 8.9.1, Gradle 9.2, `desugar_jdk_libs`
+2.1.5 and core library desugaring on.
+
+The measurement is `assembleRelease` at each candidate level: D8 refuses to dex what it cannot
+desugar, so the floor is a build failure rather than a runtime surprise.
+
+| minSdk | this app (Nitrite + MVStore + bridge) | bridge without MVStore |
+|---|---|---|
+| 21 | **fails to dex** | dexes |
+| 24 | **fails to dex** | dexes |
+| 26 | dexes | dexes |
+
+## What sets it, and it is not what the plan expected
+
+The plan predicted the gap would be in `java.nio` / `java.time`, since that is where desugaring
+usually falls short of Java 11. It is not. Every one of the four errors is the same shape:
+
+```
+D8: MethodHandle.invoke and MethodHandle.invokeExact are only supported starting with
+    Android O (--min-api 26): Lorg/h2/util/Bits;uuidToBytes(JJ)[B
+```
+
+…and all four are in **`h2-mvstore`**, the storage engine behind `nitrite-mvstore-adapter`:
+`Bits.uuidToBytes`, `AES.encryptBlock`, `AES.decryptBlock`, `SHA256.getPBKDF2`. H2 reaches for
+`VarHandle`/`MethodHandle` polymorphic signatures for byte access, and a polymorphic signature is
+not something desugaring can rewrite — the call is resolved by the VM, so Android O is the floor
+and no library version of ours moves it.
+
+**So the floor is the store, not the bridge.** `dbinspect-bridge` (Java-WebSocket, Gson, slf4j),
+`nitrite-bridge` and Nitrite's own core all dex cleanly at API 21 with desugaring on. If a future
+Android target needs to go below 26, the question to ask is which store it uses, not what the
+bridge does — and the answer is likely the in-memory store or a different adapter, since
+`nitrite-rocksdb-adapter` carries a native library that has no Android build at all.
+
+## What this does not prove
+
+Dexing is not running. The app was run on an API 37 emulator (Pixel 10 Pro XL) and the M1
+conformance suite passes against it unmodified over `adb forward` — 111 checks, 108 passed, 0
+failed, 3 skipped. **API 26 itself has not been run**: no API 26 system image is installed on the
+build machine. Dexing at 26 is a hard floor for the artifact and running at 37 shows the bridge
+works on the platform, but a run on an API 26 image is what would close this properly, and it is
+one `sdkmanager` download away.
+
+`animal-sniffer` in `nitrite-bridge`'s own build checks its sources against the API 26 signature
+on every `mvn test`, so a regression in the adapter itself fails there rather than here.

nitrite-bridge/example-android/app/build.gradle.kts

@@ -0,0 +1,54 @@
+plugins {
+    id("com.android.application")
+    id("org.jetbrains.kotlin.android")
+}
+
+android {
+    namespace = "org.dizitart.example.android"
+    compileSdk = 35
+
+    defaultConfig {
+        applicationId = "org.dizitart.example.android"
+        // See MinSdk.md beside this file. Not a guess and not yet a measurement either — the
+        // number is what the artifacts on the compile path require; PLAN.md M3 asks for a run.
+        minSdk = 26
+        targetSdk = 35
+        versionCode = 1
+        versionName = "1.0"
+    }
+
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_11
+        targetCompatibility = JavaVersion.VERSION_11
+        // dbinspect-bridge is Java 11 and uses java.time and java.nio; below API 26 those are
+        // only there through desugaring, which is why this is on rather than assumed away.
+        isCoreLibraryDesugaringEnabled = true
+    }
+
+    kotlinOptions {
+        jvmTarget = "11"
+    }
+
+    buildTypes {
+        release {
+            // Deliberately off. THREAT-MODEL §7 criterion 2 must hold because the bridge is not
+            // in the variant at all, not because R8 happened to shrink it away — R8 is
+            // configurable away and is not the guard (see DbInspect#bridgeEnabled).
+            isMinifyEnabled = false
+        }
+    }
+}
+
+dependencies {
+    implementation("org.dizitart:nitrite:5.0.0")
+    implementation("org.dizitart:nitrite-mvstore-adapter:5.0.0")
+
+    // THE release guard on Android. An application has no command line, so the system property
+    // -Ddbinspect.bridge.enabled can never be set and a guard requiring it could never be
+    // satisfied; the packaging is the guard instead, and it is a stronger property than a runtime
+    // flag rather than a weaker one. src/release/ carries a no-op DebugTools so that nothing in
+    // the release variant so much as names a bridge class.
+    debugImplementation("org.dizitart:nitrite-bridge:5.0.0")
+
+    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.5")
+}

nitrite-bridge/example-android/app/src/debug/AndroidManifest.xml

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+
+    <!--
+        mDNS only, and only in the debug variant. NsdManager needs a held multicast lock to see
+        anything on most handsets, and the lock needs these two. adb forward is the primary path
+        on Android and needs none of it, so a developer who never turns mDNS on loses nothing.
+    -->
+    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
+    <uses-permission android:name="android.permission.CHANGE_WIFI_MULTICAST_STATE" />
+</manifest>

nitrite-bridge/example-android/app/src/debug/java/org/dizitart/example/android/DebugTools.kt

@@ -0,0 +1,107 @@
+package org.dizitart.example.android
+
+import android.content.Context
+import android.net.nsd.NsdManager
+import android.net.nsd.NsdServiceInfo
+import android.net.wifi.WifiManager
+import android.util.Log
+import org.dizitart.dbinspect.BridgeAdapter
+import org.dizitart.dbinspect.BridgeServer
+import org.dizitart.dbinspect.DbInspect
+import org.dizitart.no2.Nitrite
+import org.dizitart.no2.bridge.NitriteAdapter
+import java.security.SecureRandom
+
+/**
+ * Everything this application knows about dbinspect, in the debug variant only.
+ *
+ * `src/release/` has a file with this name that returns null and names nothing, so [MainActivity]
+ * calls one signature and the packaging decides which one exists. See app/build.gradle.kts.
+ *
+ * **The primary path on Android is `adb forward`, not mDNS**, and that needs nothing from this
+ * file — the bridge binds loopback and `adb forward tcp:<local> tcp:<bridge>` reaches it. mDNS is
+ * opt-in and secondary, and it is here because PLAN.md M3 asks for `NsdManager` rather than JmDNS
+ * on this platform, with a multicast lock held.
+ */
+object DebugTools {
+
+    private const val TAG = "dbinspect"
+
+    /** Set to true to also advertise on the local network. Off is the default for a reason. */
+    private const val ADVERTISE_OVER_MDNS = false
+
+    fun start(context: Context, db: Nitrite): String? {
+        val adapters: List<BridgeAdapter> =
+            listOf(NitriteAdapter.builder(db, "nitrite-main", "example.db").build())
+
+        // bridgeEnabled() is true on Dalvik/ART by construction: an application has no command
+        // line, so the desktop system property could never be set and a guard requiring it could
+        // never be satisfied. On this platform the packaging above is the guard.
+        val bridge = DbInspect.start(DbInspect.options("example_app", adapters, android.os.Build.MODEL))
+            ?: return null
+
+        if (ADVERTISE_OVER_MDNS) {
+            advertise(context, bridge)
+        }
+
+        Log.i(TAG, bridge.banner())
+        return buildString {
+            append("dbinspect is listening\n\n")
+            append("pairing code   ").append(bridge.pairingCode().value()).append('\n')
+            append("port           ").append(bridge.port()).append("\n\n")
+            append("adb forward tcp:").append(bridge.port())
+                .append(" tcp:").append(bridge.port())
+        }
+    }
+
+    /**
+     * NsdManager, with a multicast lock held for as long as the advertisement is up.
+     *
+     * Without the lock most handsets drop multicast frames while the screen is off and some drop
+     * them always, which presents as "the device never appears" with nothing in any log.
+     *
+     * The TXT record carries a random per-session instance name and `proto`, and nothing else —
+     * PROTOCOL.md §1: appName, deviceModel, bridgeVersion and the adapter list are answered after
+     * pairing, because advertising them unauthenticated hands every peer on the subnet a target
+     * list and a version number to look up.
+     */
+    private fun advertise(context: Context, bridge: BridgeServer) {
+        val wifi = context.applicationContext.getSystemService(Context.WIFI_SERVICE) as WifiManager
+        val lock = wifi.createMulticastLock("dbinspect").apply {
+            setReferenceCounted(false)
+            acquire()
+        }
+
+        val random = SecureRandom()
+        val instance = (0 until 8)
+            .map { "abcdefghijklmnopqrstuvwxyz0123456789"[random.nextInt(36)] }
+            .joinToString("")
+
+        val service = NsdServiceInfo().apply {
+            serviceName = instance
+            serviceType = "_dbinspect._tcp"
+            port = bridge.port()
+            setAttribute("proto", "1")
+        }
+
+        val manager = context.getSystemService(Context.NSD_SERVICE) as NsdManager
+        manager.registerService(service, NsdManager.PROTOCOL_DNS_SD, object : NsdManager.RegistrationListener {
+            override fun onServiceRegistered(info: NsdServiceInfo) {
+                Log.i(TAG, "advertising as ${info.serviceName}")
+            }
+
+            override fun onRegistrationFailed(info: NsdServiceInfo, errorCode: Int) {
+                Log.w(TAG, "mDNS registration failed: $errorCode")
+                lock.release()
+            }
+
+            override fun onServiceUnregistered(info: NsdServiceInfo) {
+                lock.release()
+            }
+
+            override fun onUnregistrationFailed(info: NsdServiceInfo, errorCode: Int) {
+                lock.release()
+            }
+        })
+    }
+}