[finding][drivers] `TursoDriver` 五个 override 的 `options?: any` —— #5181 收窄的是 query，options 这条轴还没人碰过

[os-zhuang]

在 #6212 批 B（aggregate 收窄）实施期间实测发现，记录备查。观察类，不挂 pm:queue，请分诊轮定级。

事实

packages/drivers/driver-turso/src/turso-driver.ts 里五个 override 的 options 形参是 any，而它们各自的基类（SqlDriver / IDataDriver）声明的是 DriverOptions：

方法	当前签名（options 部分）
update	options?: any
upsert	options?: any
delete	options?: any
count	options?: any（query 已在 #6075 / PR #6210 收成 DriverQuery）
aggregate	options?: any（query 已在 #6212 批 B 收成 DriverQuery）

DriverOptions 声明的键（bypassTenantAudit / tenantId / trx 等）在这五处一律不受检 —— 与 #5181 对 query 参数的那条论证逐字同构：一个内部调用方拼错 bypassTenantAudit，tsc 是唯一会说话的通道，而这里把它关掉了。

为什么记一笔而不是顺手改

• [spec] IDataDriver 的 query 参数要求 QueryAST.object 与第一实参重复 —— 下游被迫 as any(20 处实测),提议 Omit/optional 化 #5181（PR refactor(spec)!: IDataDriver 的 query 参数改为 DriverQuery，对象名只写一遍 (#5181) #6076）/ [finding][drivers] 五个驱动的 find/count/… 仍声明 query: QueryAST，而调用方已可省略 object —— 双变让它编译，但声明开始说谎 #6075（PR refactor(drivers)!: 五个驱动的 query 参数跟进 DriverQuery，休眠的类型谎言没有藏身处 (#6075) #6210）/ [finding][drivers] DriverQuery 收窄之外：aggregate / distinct / analyzeQuery 等驱动自有查询方法仍要求把对象名写两遍 #6212 收窄的都是 query 那条轴，options 从未在范围内；
• 五个 override 的 options?: any 是逐字相同的一处形状，五改其一（比如只改 aggregate 的）会被下一个读者读成「对另外四个的判断」。PR refactor(drivers)!: 五个驱动的 query 参数跟进 DriverQuery，休眠的类型谎言没有藏身处 (#6075) #6210 在 count 上、[finding][drivers] DriverQuery 收窄之外：aggregate / distinct / analyzeQuery 等驱动自有查询方法仍要求把对象名写两遍 #6212 批 B 在 aggregate 上都因此刻意留下了它。

因此这是一次性五处一起收的活，或者一次性判定「不收，并写下理由」，不适合搭在别的 PR 上。

判级需要的量

我没有量过：这五处 override 的实际调用方是否都已经在传 DriverOptions 形状的值（若是，收窄就是纯注解、零报错，与 #6210 在 query 上的实测同形）。收窄前应先跑一遍这个量。

今天没有人踩：没有已知缺陷从这个口子出来过，故判级请按观察类走。

关联：#6212、#5181、#6075。

[os-project-manager]

Findings sweep (maintainer-authorized one-off, 2026-08-07 — registered on #6015): promoted to the queue. Five overrides declaring options?: any against a base that declares DriverOptions — the #5181 argument verbatim on the options axis: a misspelled bypassTenantAudit has no channel but tsc, and these five turn it off. Mechanical narrowing; batch with #6212/#6231/#6401. finding → pm:queue.

---

Generated by Claude Code

[os-zhuang]

Claim: PM loop, drivers lane (accelerated batch, maintainer-directed)
Session: session_01Hg9Pkg5nDedCRihRsdeCdX
Branch: claude/issue-6402-turso-driver-options-narrowing
Worktree: objectstack-issue-6402 (cloud session — own container)
Domain: domain:drivers
Container class: mechanical narrowing + call-site survey, mode:cloud per lane policy
File surface: packages/drivers/driver-turso/src/turso-driver.ts (the five override signatures) plus any turso test file the narrowing turns red; call-site survey elsewhere is read-only.
Serial constraints cleared: PR #6706 (issue #6518, in flight at review) touches driver-turso/src/remote-transport.ts and turso text-predicate tests but NOT turso-driver.ts — same package, disjoint files; dev instructed to merge origin/main before finalizing. #6212 batch B (aggregate query narrowing) merged. No other in-flight claim on driver-turso found.

---

Generated by Claude Code

[os-zhuang]

Measurement from #6394's implementation (that issue's cast sits on TursoDriver.create's options gate, so I had to resolve which signature actually wins there). The table in the body under-counts: it is 16 overrides, not 5.

Filing this here rather than as a new issue because it is the same shape on the same axis — but it matters for scoping, since the body's own argument ("五个 override 的 options?: any 是逐字相同的一处形状，五改其一……会被下一个读者读成「对另外四个的判断」") applies with equal force to the eleven that are missing from the list.

Full inventory

Baseline origin/main @ 64d764e, packages/drivers/driver-turso/src/turso-driver.ts:

grep -nE "override async [a-zA-Z]+\(.*options\?: any" packages/drivers/driver-turso/src/turso-driver.ts

#	Method	Line	In the body's table?
1	find	507	❌
2	findOne	512	❌
3	create	523	❌
4	update	528	✅
5	upsert	533	✅
6	delete	538	✅
7	count	543	✅
8	aggregate	558	✅
9	bulkCreate	960	❌
10	bulkUpdate	968	❌
11	bulkDelete	978	❌
12	updateMany	983	❌
13	deleteMany	990	❌
14	execute	999	❌
15	syncSchema	1027	❌
16	dropTable	1097	❌

I checked every one against its base: all 16 have a SqlDriver base declaring options?: DriverOptions (packages/drivers/driver-sql/src/sql-driver.ts — find 2789, findOne 2949, create 2961, update 3416, upsert 3444, delete 3480, bulkCreate 3503, bulkUpdate 3556, bulkDelete 3565, updateMany 3574, deleteMany 3586, count 3625, execute 3661, aggregate 3802, syncSchema 4082, dropTable 4090). So there is no subset here that is any for a legitimate reason — it is one uniform widening across the whole override surface.

Why create in particular is worth calling out

#6394 removed a as never on a driver.create(…, { bypassTenantAudit: true }) options argument in date-bucket-parity.test.ts. I measured what removing it restores: nothing. With the cast gone, both a misspelled key and a wrong-typed value still compile clean, because override #3 above erases the parameter to any. Confirmed the test file really is in the compile graph (an unrelated const x: number = "s" in the same file does red with TS2322), so that is a real negative, not a skipped check.

The contrast against a driver that has not had this widening applied, same key, cast stripped:

src/sql-driver-runtime-token-default.test.ts(111,73): error TS2561: Object literal may only
specify known properties, but 'bypassTenantAuditt' does not exist in type '{ transaction?:
unknown; … bypassTenantAudit?: boolean | undefined; }'. Did you mean to write 'bypassTenantAudit'?

That is exactly the check this issue is about, working on SqlDriver and silent on TursoDriver.

On the un-measured quantity the body asks for

The body notes it did not measure whether existing callers already pass DriverOptions-shaped values. I have not measured that across all 16 either, so that gate still stands before narrowing. One data point in its favour: driver-turso's own 836-test suite and full package typecheck are green with the #6394 call site passing a plain { bypassTenantAudit: true } — a declared key, correctly typed.

Also filed #6754 for the sibling shape: 27 dead { bypassTenantAudit: true } as any casts in driver-sql / driver-sqlite-wasm tests. Those are the inverse trade to this issue — they sit on a real typed gate, so removing them buys checking immediately, whereas turso's casts are only worth touching after these 16 overrides are narrowed.

---

Generated by Claude Code

[os-zhuang]

os-dev report

{
  "issue": 6402,
  "premise_still_valid": true,
  "premise_correction": {
    "claimed": "5 overrides carry `options?: any` (update, upsert, delete, count, aggregate)",
    "measured": "17 overrides carry `options?: any`, verbatim-identical shape",
    "evidence": "grep -c 'options?: any' packages/drivers/driver-turso/src/turso-driver.ts => 18 (17 signatures + 1 in the #6212 deferral comment). Blocks: CRUD (find, findOne, create, update, upsert, delete, count, aggregate), Bulk (bulkCreate, bulkUpdate, bulkDelete, updateMany, deleteMany), Raw (execute), Schema (syncSchema, syncSchemasBatch, dropTable).",
    "why_it_changes_scope": "The issue's binding rule is that an identical shape must not be PARTIALLY narrowed, because a subset reads as a verdict on the rest. Narrowing only the 5 named would have left 12 character-identical `any` doors behind — reproducing, at larger scale, the exact anti-pattern the issue was filed to prevent. All 17 narrowed together.",
    "also_measured": "turso-driver.ts was the ONLY driver in the repo with this shape; every other driver already declared DriverOptions. Remaining repo-wide `options?: any` hits are narrow structural port interfaces in objectql / service-job / service-queue / service-automation — a different axis, out of scope, filed below."
  },
  "verdict": "narrowed",
  "scope_vs_ruling": "Dispatch ruled 'all five together, or a reasoned do-not-narrow verdict, never a partial narrowing'. Narrowing all 17 satisfies the letter (the five are included) and the intent (no residue). Flagged as exceeding the literal ruling; reversible to exactly five on request, but that produces the partial state the issue forbids.",
  "issue_measurement_precondition": {
    "asked": "Are all callers of these overrides already passing DriverOptions-shaped values? (issue: 'I have NOT measured this ... run it before narrowing')",
    "result": "Yes. `turbo run typecheck` 125/125 green, unchanged. Annotation-only — same result #6210 measured on the query axis.",
    "call_sites_broken": 0,
    "casts_added_at_call_sites": 0
  },
  "implementation": {
    "files_changed": 3,
    "diff": "+203 / -22",
    "code": "packages/drivers/driver-turso/src/turso-driver.ts — 17 signatures `options?: any` -> `options?: DriverOptions`; import of DriverOptions from '@objectstack/spec/data' (matching driver-sql's convention); the #6212 deferral comment on `aggregate` discharged and replaced by a block comment above find() recording why the sweep was all-or-nothing.",
    "tests": "packages/drivers/driver-turso/src/turso-driver-options-door.test.ts (new) — compile-time pin on all 17 doors.",
    "changeset": ".changeset/turso-driver-options-driveroptions.md — patch",
    "changeset_level_reasoning": "patch, not docs-only: the narrowed signatures are public, so a downstream TS consumer holding a TursoDriver-typed reference and passing a non-DriverOptions options value now sees a compile error where it previously saw none."
  },
  "test_design": {
    "mechanism": "`Door<T>` reports 'any' for a widened door and 'DriverOptions' only for an exact match; each of 17 rows `satisfies` it, so reverting any single signature fails tsc ON THAT ROW, naming the method that drifted.",
    "why_not_simpler": "A mutual-`extends` check reports green against `any` (it satisfies both directions). The pin needs the `IsAny<T> = 0 extends 1 & T` detector to have teeth — proven by the reverse verification, not assumed.",
    "controls": "Positive control (declared keys still fit, so the pin is not green merely because nothing fits) + a @ts-expect-error on the exact misspelling the issue argued about (`bypassTenantAdit`)."
  },
  "reverse_verification": {
    "predicted_before_running": true,
    "typecheck": {"predicted": "RED, one error per reverted signature + TS2578 on the misspelling pin", "measured": "18 errors: 17 x TS1360 (one per row) + 1 x TS2578", "match": true},
    "test": {"predicted": "GREEN — every assertion is a type-level fact", "measured": "4/4 passed", "match": true},
    "finding": "The defect has NO runtime face at all. That is why it went 17-for-17 unnoticed, and why the pin had to be compile-time to mean anything.",
    "self_correction": "The doc comment first predicted an assignability error; the real code is TS1360 ('does not satisfy the expected type') because the rows use `satisfies`. Comment corrected to quote the measured message."
  },
  "verification": {
    "driver_turso_tests": "840/840 passed, 28 files",
    "driver_turso_typecheck": "clean",
    "turbo_typecheck_packages_apps": "120/120",
    "turbo_typecheck_full_monorepo": "125/125",
    "examples_typecheck": "4/4 clean",
    "turbo_build": "70/70 and 66/66",
    "lint": "clean",
    "lint_yml_gates": "all 64 steps enumerated from .github/workflows/lint.yml and run one by one — ALL PASS",
    "gates_of_note": "check:query-options-erasure PASS (turso is not in scripts/query-options-erasure-baseline.json — that ratchet targets engine query-options; the new test adds no erasure and leaves testSurface.sites unchanged); check:driver-conformance, check:driver-memory-census, check:type-check-debt, check:exported-any, check:published-files all PASS.",
    "rerun_after_merge": "Full gate list re-run after merging origin/main @ 64d764e"
  },
  "pr": {
    "number": 6755,
    "url": "https://github.com/objectstack-ai/objectstack/pull/6755",
    "draft": true,
    "base": "main",
    "merged_main_at": "64d764e",
    "ci": "pending — see the follow-up comment on this issue for the converged result",
    "conflict_avoidance": "diff held to 3 files; remote-transport.ts untouched, keeping clear of in-flight PR #6706 (issue #6518)"
  },
  "out_of_scope_findings": [
    {
      "what": "The 3 dead `{ bypassTenantAudit: true } as any|never` options-gate casts in driver-turso tests are unblocked by this PR.",
      "action": "NOT filed as new — deduped to existing #6754, which names #6402 as its own blocker. Posted the measurement as a comment there instead.",
      "measurement": "With #6755 applied, stripping all 3 gives driver-turso typecheck EXIT=0; misspelling a key after the strip then yields TS2561 'Did you mean to write bypassTenantAudit?' — i.e. removing the casts now buys back a REAL check, the same trade #6754 measured on driver-sql. Before this PR it bought nothing.",
      "correction_to_6754": "It inventories 2 turso casts; measured 3 (date-bucket-parity.test.ts:68 as never — that is #6394's site — plus turso-temporal-conformance.test.ts:114,156 as any). Total across 3 packages is 30, not 27+2.",
      "deliberately_not_fixed_here": "Those sites are claimed by #6754 and #6394; absorbing them would leave both issues stale and push this diff past its 3-file scope."
    },
    {
      "what": "`options?: any` on structural driver-port interfaces outside the drivers layer: objectql/src/summary-aggregate.ts:89, objectql/src/summary-backfill.ts:126-127, objectql/src/engine.ts:883, service-automation/src/suspended-run-store.ts:147-150, service-job/src/db-job-adapter.ts:17-20, service-queue/src/common.ts:12-15.",
      "action": "NOT filed — searched first (repo:objectstack-ai/objectstack is:issue \"options?: any\"; 17 hits reviewed). These are a genuinely different axis from #6402: narrow local port interfaces that intentionally under-specify a structural contract, not class overrides diverging from their own base. Filing them as one finding would assert an equivalence I have not measured. Recorded here rather than as a speculative issue.",
      "posture": "observation only"
    }
  ],
  "open_questions": [
    "Scope call made under the self-drive clause rather than asked: narrowed 17 instead of the 5 named. Rationale above; the alternative (exactly 5) is a one-line revert but contradicts the issue's own no-partial-narrowing rule.",
    "Whether the turso 3 casts should fold into #6754's pass (total 30) or stay with #6394 is left to triage — flagged in the #6754 comment rather than decided here."
  ],
  "blocked": false
}

---

Generated by Claude Code

[os-zhuang]

CI converged on #6755 @ 78e8468 — all green, no fixes needed.

Workflow	Result
Lint & Type Check	✅ success (both jobs)
CI	✅ success
Duplicate Fix Guard	✅ success
Console Pin Freshness	✅ success
Check Links	✅ success
Docs Drift Check	✅ success
PR Automation	✅ success

Both jobs of the gate workflow passed every step — ESLint 40/40, TypeScript Type Check 37/37 (step 38 Save Turbo cache skipped, main-only by design). That confirms the local enumeration in the report above: the gates I ran one-by-one off .github/workflows/lint.yml are the same set CI ran, with the same verdict.

Worth naming three that were specifically at risk from this change, all green in CI:

• Engine query-options erasure ratchet — the decrease-only gate on any-erasure of options values. Passed, confirming the local read: turso-driver.ts is not in scripts/query-options-erasure-baseline.json (that ratchet scopes to engine query-options), and the new pin test adds no erasure, so testSurface.sites is untouched.
• Check no exported spec type resolves to any — green; the narrowing moves toward this gate's intent, not against it.
• driver-memory census and Check every driver runs the shared conformance cases — green, so narrowing all 17 signatures did not disturb the driver conformance surface.

The patch changeset is the only release-facing artifact; Release-notes drift guard and Release-body limit guard both passed.

PR #6755 is left as a draft, unmerged, per dispatch. No further action from me unless triage wants the scope reduced to the five originally named — that is a one-line revert, but it produces the partial-narrowing state the issue itself rules out, so I have not done it.

---

Generated by Claude Code

[os-zhuang]

ACCEPT — PR #6755 passed the step-7 review; marking it ready and enabling auto-merge.

What shipped: all 17 options?: any overrides in turso-driver.ts narrowed to DriverOptions (the dev's measured inventory superseded the body's 5 — narrowing only the named subset would have reproduced the partial-narrowing state the issue itself forbids; scope call endorsed), plus a compile-time pin (IsAny detector, one row per door) whose reverse verification matched its predictions exactly (18 errors: 17×TS1360 + 1×TS2578). The issue's measurement precondition was run: annotation-only, 0 call sites broken, 0 casts added. CI verified as job conclusions: all 24 checks success/skipped, including ESLint, TypeScript Type Check, Test Core ×3, and Temporal Conformance (live PG + MySQL). remote-transport.ts untouched. Changeset: patch, correctly reasoned (public signature narrowing is TS-consumer-visible).

Cross-validation note for the record: the #6394 dev independently measured the same widening (16 vs 17 — the delta is syncSchemasBatch); the two inventories agree in substance and #6755 covers the union.

---

Generated by Claude Code