fix(driver-turso): a remote $between that is not two bounds is refused INVALID_FILTER / 400 through the transport's withheld seam, naming no field or value (#20094)

[objectstack-fleet]

Fixes #20094

Clause-②: no

What changed

In remote mode, TursoDriver.toRemoteFieldSpec lowers $between to $gte / $lte before the filter reaches RemoteTransport, so that a two-bound range inherits the whole-day upper-bound rule (framework#4081). A range that was not two bounds was refused right there, with a bare Error: no code, no status, and a message naming 'deal.field' and echoing the comparand. That method runs before the transport and so outside its refusal seam, which is why PR #20093's class closure never reached it.

• turso-driver.ts, the $between arm of toRemoteFieldSpec. A range that is not two bounds is no longer refused here. The arm hands it to the transport as written, un-lowered. A two-bound range lowers exactly as before.
• remote-transport.ts, the $between arm of unsupportedOperator. The arm now tells apart the two ways a $between can arrive:
  • A range that is not two bounds gets driver-sql's class statement for the same mistake (betweenArityError), behind this file's [RemoteTransport] prefix. It goes through withheldRefusal: INVALID_FILTER / 400, with the field and the comparand in the diagnostic sink only.
  • A well-formed range keeps its "must be lowered" sentence, unchanged.
  • The range is read off the operator map that the one call site already passes as subtree. The refusal carries the range itself when it is an object, and otherwise the map. That is driver-sql's refusalSubtree rule.

After this change toRemoteFilter, toRemoteFieldSpec and toRemoteUpperBound contain no throw. The remote face's filter refusals are raised in buildWhereSQL, behind the seam and its enumeration pin.

The remote withheld message, as it stands at this head:

[RemoteTransport] Operator "$between" in this filter requires a [min, max] value array. The field it was aimed at is withheld from the message; the full diagnostic is in the server log.

It is the local message behind the prefix, minus one thing: the local sentence carries the tracker id (#8197). Runtime text carries no tracker id, and check:doc-authoring's sibling-package prose ratchet reds a new one, so the copy leaves it out. The class statement itself is byte-equal to the local one. The pin compares the two faces after removing the local tracker id, so the day the local sentence drops it, the comparison still holds.

Measured

The probe was a scratch vitest file, never committed. It drove a real remote TursoDriver (the in-repo libSQL stub over better-sqlite3) and a local TursoDriver(':memory:') control, both seeded with the same four rows. It covered 7 shapes ([x], [x, y, z], a number, a string, null, {} and []), 3 caller classes (unmarked, 'policy'-marked where, 'author'-marked where), and both find and count: 42 cells per face. The field is secret_policy_col and the literals are distinctive, so a leak is a substring hit. The base column was measured on the base tree (8d76c2d38c), and again with both files put back at their base blobs in this worktree. The two base runs are byte-identical.

H1: confirmed

face	base	this head
remote	42 of 42 cells: bare Error, code and status undefined, no own keys. The message names 'deal.secret_policy_col' in all 42, and echoes the comparand in all 24 cells whose shape has a literal. Nothing is logged.	42 of 42 cells: INVALID_FILTER / 400, own keys exactly code,status. The message names neither the field nor the comparand. One warn line holds both.
local (control)	INVALID_FILTER / 400 and one class for all seven shapes. Unmarked and 'policy': withheld, with one warn line naming the field. 'author': the field restored, nothing logged. The comparand is never echoed.	42 of 42 cells byte-identical to base

H2: falsified as stated, so the arm needed one branch

I drove the transport directly with the un-lowered $between, 7 shapes × 3 marks. At base it refused all 21 cells with INVALID_FILTER / 400 through the seam and executed no statement. The wording, though, was the "must be lowered to $gte/$lte before it reaches the transport" sentence. That is the class of a skipped lowering step, not the local face's arity class. Dropping the pre-check alone would therefore have answered the right envelope with a false cause. At this head all 21 cells answer the arity class. 'author'-marked cells get the full diagnostic, including the comparand.

Lowering controls, base against head, byte-identical in all six. Each control compared the lowered filter (toRemoteFilter), the statements the stub executed, and the rows and count on both faces. Local and remote agree in every control.

control	lowered (identical at base and head)	rows
numeric [10, 20]	{"$gte":10,"$lte":20}	r2, r3
bare days on a date field	{"$gte":"2026-01-01","$lte":"2026-01-31"}	r1, r2
bare days on a datetime field	{"$gte":"2026-01-01T00:00:00.000Z","$lt":"2026-02-01T00:00:00.000Z"}	r1, r2 (r2 is 13:45 on the last day; only the whole-day rule admits it)
instants on a datetime field	$gte / $lte, unwidened	r1
the bare-day control under $not	$not of the widened pair	r3, r4
numeric inside $or	the lowered pair inside $or	r2, r3, r4

H3: which text each caller class gets

caller	local (base = head)	remote base	remote head
unmarked	withheld class statement	bare Error, field and comparand, to everyone	withheld class statement
'policy'	withheld class statement	the same bare Error	withheld class statement
'author'	the full text, field restored	the same bare Error	withheld class statement

toRemoteFilter rebuilds every node, so no mark reaches the transport. On the remote face an author therefore reads the unmarked answer. PR #20093 declared that same cost for the transport's other classes; it errs in the withholding direction. I did not extend turso-local-remote-text-parity.test.ts. Its population is FILTER_TEXT_CASES, which has no $between row, so nothing there reaches this door. The local-against-remote table for withheld classes is Half 3 of remote-transport-compile-refusal-seam.test.ts. This PR extends that half with a table of its own, and adds no new file.

H4: the refused set did not move

Every one of the 42 remote cells was refused at base and is refused at head. I also measured 15 nested and multi-operator cells at both base and head: a malformed range under $not, inside $or, inside $and with null, beside a $gt in one map, and a two-bound range with an object member. Each of them was refused at base and is refused at head. The six well-formed controls answer the same rows. Declared patch, Clause-②: no.

Tests

remote-transport-compile-refusal-seam.test.ts grows from 96 to 130 cases:

• An ARMS row for the arity branch ({ secret_policy_col: { $between: [7770123] } }), driven through all four legs of Half 2: 'policy', 'author', unmarked and merged $and in both orders. The stack binds it to unsupportedOperator. The existing well-formed $between row stays, so both branches of the arm are pinned.
• Half 3b, one table over both faces. It covers 7 shapes × find / count (28 cases):
  • Unmarked and 'policy': INVALID_FILTER / 400 and own keys exactly code,status on both faces. The class statement is on the wire, with no field and no literal. The field is in each face's log, and the comparand is in the remote sink. The remote message equals the local one behind the prefix, minus the local tracker id. No statement is executed.
  • 'author': local restores the field, and remote equals its own unmarked answer.
• Two well-formed controls. Numeric [10, 20], and bare days on a datetime field. The date control's expected rows include a row only the whole-day upper bound admits. Both faces must return the same rows, and count must agree.

Ablations, on committed state. Each ablation put one file back at its base blob with git restore --source, and the blob hash was checked equal to base before the run. trap restored the file from HEAD, the blob hash was checked equal to HEAD, and git diff HEAD was empty afterwards. The pin imports src, so no build leg was needed. I predicted the counts before running either one.

1. turso-driver.ts at base (marker 1 → 0): 28 failed, 102 passed, as predicted. All 28 Half 3b shape cases failed. The two controls and the transport arity row stayed green.
2. remote-transport.ts at base (marker 2 → 0): 18 failed, 112 passed, as predicted. The four legs of the arity row failed, along with the 14 unmarked and 'policy' Half 3b cases, whose wording at base is "must be lowered". The 14 'author' cases stayed green (remote stays withheld either way), and so did the controls. This is H2 as a test result.

Suites run, all at d148119880 unless noted:

• driver-turso, the whole suite: 68 files, 1640 tests passed. typecheck exits 0, and tsc --noEmit --listFiles counts the pin file once.
• driver-sql seam and provenance pins, which import the shared wording: sql-driver-compile-refusal-seam, sql-driver-target-field-provenance, sql-driver-refusal-door-provenance and sql-driver-cross-field-provenance. 4 files, 169 tests passed.
• The scratch probe, at base and at head (see above).
• driver-sql is untouched, and no export moves. The only wording removed ([TursoDriver] $between on … needs exactly two bounds) has no reader: a repo-wide git grep finds it nowhere. The control, the spec's own "A range needs exactly two bounds" message, was found in its 3 files.

Gates

• dispatch-gates --commands --repo objectstack-ai/objectstack at d148119880 (merge base aa04ea2964, 4 paths) derived 62 families, and all 62 exited 0.
  • check:dual-build-cjs-loads and check:lean-entry-closure first exited 3 (PREREQUISITE NOT MET). They exited 0 after turbo run build --filter=./packages/* --filter=./packages/*/* (72 of 72 tasks). check:dts-closure was re-run on that build: 72 packages, 166 of 166 declaration files present.
  • --ran over the last record per command: "62 derived, 62 run, 0 NOT-MEASURED, 0 UNRUN".
• The three roster families under packages/ that the PM's derivation flagged exited 0: check:authz-resolver, check:error-code-casing and check:filter-alias-parity.
• check-issue-citations --base aa04ea2964: exit 0, 5 citations resolve.
• check:driver-conformance: "50 covered cell(s), 0 in the DEBT ledger, 0 exempt" both at base (8d76c2d38c, read from an archived tree) and at this head. The ledger did not move.
• check:doc-authoring: the sibling-package prose ids hold the baseline, with no growth.
• ESLint (--no-inline-config --format json) on the 3 changed .ts files reports 3 files, 0 errors and 0 warnings, so no file was ignored. The printed config for remote-transport.ts has parserOptions {"ecmaVersion":"latest","sourceType":"module"} and no project. Linting is therefore not type-aware, and this diff cannot move a verdict on an untouched file. The repo-wide run is CI's.
• A control-byte scan of the 4 changed files found no hits.

Acceptance notes

• A remote author loses the text it got at base. The base text was a bare Error that also went to every other caller. At this head the author gets the withheld class statement, and the field and comparand are in the server log. Local mode still restores the field for an author. This is the fail-closed direction the contract prescribes, and the same one the transport's other classes already take on the remote face.
• Which refusal answers can change when one filter carries more than one defect on the remote face. The transport walks the map in order. Measured at head: { f: { $gt: SOME_OBJECT, $between: [x] } } answers the comparand refusal, and the same map with $between first answers the arity refusal. Both are INVALID_FILTER / 400. At base the lowering threw its bare $between error for both orders; that is read from the code, not measured: the lowering walks the whole map before the transport sees it. The refused set does not move.
• An object member inside a two-bound range ([{…}, 1]) answers a different class on each face. Local answers the list-member refusal and remote answers the comparand refusal. Both are INVALID_FILTER / 400 and withheld. The answer is identical at base and head, because this diff does not touch the two-bound path, and PR fix(driver-sql, driver-turso): every filter-compile refusal goes through the withheld provenance seam, so a read scope refused there names no field or literal (#20039) #20093's changeset already says so.
• turso-remote-temporal-conformance.test.ts still asserts its malformed $between with a bare toThrow(/\$between/). It stays green. The new table pins the envelope, and that file is outside this claim's one-table surface.
• The REST face was not measured. The measurements are at the driver.
• I merged origin/main once (aa04ea2964, objectql only). It is outside driver-turso's dependency closure.
• driver-turso remote: inherited SqlDriver methods the remote face does not override answer from the placeholder :memory: Knex database — introspectSchema() returns no tables, distinct() a 500, findWithWindowFunctions() a raw SQLite error #20055 and spec + drivers: a $like / $ilike pattern holding U+0000 is cut at the NUL on the SQLite faces and answers a different question; refuse it at every face through one spec predicate beside hasDanglingLikeEscape #20041 are not addressed here. They are in flight in other regions of these files, and this diff touches only the two $between arms, one doc paragraph, the seam pin and the changeset.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

3 anchor(s) derived from 1 changed package(s); no hand-written page names any of them, so this run has nothing to list — not a clean bill of health. This check sees only pages that NAME a derived anchor: one that documents this change in prose, or enumerates it in an authoring dialect, names none and stays invisible to it on every run.

What this run could not see

• the SDK route bridge reached 60 of 215 client-bound route-ledger rows — the other 155 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 155: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 100 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 6 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json fa00ebf44759b7fcfb0a1e9f55256265068399a8 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 260feffb77bdc9f5259da62bd3bf85ebd2a13bdc — the merge of head d14811988009df1869d3660cc2d3e26d8e075e72 into base fa00ebf44759b7fcfb0a1e9f55256265068399a8, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 260feffb77bdc9f5259da62bd3bf85ebd2a13bdc && git checkout 260feffb77bdc9f5259da62bd3bf85ebd2a13bdc
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin fa00ebf44759b7fcfb0a1e9f55256265068399a8 d14811988009df1869d3660cc2d3e26d8e075e72 && git checkout -B drift-repro fa00ebf44759b7fcfb0a1e9f55256265068399a8 && git merge --no-ff d14811988009df1869d3660cc2d3e26d8e075e72

node scripts/docs-audit/affected-docs.mjs --json fa00ebf44759b7fcfb0a1e9f55256265068399a8

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: d14811988009df1869d3660cc2d3e26d8e075e72

Scope: 4 files (+232/−13) on merge base aa04ea2964:

• the $between arm of TursoDriver.toRemoteFieldSpec;
• the $between arm of RemoteTransport.unsupportedOperator, with its doc paragraph;
• the seam pin remote-transport-compile-refusal-seam.test.ts;
• the changeset.

No governed surface is touched.

Read: card #20094 with its triage, unlock and claim, #20039, PR #20093 and its record 5826632400, the PR body, the diff, all check-runs, AGENTS.md, contract-review.md, and the code at head and base.

Measured in two detached worktrees (head and base), each with driver-turso's closure built. The probe drove a real remote TursoDriver over the in-repo libSQL stub beside TursoDriver(':memory:'), and it also drove RemoteTransport directly with a stub client and a diagnostic sink.

① Derived judgments

• Every malformed shape: the premise is REAL at base and closed at head. The seven shapes were [x], [x,y,z], a number, a string, null, {} and []. Each ran under 3 marks through find and count on both faces: 84 cells per tree.
  • Base remote, 42/42: a plain Error with code and status undefined. It names 'object.field' in 42/42 and echoes the comparand in 24/24 literal cells, logs nothing, and is the same for every caller.
  • Head remote, 42/42: INVALID_FILTER / 400, with own keys exactly code,status. The field appears in 0/42 messages and the comparand in 0/24. There is exactly one warn line with the field and comparand, and 0 statements execute.
  • The head remote non-author message equals [RemoteTransport] plus the local class statement in 28/28 cells.
  • Local control: 42/42 cells are byte-identical at base and head.
  • aggregate, updateMany and deleteMany with [x] also answer INVALID_FILTER / 400 at head, with no row changed.
• The refused set does not move: RIGHT. 17 nested and multi-operator shapes × {unmarked, 'policy'} × 2 faces = 68 cells, 0 moved. Well-formed shapes answer the same rows at base and head.
• Well-formed ranges lower byte-identically: RIGHT. Six controls: a numeric range, bare days on a date field, bare days on a datetime field (the whole-day upper bound of framework#4081), instants, a range under $not and a range inside $or. The lowered filter, the executed SQL and args, the rows and the counts are identical at base and head in 6/6, and remote equals local in 6/6.
• The pins discriminate: RIGHT, and both claimed counts reproduce. The seam pin passes 130/130 at head. With turso-driver.ts at its base blob it gives 28 failed / 102 passed; with remote-transport.ts at its base blob, 18 failed / 112 passed. Each file was restored by blob.
• No throw remains in the remote lowering at head. The removed wording has no reader in the repository.
• Public surface: RIGHT. Both changed methods are private. No export, index.ts, package.json or packages/spec file moves.
• Existing pins: turso-remote-temporal-conformance.test.ts passes 67/67 at head.
• CI at this head: 34 runs, 31 success, 3 skipped, 0 failures, and all seven required contexts are success.

② Semver level

@objectstack/driver-turso: patch, Clause-②: no: RIGHT.

• The refused set is unchanged in 152 of 152 cells, and the rows are unchanged in every well-formed control.
• No export or signature moves. Message text is outside the published accept set (the driver-sql: the #7929 withhold covers the cross-field family only — every other INVALID_FILTER refusal still names the target field, which is admin-authored on a read-scope predicate #8197, fix(driver-sql, driver-turso): four filter-refusal doors read the provenance mark before naming a read scope field or comparand (#20020) #20037 and fix(driver-sql, driver-turso): every filter-compile refusal goes through the withheld provenance seam, so a read scope refused there names no field or literal (#20039) #20093 precedents).
• The declared fail-closed cost for a remote 'author' caller narrows nothing that caller could rely on. At base it got a bare Error with no code; at head it gets INVALID_FILTER / 400. No remote transport refusal has disclosed to an author since PR fix(driver-sql, driver-turso): every filter-compile refusal goes through the withheld provenance seam, so a read scope refused there names no field or literal (#20039) #20093 (author equals unmarked in 14/14 cells).

③ Boundary flags

• Changeset: every sentence is TRUE. The read-scope clause is measured through a 'policy'-marked where, not through the plugin itself.
• PR body: no FALSE sentence. H1–H4, the 96 → 130 case count, both ablations and the acceptance notes reproduce. The whole-suite count and the gate families were not re-measured here; CI carries them.
• The dev's deviations are answered.
  • Not extending the text-parity file is correct: it has 0 $between rows.
  • Omitting the tracker id from the new runtime string is justified by the prose-id baseline.
  • The remote author cost is accepted per ②.
  • The three out-of-scope observations are correctly left unfiled.

Implemented-by: claude/issue-20094-turso-remote-between-envelope
Reviewed-by: session_01Bvd69VPa6puiNzzPUroDBx

VERDICT: PASS