[design] ADR-0104: field runtime value-shape as a first-class contract (spec-owned), typed action handlers, file-as-reference

[os-zhuang]

纯设计文档:新增 docs/adr/0104-field-runtime-value-shape-contract.md(Status: Proposed),不含任何代码改动。

背景

#3405 / #3406(内联 lookup 参数的 reference 被 .strip 静默吃掉)修掉的是一个键;这份 ADR 处理它背后的类问题:**字段的运行时值形状(value shape)在整个平台里不是任何人的契约。**代码盘点(全部带 file:line 证据,见 ADR 正文)发现:

• 值形状知识在 4 处手工重复:record-validator.ts(私有 MULTI_CAPABLE_TYPES,单值 lookup / file / location 等完全不校验,line 341「opaque payloads」)、import-coerce.ts(6 份自己的类型集合)、driver-sql(JSON_COLUMN_TYPES / NUMERIC_SCALAR_TYPES)、verify/read-coercion.ts(只覆盖 3 个类型)。
• spec 导出的 3 个值 schema 全部无人消费,其中 2 个与实际存储直接矛盾(CurrencyValueSchema 说 {value,currency},实际存裸 number;LocationCoordinatesSchema 说 {latitude,longitude},field-zoo 存 {lat,lng})——正是 ADR-0078 禁止的「导出但惰性」。
• 动作参数声明(type/required/multiple/accept/maxSize)只喂给客户端弹窗;服务端 handleActions 原样透传 reqBody.params(http-dispatcher.ts:3882,MCP 路径同样),沙箱 input: unknown,handler 注册签名 (ctx: any) => any,现有 handler 全靠裸 as 强转。
• 文件字段存无 schema 的内联 JSON blob({url,name,size}),完全绕开平台已有的 sys_file 一等文件原语(生命周期 GC、下载鉴权、稳定 /files/:fileId 解析器)——attachment-lifecycle.ts:27-29 自己就写着字段列的引用是 join-row 计数看不见的。后果:无引用完整性、清空字段永久泄漏 blob、非附件文件全部匿名 capability URL、FieldSchema 里连 accept/maxSize 都没有、client.storage.upload() 甚至拿不到 fileId(complete 响应把它丢了)。

决策概要

• D1 — spec 拥有值形状契约:field-value.zod.ts 导出语义类型集合 + valueSchemaFor(field, form)(stored / expanded 双形态,把 lookup 展开多态显式命名);「现实优先」原则处理 3 个死 schema(currency 定为裸 number 并墓碑化旧导出等);4 个消费方收敛到同一来源;field-zoo 往返测试反向断言契约,防止契约与 oracle 漂移。
• D2 — 类型化 action handler:REST/MCP 派发时按声明 params 构建 Zod 校验(required / 选项成员 / multiple / 未知键报错——吸取 动作参数弹窗:内联 lookup 参数无法声明引用目标(配置被静默剥离 + 文案谎报「即将上线」) #3405 教训,不再静默剥离),defineAction 衍生 ctx.params 的静态类型,registerAction 收紧签名;file/image 参数走 fileId + 服务端按 sys_file 元数据实施 accept/maxSize。
• D3 — file-as-reference:文件字段存储形态改为 sys_file 的 fileId(multiple → 数组),展开形态为 spec 定义的 FileValueSchema(url 派生、永不落库);写路径维护引用行,接入 ADR-0057 既有 tombstone/reap GC;下载鉴权复用 attachments 模型,匿名 URL 变 opt-in;协议 major + 双读窗口 + os migrate 回填(外链 URL 进迁移报告,不静默丢弃,遵守 service-automation: update_record reports success when written fields are silently stripped — no observability for dropped writes (split from #3356) #3407 纪律)。
• D4 — 三阶段落地:非破坏收敛 → 参数强校验(与 feat(spec): let an inline lookup action param declare its reference target (#3405) #3406 同姿态:本来就坏的配置从无声坏变有声坏)→ 文件迁移(协议 major,objectui 同步跟进)。

备注

• 任务标题里引用的 fix(spec): PROTOCOL_VERSION 12→13 — restore package-major lockstep (unbreaks main) #2731 经核实是无关的已关闭 PR(PROTOCOL_VERSION 12→13 一行修复),应为引用失效;本 PR 按标题文字本身的范围执行。
• Alternatives considered 里记录了 5 个被否掉的方向(含「继续内联 blob 但补 schema」「只在客户端校验」等)及理由。

🤖 Generated with Claude Code

https://claude.ai/code/session_01SHpGw3GBA9aFpfwVArRWfd

---

Generated by Claude Code

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
spec	Ready	Preview, Comment	Jul 22, 2026 10:06pm