driver-sql: `introspectSchema()` still diverges from the spec contract on `indexes` (required, never emitted) and `defaultValue` (declared `string`, emitted `null`)

[os-zhuang]

Found while landing #10676 / #10998 (the driver aligning to the spec introspection contract, maintainer ruling 2026-08-22 「同意所有」 item 9). That ruling names exactly three keys — primaryKey on columns, plus dialect and introspectedAt on the schema — and those are repaired. Two other keys of the same contract are still unconformed, and they are recorded here rather than absorbed into that PR, because neither is covered by the ruling.

1. IntrospectedTable.indexes is declared REQUIRED and is never emitted

packages/spec/src/contracts/schema-diff-service.ts:

export interface IntrospectedTable {
 name: string;
 columns: IntrospectedColumn[];
 indexes: IntrospectedIndex[]; // required
}

SqlDriver.introspectSchema() builds { name, columns, foreignKeys, primaryKeys } — no indexes, on every dialect (one construction site, sql-driver.ts). So a consumer typed against the spec contract may read table.indexes without a guard and get undefined.

This is cheap to repair and deliberately not repaired in that PR: the capability already exists. SqlDriver.introspectIndexes(tableName, { onFailure }) returns PhysicalIndex[] ({ name, columns, unique, primary }), which is the spec's IntrospectedIndex ({ name, columns, unique }) plus one member. What is missing is the wiring plus two decisions that are not a dev's to take alone:

• cost: it adds one index read per table to every introspectSchema() call, including the federation path that introspects a whole remote warehouse;
• failure policy: introspectIndexes takes onFailure: 'throw' | 'partial' for the reason driver-sql: introspectIndexes swallows every error and returns a partial index list, which the drift differ then reports as missing indexes #7332 documents. Which one an introspection snapshot wants is a real choice — a partial index list is what the drift differ misreads as missing indexes.

⚠️ In the meantime the type in driver-sql / objectql Omits indexes from the spec table rather than emitting indexes: [], on purpose: an empty array tells a schema differ the table HAS no indexes, which is worse than an absent key.

2. IntrospectedColumn.defaultValue is declared string, and the producers emit other types

The spec declares defaultValue?: string. Measured on a live in-memory SQLite database, the driver's own output for t.string('id').primary():

{"name":"id","type":"varchar","nullable":true,"defaultValue":null,"primaryKey":true,"isUnique":true,"maxLength":"255"}

defaultValue is null — it is whatever knex.columnInfo() reported. In-tree fixtures also carry non-strings (packages/objectql/src/util.test.ts has defaultValue: true for a boolean column). The IntrospectedColumn in driver-sql and objectql therefore keeps defaultValue?: unknown (spelled as an explicit Omit from the spec type, so the divergence is visible rather than accidental).

Repairing it means deciding which side is right: normalise the producer to a string expression (and drop null rather than emit it), or widen the spec declaration. Both are contract decisions.

Same measurement note: maxLength came back as the STRING "255" while the SQL-layer type declares number. Same class, same site, listed here so it is not re-discovered separately.

Not measured

SQLite only. Postgres and MySQL were read, not run — no server is reachable from the container this was measured in. Both keys are built at a single dialect-independent site, so the SHAPE cannot vary by dialect; per-dialect CONTENT is not claimed.

Filed unassigned as a finding from #10676 / #10998; not fixed there because the ruling that released those cards does not cover these keys.

[os-zhuang]

Triage: 入决策箱(needs-user-decision + domain:spec,类型 Bug)。两个键都是契约裁定,分诊不代裁。

一句话问题:平台向外承诺的「数据库结构快照」里,一个必填字段从来没人给(indexes),另一个字段给出来的类型跟承诺不符(defaultValue 说是字符串,实际给 null/布尔)——按承诺写代码的消费者拿到 undefined 就崩。

选项 × 真实代价

选项	做什么	客户可感知代价
A	兑现承诺:introspectSchema 接线索引读 + defaultValue 拓宽为实际类型	每张表每次快照多一次索引读(联邦整仓 introspect 变慢),还要先裁 onFailure 策略(partial 的索引表会被漂移比对误读成「索引丢了」)
B	撤回没兑现过的承诺:indexes 改 optional;defaultValue 拓宽为实际类型	消费者失去「必有 indexes」的字面承诺(该承诺从未真实兑现过,今天信它的人只会崩)
C	producer 归一:defaultValue 全部序列化成字符串	失真(布尔默认值变字符串),producer 复杂化

业务直译:B = 商品页把「附赠配件」一栏从「必附」改成「视型号」,因为仓库从来就没配过;A = 真去配,但配送变慢且要先定「配件缺货时发不发货」。

四轴(业务立场)
① 长远合理性:声明与兑现一致是底线;先止谎(B),接线(A)等真实需求拉动再做,两步不冲突。
② 实际业务拉动:今天没有任何消费者成功读过 indexes(读了必拿 undefined)——零拉动的承诺不值得为它加每表一次的快照成本。
③ 防 AI 犯错:假承诺字段正是 AI 写消费代码时的坑(类型系统说必有,运行时没有);B 让类型系统说真话。
④ 创业阶段不扩散:不为无人消费的能力面付实现与运维成本;Omit 变通已经把分歧标记出来,收敛它。

推荐 B(两键同 PR:indexes 收窄 + defaultValue/maxLength 按实测拓宽),回退 A(若你认为快照就该含索引,则连带裁 onFailure:throw 还是 partial)。
置信缺口:本分析未测 spec 之外(cloud / objectui)是否存在读 indexes 或依赖 defaultValue: string 假设的消费者;Postgres/MySQL 只读码未运行(卡内已声明)。
回一个字母即可;「B,但 indexes 留必填」= 自动落到 A。

裁后执行:B ⇒ spec 席条款②档位派发(改声明 = 改接受集),同 PR 撤 driver-sql/objectql 的 Omit 变通注记;A ⇒ 先在本卡追一行 onFailure 裁定再派。

---

Generated by Claude Code

[os-zhuang]

[facets-block]

• 业务需求:指向 B —— 零消费者成功读过 indexes,为无拉动承诺付每表一次快照成本不值
• 长远合理:指向 B —— 先让声明说真话;接线等真实需求再做,两步不冲突
• 防 AI 错:指向 B —— 类型系统承诺必有、运行时没有,正是 AI 消费代码的坑
• 阶段聚焦:指向 B —— 不为无人消费的能力面付实现与运维成本
  推荐:B(indexes 收窄 optional + defaultValue/maxLength 按实测拓宽;接线另立卡)· 置信缺口:cloud/objectui 是否有依赖该承诺的消费者未测;PG/MySQL 只读码未运行

---

Generated by Claude Code

[os-zhuang]

Maintainer ruling recorded (2026-08-23, live PM chat, verbatim: 「其他同意你的意见」— adopting recommendation B): withdraw the never-honored promise — IntrospectedTable.indexes becomes optional; IntrospectedColumn.defaultValue (and the noted maxLength) widen to the measured emitted types. Wiring the index read (option A) is NOT authorized here; if real consumer demand appears, that is a new card with its own onFailure ruling.

State: needs-user-decision → pm:queue, domain:spec (same stroke). Dispatch constraints: Clause-② yes (declaration change — contract-review tier); the same PR retires the deliberate Omit workarounds in driver-sql/objectql and their explanatory notes; premise check first — verify no consumer in cloud/objectui reads table.indexes or assumes defaultValue: string (the recorded gap) and report readings; a found consumer forks back here rather than being silently accommodated.

---

Generated by Claude Code