fix(driver-turso): narrow every override's options from any to DriverOptions (#6402)

[os-zhuang]

Fixes #6402

What was open

TursoDriver overrides methods that take an options argument and declared every one of them options?: any, while the base they forward to (SqlDriver, and behind it the IDataDriver contract) declared DriverOptions. The keys DriverOptions names — bypassTenantAudit, tenantId, transaction, accessible_org_ids, skipCache, timeout, … — were unchecked at every one of those doors.

The argument is #5181's, one axis over. An internal caller that misspells bypassTenantAudit gets no runtime complaint: the typo'd key is simply never read, the write proceeds unaudited, and nothing anywhere says so. tsc is the only channel that ever objects, and any had switched it off.

Nothing is known to have gone wrong through this gap. It is closed because the door was open, not because someone walked through it — the issue was filed and triaged as observational.

⚠️ Premise correction: 17 sites, not five

The issue's count is wrong, and the correction changes the scope rather than a detail. #6402 names five overrides (update, upsert, delete, count, aggregate) — the CRUD block its author was reading while #6212 batch B was in flight. Measured against main, turso-driver.ts carries 17 options?: any sites:

Block	Overrides
CRUD	find, findOne, create, update, upsert, delete, count, aggregate
Bulk	bulkCreate, bulkUpdate, bulkDelete, updateMany, deleteMany
Raw execution	execute
Schema	syncSchema, syncSchemasBatch, dropTable

This matters because of the issue's own binding rule: an identical shape must not be partially narrowed, since a subset reads to the next person as a verdict on the rest. Narrowing the five named would have reproduced that exact anti-pattern at larger scale — leaving twelve character-identical any doors behind, in the very PR filed to stop that from happening. All 17 are narrowed here, so no half-narrowed state exists to be misread.

The dispatch ruling scoped this to "all five together, or a reasoned do-not-narrow verdict, never a partial narrowing". Narrowing all 17 satisfies both the letter (the five are included) and the intent (no residue). Flagging the scope change explicitly since it exceeds the literal ruling.

Also measured: turso-driver.ts was the only driver in the repo with this shape. Every other driver already declared DriverOptions. The remaining repo-wide options?: any hits are narrow structural port interfaces in objectql / service-job / service-queue / service-automation, which is a different axis and out of scope.

The measurement the issue asked for

#6402 explicitly made this a precondition: "我没有量过：这五处 override 的实际调用方是否都已经在传 DriverOptions 形状的值 … 收窄前应先跑一遍这个量。"

Run, on all 17: turbo run typecheck is 125/125 green, unchanged. No caller in this repo passes an off-contract value, so the narrowing is annotation-only — the same result #6210 measured on the query axis. No call site needed a cast, and none was added.

Reverse verification — direction predicted per channel BEFORE it was run

Reverted all 17 signatures to options?: any and measured both channels:

Channel	Predicted	Measured
pnpm typecheck	RED, one error per reverted signature, plus TS2578 on the misspelling pin	18 errors: 17 × TS1360, one per table row, + 1 × TS2578 ✓
pnpm test	GREEN — every assertion is a type-level fact	4/4 passed ✓

That split is the finding, not an inconvenience: this defect has no runtime face at all, which is why it sat unnoticed 17-for-17. It also means the pin had to be built as a compile-time check to have any teeth.

One prediction was written imprecisely and corrected against the measurement: the doc comment first said the revert fails with an assignability error; the actual code is TS1360 (does not satisfy the expected type), because the rows use satisfies. The comment now quotes the real message.

Tests

New turso-driver-options-door.test.ts pins all 17 doors. Door<T> reports 'any' for a widened door and 'DriverOptions' only for an exact match; each row then satisfies it, so reverting any single signature fails tsc on that row, naming the method that drifted.

A mutual-extends check could not do this — any satisfies both directions and would have reported green. The IsAny<T> = 0 extends 1 & T detector is what makes the pin real, and the revert above is the evidence it works rather than an assumption that it does.

The suite also carries a positive control (declared keys still fit, so the pin is not green merely because nothing fits) and a @ts-expect-error case on the exact misspelling the issue argued about — bypassTenantAdit. That directive tripping TS2578 under revert is what proves the excess-property check is live.

No existing test turned red, so nothing needed fixing and no cast was introduced to silence anything.

Verification

• pnpm --filter @objectstack/driver-turso test — 840/840 passed, 28 files
• pnpm --filter @objectstack/driver-turso typecheck — clean
• turbo run typecheck (packages, packages/*/*, apps) — 120/120; full monorepo 125/125
• pnpm --filter './examples/*' run typecheck — clean (4/4)
• turbo run build (packages + examples deps) — 70/70 and 66/66
• All 64 steps enumerated from .github/workflows/lint.yml — run one by one, every check:* in the ESLint and TypeScript Type Check jobs. All pass, including check:query-options-erasure (turso is not baselined — that ratchet targets engine query-options; the new test adds no erasure and leaves testSurface.sites alone), check:driver-conformance, check:driver-memory-census, check:type-check-debt, check:exported-any, check:published-files.
• pnpm lint — clean

Re-run in full after merging origin/main at 64d764e.

Notes

• Rebased/merged onto origin/main 64d764e. The diff is 3 files — turso-driver.ts, the new test, and the changeset. remote-transport.ts is untouched, keeping clear of in-flight PR fix(drivers): text-operator case folding is the contract's answer, not the dialect's (#6518) #6706.
• Changeset is patch, not docs-only: the narrowed signatures are public, so a downstream TypeScript consumer holding a TursoDriver-typed reference and passing a non-DriverOptions options will now see a compile error where it previously saw none. That error is the point — the value was already being ignored by the driver.
• The deferral comments left by refactor(drivers)!: 五个驱动的 query 参数跟进 DriverQuery，休眠的类型谎言没有藏身处 (#6075) #6210 on count and [finding][drivers] DriverQuery 收窄之外：aggregate / distinct / analyzeQuery 等驱动自有查询方法仍要求把对象名写两遍 #6212 on aggregate are now discharged and replaced with a block comment above find() recording why the sweep was all-or-nothing, so the next reader does not re-derive it.

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 8, 2026 2:22pm

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/driver-turso.

6 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/data-modeling/drivers.mdx (via @objectstack/driver-turso)
• content/docs/deployment/cli.mdx (via @objectstack/driver-turso)
• content/docs/deployment/environment-variables.mdx (via @objectstack/driver-turso)
• content/docs/deployment/self-hosting.mdx (via @objectstack/driver-turso)
• content/docs/getting-started/glossary.mdx (via @objectstack/driver-turso)
• content/docs/plugins/packages.mdx (via @objectstack/driver-turso)

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.