Drain a buffer, copy a store while it is being written, and bound a hostile expression

[aoreshkov]

Tier 1: one item per remaining gap, in the order the readiness note sequences them. Four use cases
were each blocked on something specific. No format change, no new dependency, and no answer any
query returns is different.

994 tests, zero failures. ABI dumps grew by 107 lines and shrank by none.

	Gap it closes	Shape
T1-6	nothing bounded a hostile expression	JsonPathLimits, three bounds, counted in steps
T1-7	StoreLockedException read as a crash	it carries the directory and a LockHolder
T1-2	no backup, checkpoint or consistent copy	checkpoint(target), hard-linked
T1-1	no retention; the correct loop is not obvious	deleteRange(from, to)
T1-5	a type mismatch discovered at runtime	ExplainTypeNote
T1-4	the (metadata, value) split is a trap	Variant.detached(), shreddingAdvice()
T1-3	the drain pattern is hand-rolled	:rabosh-samples:runDrain

Bounded evaluation for untrusted JSONPath

The module's chosen use case is expressions you did not write, and nothing bounded what a small,
valid query cost against a large document. $..*..nope is fourteen characters, quadratic in the
document's node count, and returns the empty nodelist — so nothing measured on the answer can see
it coming. That is why the fixture names a field the document does not have, and it is the sharpest
statement of why the bound has to be on the work.

The bound refuses; it never truncates, and this reconciles T1-6 with a rule rabosh-jsonpath
already had. Its conventions said the walk carries no budget, because one that stopped early and
returned what it had is a wrong answer with nothing to say so. That rule is unchanged and still
governs. JsonPathLimitExceededException is the opposite mechanism: no nodelist rather than a short
one. Evaluation.stop() throws rather than returning a Boolean deliberately — reusing the
sink's own "stop" would look like a simplification while reintroducing the exact truncation the rule
forbids. Please keep those apart in review.

All 703 compliance cases and the module's 20 000-deep and 5 000-wide fixtures pass under the shipped
defaults, untouched. The defaults are a backstop, not a policy.

Checkpoint

Flush, pin a snapshot, link what that snapshot sees. The ordering rule — log, then memtable, then
segment, then manifest, then delete — governs the target as much as the source, so every data
file is durable before the manifest naming it exists and CURRENT is written last.

Core copies every file numbered after a live segment rather than a list of suffixes, so it needs no
knowledge of what a .cat or .pst is and a sidecar kind added later travels for free. INDEXES is
named rather than numbered and cannot travel that way — IndexCatalog.copyRegistryTo carries it,
because losing it would lose an instruction rather than derived data and leave the posting files as
orphans. That is why Rabosh.checkpoint exists rather than the facade delegating and stopping.

The fault suite fails the copy at four steps and asserts the source is unharmed at each. Note
which step it arms: the segments are hard-linked, so no byte is written for one and a WRITE fault
never fires. FORCE happens either way, and it is the step the ordering rule is actually about.

The rest, briefly

• deleteRange is point deletes in bounded batches, deliberately: no new operation id, no format
  change, and above all no change to the tombstone-drop rule, which fails by returning a deleted
  document to a reader.
• ExplainTypeNote is a diagnostic, never a coercion. Type bracketing is unchanged and
  ColumnPredicate.matches is still the only definition. The family travels on Normal.Leaf from the
  lowering because ColumnPredicate.kind is internal to rabosh-index, and re-deriving it in the
  query layer would be a second definition of bracketing arriving by the back door.
• detached() — a document read from a segment carries that segment's dictionary, so handing
  the pair over is a trap that sometimes works. The test uses document 50 rather than document 0,
  because document 0's two names occupy the same ids in both dictionaries and read back perfectly.
• LockHolder.isRunning checks the start time as well as the pid. Operating systems reuse pids,
  and telling a user to kill pid 4242 on the strength of a number is how they kill a stranger's
  process. The lock moved to byte zero with the record after it, because a Windows file lock is
  mandatory and a second process could not otherwise read the record at the one moment it wants to;
  the regions overlap, so a build using either scheme still excludes one using the other.
• runDrain is the acceptance test for the two big items in the only way that matters, a caller's
  program: snapshot, scan from the watermark, ship, then record the watermark, retire, compact.
  Every mistake in that order is silent.

The deprecation cycle's first live test

StoreLockedException needed a new constructor. The old two-argument one is still there,
@Deprecated(WARNING) with a ReplaceWith — which is why directory is Path? rather than Path.
Zero removals across all seven dumps. If you would rather take the break than carry the nullability,
say so and I will; the policy shipped last week and this is the first time it cost anything.

Verification

build, -p build-logic check, all three samples, the module-path run, publishToMavenLocal,
dokkaGenerate (no new warnings). Assertions verified by breaking them:

Break	Result
Checkpoint skips files numbered after a segment	RaboshCheckpointTest fails on both the index and the schema
$..*..nope under JsonPathLimits.NONE	answers — so the refusal is the bound, not the fixture
The mismatched pair for document 0	reads back correctly, which is why the test uses 50

Still not addressed

Second commit: the tier audit is now a gate

The section that used to sit here said the tier-leak audit was still not wired into build and
offered to do it in a follow-up. It is done in 7cd8465, in this PR rather than a later one, because
the first commit adds public surface to every module in the chain and that is precisely when the
claim needs holding up.

ApiTierAudit is the awk script promoted: plain Kotlin over File beside PublishedModules and
CentralBundleReport, 15 unit tests, and a root checkApiTiers task hung off check — so
./gradlew build runs it and CI needs no new step. Root rather than per-module because the leak is
cross-module: a type marked in rabosh-index leaks through a signature in rabosh-query's dump.

Both halves are derived and neither is listed — the marker set from the sources, the surface from
the committed dumps. A hand-maintained list of experimental types would disagree with the annotations
exactly once, silently, in the direction of not reporting a leak. The awk script is deleted rather
than kept beside it, for the same reason.

Promoting it found a bug the hand-written version never had to have. The script carried a
hard-coded type list, so it never worked out which type a marked member belonged to. The derived
version does, and its first attempt took the most recent type declaration above the annotation — which
put IndexCatalog.read inside a private class declared two hundred lines earlier, and reported a
correctly marked method as a leak. A false positive is what gets a gate switched off, so nesting now
follows indentation with a strictly-less-than comparison, and the sibling case is a test.

Break	Result
Remove the marker from IndexCatalog.read	checkApiTiers fails, naming the method, IndexReader and the module
An annotation with no declaration under it	markedIn throws rather than returning a short set — under-reporting is the only failure that matters

Current output: API tiers: 7 dump(s) checked against Tier(20 type(s), 12 member(s)), no leaks.

One limit stated rather than assumed: the audit checks what a dump can express. List<Bitmap>
erases to Ljava/util/List;, so an experimental type reachable only as a type argument is invisible to
it. Nothing in the current surface has that shape, and the phase note records it as the reason to
remember why if one is ever added.

🤖 Generated with Claude Code