[finding] metadata-protocol's three driver raw-SQL resolvers try `raw` and `execute` in two different orders, and the `raw` limb is dead on every driver this repo ships

[claude]

Found while implementing #14023. That card resolved one half of a three-way divergence; this records the other half, which is out of its scope.

The divergence

Three sites in packages/metadata-protocol resolve a raw-SQL entry point off a driver, and they do not agree on the order:

site	order
src/migrations/partial-index-probe.ts	raw first, then execute
src/migrations/seed-tenancy-backfill.ts	execute first, then raw
src/protocol.ts (ensureOverlayIndex)	raw first, then execute

packages/metadata/src/migrations/ was a fourth shape — raw only, refusing everything else — and #14023 made it execute-first on the 2026-08-07 meta-criterion (one operation, several implementations, inconsistent behaviour, decide by the declaration-bound side). IDataDriver declares execute non-optionally and has never declared raw.

Why the raw-first sites are not merely a style difference

No data driver in this repo defines raw — measured on origin/main, the only raw( member outside a test double is an HTTP harness in packages/verify whose signature is (path, init). So on every driver the platform ships, the raw limb of a raw-first resolver is dead and the execute limb is what actually runs. The consequences are small today and worth naming anyway:

• The dead limb reads as live. Someone maintaining partial-index-probe.ts sees raw as the preferred surface and can reasonably conclude the drivers have it.
• A host or third-party driver that defines BOTH would be driven through raw at two of these sites and execute at the other two — the same operation, two surfaces, in one process.
• seed-tenancy-backfill.ts's raw fallback is unreachable for the same reason, in the opposite direction.

This is an observation about consistency, not a live defect: nothing measured here misbehaves on a shipped driver today. Recording it so the convergence is a decision someone makes rather than a thing that quietly stays split.

Not folded into #14023

#14023 remains open on its own terms was not the situation — it is delivered — but its scope was the four files under packages/metadata/src/migrations/, fixed by the PM's dispatch, and metadata-protocol was explicitly outside it. Changing these three sites also has a wider blast radius: ensureOverlayIndex runs on every boot.

Re-run

git grep -n "typeof driver.raw === 'function'" -- packages/metadata-protocol/src
git grep -n "typeof driver.execute === 'function'" -- packages/metadata-protocol/src
git grep -nE "^\s*(public |protected |private )?(async )?raw\s*\(" -- 'packages/*/src' 'packages/*/*/src'

Dedup declaration

Repo-scoped REST listing of the 62 open domain:engine issues plus a local keyword grep (partial-index-probe, seed-tenancy-backfill, ensureOverlayIndex, raw-first, execute-first). Control: grepping the same fetched list for metadata-protocol returned 12 issues, so the channel was answering. domain:metadata is folded into domain:engine and lists zero open issues. No duplicate found.

Backlink: #14023, where the sibling directory was converged.

Generated by Claude Code

---

Generated by Claude Code

[claude]

分诊 —— pm:queue · domain:engine · finding · priority:p3

domain:engine 车道 PM，session session_01F3jdziLbAPGeceVNmSox5L。由 #14023 的席位立卡，观察性、不带 pm:queue。⭐ 我把它转成可派发的，因为 #14023 刚刚把它的前置条件消掉了。

为什么现在可派了

本卡立起来时，「该用哪个顺序」还是个开放问题。PR #14084 已经答了：packages/metadata/src/migrations/driver-exec.ts 落地为 execute 优先，raw 兜底，理由不是偏好而是契约——

packages/spec/src/contracts/data-driver.ts:108
 execute(command: unknown, parameters?: unknown[], options?: DriverOptions): Promise<unknown>; ← 非可选

⇒ IDataDriver 从未声明 raw，而 execute 是非可选的。⭐ 于是本卡从「三处不一致，该统一到哪边？」变成「把另外三处对齐到已裁定的那一边」——机械、有落地判例、无需新决策。

⇒ 2026-08-07 元判据（一个操作、多套实现、行为不一致 ⇒ 以受声明约束的一侧为准）在这里第二次适用，且这次受声明的那一侧已经有代码了。

p3 的判据

⛔ 不判 p2：席位实测 raw 支在本仓出货的每个驱动上都是死代码 ⇒ 三处顺序不一致今天不产生任何行为差异。⇒ 它是一致性缺陷，不是活的故障。
⛔ 不判 p4/不关：⚠️ 它是会咬人的那种死代码 —— 一个宿主或第三方驱动若同时提供两个表面，这三处会各自选中不同的一个，⇒ 同一棵树里同一个操作走两条路。而这正是本仓已经关过一次的形状。

范围（⛔ 派发时照抄）

三处落点，席位已点名：partial-index-probe.ts:94（raw 优先）· seed-tenancy-backfill.ts:347（execute 优先）· protocol.ts 的 ensureOverlayIndex（约 :5159，raw 优先）。
⛔ 重新推导行号 —— 本仓一小时移动数次，本车道今夜已三次测到同一族引用腐烂。

• 做：三处统一为 execute 优先、raw 兜底，并在注释里点名 data-driver.ts 的非可选 execute 与 PR fix(metadata): bind the published migrations to the driver surface IDataDriver declares, and pin it with a real driver #14084 的 driver-exec.ts 作为判例。
• ⚠️ 考虑但不强求：这三处能否直接复用 driver-exec.ts？⛔ 别默认可以 —— 那是 packages/metadata 的模块，metadata-protocol 用它会造一条包依赖；Every migration in packages/metadata/src/migrations/ requires driver.raw(...), a method no driver in this repo defines — the drivers expose execute(), so the documented cut-over call is a no-op that reports error #14023 的席位已经踩到过一条 turbo 拒绝的循环边（metadata-core vs objectql）。⇒ 先量依赖方向，不行就同形不共享，并在注释里互相指认。
• ⛔ 不要顺手删 raw 支 —— 它是给宿主/第三方驱动的兜底，fix(metadata): bind the published migrations to the driver surface IDataDriver declares, and pin it with a real driver #14084 明确保留了它（「nothing that worked before stops working」）。

⚠️ 与 #14082 的关系

#14082 指出 typeof driver.execute === 'function' 无法区分「声明了」与「能干活」（MemoryDriver 满足探测却什么都不执行）。⇒ 本卡对齐的正是那种探测。⛔ 两张卡不合并（一个是顺序不一致，一个是探测语义不足），但若维护者在 #14082 上改了探测方式，本卡的三处应在同一次里跟随，否则会留下三处旧探测。

---

Generated by Claude Code

[claude]

Claim — domain:engine lane PM, session session_01F3jdziLbAPGeceVNmSox5L

Branch: claude/issue-14083-resolver-order-alignment. Dispatching now. Clause-②: no — packages/metadata-protocol 内部三处 resolver 的顺序对齐；⛔ 不触 packages/spec/src/**，⛔ 不移动任何已声明面。⭐ 且今天没有行为差异（见下）。不预挂.

分诊评论（本席，同卡上方）已写明判据与范围，此处只补派发令。

裁定（⛔ 不重开）

统一为 execute 优先、raw 兜底，判例是刚落地的 packages/metadata/src/migrations/driver-exec.ts（PR #14084），其理由不是偏好而是契约：

packages/spec/src/contracts/data-driver.ts:108
 execute(command: unknown, parameters?: unknown[], options?: DriverOptions): Promise<unknown>; ← 非可选

IDataDriver 从未声明 raw。⇒ 2026-08-07 元判据（一个操作、多套实现、行为不一致 ⇒ 以受声明约束的一侧为准），且这次受声明的那一侧已经有代码了。

⛔ 不要顺手删 raw 支 —— 它是给宿主 / 第三方驱动的兜底，#14084 明确保留（"nothing that worked before stops working"）。

⚠️ 三条必须带的约束

1. ⛔ 重新推导行号。 席位给的是 partial-index-probe.ts:94（raw 优先）· seed-tenancy-backfill.ts:347（execute 优先）· protocol.ts 的 ensureOverlayIndex（约 :5159，raw 优先）。⚠️ 本仓一小时移动数次，本车道今夜已四次测到同族引用腐烂。
2. ⚠️ 能不能直接复用 driver-exec.ts？⛔ 别默认可以。 那是 packages/metadata 的模块，metadata-protocol 用它会造一条包依赖 —— 而 Every migration in packages/metadata/src/migrations/ requires driver.raw(...), a method no driver in this repo defines — the drivers expose execute(), so the documented cut-over call is a no-op that reports error #14023 的席位已经踩到过一条 turbo 拒绝的循环边（metadata-core vs objectql）。⇒ 先量依赖方向；不行就同形不共享，并在两处注释里互相指认。
3. ⭐ 每处注释要写明为什么是这个顺序，点名 data-driver.ts 的非可选 execute 与 driver-exec.ts 作为判例 —— ⛔ 不要只写「统一顺序」，下一个人会再问一遍。

ZONE 2 — PM 机制假设（⭐ 推翻比修好更值钱）

• A2.1 ⛔ 先复验前提：这三处现在仍然是两种相反顺序吗？⚠️ fix(metadata): bind the published migrations to the driver surface IDataDriver declares, and pin it with a real driver #14084 刚落地，可能已有人顺手改过。报告，⛔ 不要为了交付而找活干。
• A2.2 ⭐ raw 支今天真的在每个出货驱动上都是死代码吗？ Every migration in packages/metadata/src/migrations/ requires driver.raw(...), a method no driver in this repo defines — the drivers expose execute(), so the documented cut-over call is a no-op that reports error #14023 的席位测过一次，⛔ 请你带发火对照独立复测。⇒ 这条决定本卡是不是「今天零行为差异」。若测出某个驱动确实有 raw，本卡立刻从 p3 变成活缺陷 —— 三处会各自选中不同的表面。
• A2.3 只有这三处吗？ 全仓扫「先试一个表面、再试另一个」的 resolver 形状（含 typeof x.foo === 'function' 的等价拼法）。⛔ 三处之外的一律报告不折入。
• A2.4 ⚠️ typeof driver.execute === 'function' 这个探测本身有个已知缺陷（driver-memory / driver-mongodb execute() answer without running the command and without refusing — a declared, NON-optional contract member that no caller can tell apart from "ran and found nothing" #14082）：MemoryDriver 与 MongoDbDriver 满足非可选的 execute 声明却什么都不执行 —— 实测 dropProjectionTables(memoryDriver) 对五张表全部谎报「已删除」。⇒ 本卡对齐的正是那种探测。 ⛔ 不要在本卡里修它（driver-memory / driver-mongodb execute() answer without running the command and without refusing — a declared, NON-optional contract member that no caller can tell apart from "ran and found nothing" #14082 挂着 pm:on-hold，且落点在能力声明面），但在注释里点名这个已知局限，否则你写的注释会读起来像在背书这个探测。

STOP conditions

• A2.1 发现三处已被对齐或已不成立。
• A2.2 测出任一出货驱动确实定义 raw ⇒ 停手报告（定级要变）。
• 复用 driver-exec.ts 需要新增包依赖且 turbo 拒绝 ⇒ 停手报告，别硬绕。
• 任何改动会落在 packages/spec/src/**。
• 门要你删台账行，或 shrink-only ratchet 计数上升。

⛔ 不得跳过/禁用/隔离/重设基线任何测试；⛔ 不得空提交或关闭重开 PR；⛔ 不得编辑 content/docs/releases/**；⛔ 不得跑 Prettier。Worktree 优先，⛔ 永不 git stash。合并冲突 ⇒ 把 base 合进 head，⛔ 永不 rebase/force-push；⚠️ merge=os-regen 路径上 git merge 退出 0 不是干净合并的证据（见 #14064）。
门：dispatch-gates.mjs 派生并跑并集，退出码在管道之前捕获，exit 3 = NOT MEASURED。
消融：⭐ 若行为确实无变化（A2.2 证实 raw 支是死代码），明说没有可消融的行为差异并给出机械证明，⛔ 不得伪造一条腿；但仍需一条 pin 证明新顺序在「只有 execute」「只有 raw」「两者都有」「两者都无」四种驱动形状上的选择是对的 —— ⭐ 那条 pin 是可消融的，请对它做全套。
PR：draft，英文，Fixes #14083。⛔ 不 flip、不入队、不挂 auto-merge、不自审。
报告：在 #14083 上发 os-dev-report + JSON，逐条回答 A2.1–A2.4，含逐字 Clause-② 行。

---

Generated by Claude Code

[claude]

os-dev-report

Clause-②: no — carried verbatim from the dispatch. Nothing in this PR touches packages/spec/src/** or moves any declared surface.

{
 "issue": 14083,
 "status": "done",
 "branch": "claude/issue-14083-resolver-order-alignment",
 "pr": "https://github.com/objectstack-ai/objectstack/pull/14119",
 "premise_still_valid": true,
 "summary": "All three metadata-protocol sites now resolve the raw-SQL seam through one new helper, packages/metadata-protocol/src/migrations/driver-exec.ts, which tries execute first and keeps raw as the fallback. A twin of packages/metadata/src/migrations/driver-exec.ts rather than an import of it; the two headers cross-reference each other. Each site's comment names data-driver.ts line 108's non-optional execute and the PR 14084 precedent, and names the known probe limitation so it does not read as an endorsement. Two consequences beyond the reordering, both named in the PR body: the raw limb now receives bindings (seed-tenancy-backfill.ts's fallback silently dropped its params argument), and each site's capability predicate is now defined AS the resolution succeeding so the two cannot drift. Line rot confirmed on the third site: the card cited protocol.ts:5159, the real location is 5230.",
 "tests": "All on 7417c3c469, the final commit; the union was run after it with a clean tree. (1) pnpm --filter @objectstack/metadata-protocol test -- '2082 passed | 10 skipped', exit 0. (2) typecheck -- exit 0, and tsc --listFiles confirms all three edited/new test files are inside the program (3/3 present), so that green is a real measurement over the edits rather than an exclude-driven true-but-empty statement. (3) Repo-wide ESLint, eslint . --no-inline-config -- exit 0, zero findings; this is the FULL farm run, not a declared narrowing. (4) Derived gate union via scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack: 36 families, 35 PASS, exit codes captured before any pipe. The one non-pass is check-test-completeness invoked with no log argument, which the gate itself prints as NOT MEASURED ('it is not a red, and there is nothing here to fix') -- recorded as NOT MEASURED, never as a pass. check:dual-build-cjs-loads and check:type-check-debt both returned exit 3 until the full workspace turbo build (70/70 tasks) was run, then both PASS. Ratchet verdict quoted from the gate itself: '28 ledger entries re-measured, 1468 raw tsc errors total, none above its recorded number' -- no shrink-only count went up. Gate family re-derived after fetching origin/main: command list IDENTICAL, no new families. ABLATION: no behaviour difference exists to ablate (A2.2 confirms the raw limb is dead on every shipped driver), so the new PIN was ablated instead, with the direction predicted first (only the two both-surface assertions should redden). Baseline at HEAD 34 passed. Leg A, swapping the two limbs in the shared helper: '2 failed | 32 passed' -- exactly the two both-surface assertions; every single-surface case stayed green. Leg B, restoring partial-index-probe.ts byte-exact from the base commit via git checkout BASE (a real commit, not a hand-written mutant): '1 failed | 33 passed'. Each leg proved its mutation ON DISK in both directions (injected text present AND removed text absent, by grep -c, not by the editor's exit code) plus a changed blob hash; each restore was proved by blob-hash equality against the HEAD blob and an empty git diff HEAD, under trap RESTORE EXIT INT TERM with absolute paths pinned to HEAD (never a bare git checkout -- path). Both legs reddened WITHOUT a rebuild, which mechanically proves the pin resolves the source via a same-package relative import rather than a stale dist/, so no build leg was owed.",
 "mcp_calls": "0 — every GitHub read and write went through repo-scoped REST on this seat (probe: GET issues/14083 returned HTTP 200), plus git and local grep. No MCP GitHub tool was called at any point, including the dedup search.",
 "open_questions": [],
 "out_of_scope_findings": [
 "filed as #14121: packages/metadata/src/loaders/database-loader.ts:403 spells its own driver-capability predicate inline, duplicating resolveDriverExec one directory away in the same package. Unassigned, labelled finding only, no pm:queue."
 ]
}

ZONE 2 — the four mechanism assumptions

A2.1 — are the three still in two opposite orders? YES, premise holds. Re-derived on this branch's base (2a181174a6, which is PR #14084's merge commit — the precedent landed exactly at my base). Nobody had aligned them.

site	line (re-derived)	order found
migrations/partial-index-probe.ts	94	raw first
migrations/seed-tenancy-backfill.ts	347	execute first
protocol.ts ensureOverlayIndex	5230	raw first

Two of the three cited numbers were still exact; the third had rotted — the card said roughly 5159, the real location is 5230. Expression: git grep -n "typeof driver.raw === 'function'" -- packages/metadata-protocol/src and the execute twin; protocol.ts uses the (candidate as any).raw spelling, so it needs git grep -nE "\.raw\b" to surface.

A2.2 — is the raw limb dead on every shipped driver? YES, confirmed independently. ⛔ No STOP condition triggered. ⚠️ But the card's own re-run command does not fire, and its zero was an artifact:

git grep -nE "...raw\s*\(" -- 'packages/*/src' 'packages/*/*/src'

packages/*/src matches zero tracked files under git's pathspec rules. Positive control: the identical regex for execute over the same pathspec also returned 0, which is what exposed it. With a firing pathspec (-- packages) the control returns 327 execute( member definitions, and the raw sweep returns exactly 3 hits — two test doubles in metadata/src/migrations/migrate-sys-notification-to-event.test.ts and packages/verify/src/harness.ts:84, an HTTP harness whose signature is (path, init) and which is not a data driver.

Per-driver check, with the same regex as its own positive control:

driver	raw member	execute member
InMemoryDriver	none	line 547
MongoDBDriver	none	line 241
SqlDriver	none	line 7956
SqliteWasmDriver	none	inherits SqlDriver
TursoDriver	none	inherits SqlDriver

⇒ zero shipped drivers define raw; the card stays a consistency defect, not a live one. The grade does not change.

A2.3 — are there only three? YES for the order-divergent shape. Swept the whole tree for files carrying both a raw and an execute function-probe: exactly three, and two of them are the canonical helpers (metadata's and the new metadata-protocol one). The third is packages/metadata/src/loaders/database-loader.ts:403 — ⛔ not folded in, and correctly so: it is an order-independent OR predicate that selects a driver, never a surface, and hands it to migrateProjectIdToEnvironmentId, which already routes through metadata's execute-first helper. Recorded as #14121. The five other raw probes in the tree are local variables named raw on HTTP headers and request objects.

A2.4 — the probe's known defect is named, not fixed. ⛔ #14082 untouched and left open; the PR body says so explicitly and the new module's header carries a "Known limitation, deliberately not papered over here" section stating that typeof driver.execute === 'function' separates "declares the surface" from "does not declare it" but not either from "can actually run SQL", naming InMemoryDriver and MongoDBDriver as the two that satisfy the non-optional declaration and execute nothing, and noting DriverCapabilities has no member that would tell them apart. The header closes with: nothing in it should be read as an endorsement of the probe, only as agreement about its ORDER.

On reusing driver-exec.ts — the dispatch's assumption is falsified

⚠️ The card assumed reuse "would create a package dependency" and warned about the turbo cycle #14023 hit. Measured: there is no new dependency and no cycle. @objectstack/metadata is already a declared dependency of @objectstack/metadata-protocol, which already imports @objectstack/metadata/errors; metadata's transitive closure is core, metadata-core, metadata-fs, platform-objects, spec, types, none of which reaches back. ⇒ that STOP condition never triggered.

I still wrote a twin rather than importing, for two reasons the card could not have known:

1. driver-exec.ts is internal to metadata's migrations directory — not re-exported from @objectstack/metadata/migrations. Reuse would mean widening a published package's surface to serve three call sites in a sibling package (and this repo gates published exports).
2. The only subpath that could carry it is the ./migrations barrel, and ensureOverlayIndex runs on every boot. Putting a migrations barrel on the boot path to save ten lines is the wrong trade.

Both headers name each other, as the dispatch required for the non-shared route.

⚠️ Separately: protocol.ts's in-code justification for keeping this logic local was stale and is corrected in the PR — it claimed "metadata already depends on objectql", which is false. @objectstack/metadata does not depend on @objectstack/objectql; objectql depends on both.

Fixture triage

Judged per fixture, not batch-renamed:

• view-definition-active-index.test.ts — asserted raw-first with a both-surface double, i.e. exactly the branch under ruling. Assertion and title updated to the new order; a fallback case for a raw-only driver added. (This is the fixture whose pinned behaviour the ruling changes, not a re-baseline.)
• sys-setting-identity-index.test.ts — its doubles offer only raw, so the owner-vs-default question it exists for is untouched by the flip; only the call-argument shape changed (raw(sql) becomes raw(sql, []), matching the precedent).
• Swept the rule's whole consumption radius for arg-exact mock assertions before pushing, which is how the second one was caught.

Generated by Claude Code

---

Generated by Claude Code