feat(spec): declared media value shape — ADR-0104 D3 wave 1 + addendum#3443
Merged
Conversation
ADR-0104 addendum (2026-07-24): split D3 (file-as-reference) into two waves and
record the enforcement-point principle (build-time hard reject for AI-authored
metadata + runtime warn-first for deployed data). Makes explicit that D3 covers
the whole FILE_REFERENCE_TYPES media class (file/image/avatar/video/audio), not
just `file`.
Wave 1 (this change, single-repo, no migration): spec now exports
FileValueSchema — the declared inline media form ({url, name?, size?, mimeType?,
alt?, duration?}, url required) — tightening D1's loose transitional union so a
malformed media value is caught instead of waved through as an opaque payload;
the id/url string form stays accepted for import compat. Enforcement rides D1's
warn-first write path, so deployed records aren't stranded.
Wave 2 (accept/maxSize, sys_file reference model, GC, governed download,
protocol-major migration) is deliberately gated — not in this PR.
spec suite 6850 green (incl. new media-class cases); api-surface + generated
reference docs regenerated.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SHpGw3GBA9aFpfwVArRWfd
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
github-actions
Bot
added
documentation
Contributor
📓 Docs Drift CheckThis PR changes 1 package(s): 104 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:
|
os-zhuang
marked this pull request as ready for review
July 24, 2026 14:57
7 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
承接 D1(#3429)/ D2(#3432),推进 ADR-0104 的 D3 第一波,并把 D3 的决策补记进 ADR。
背景:回答"除了 file,image 等是不是也算"
算,而且从 D1 起就是同一个类。 D1 已经把
file / image / avatar / video / audio五个都归进FILE_REFERENCE_TYPES——它们今天存同一种内联 blob、同样绕开sys_file、同样要一起改。D3 全程用file只是这个媒体类的简称,没有单独的 image 故事。本 PR 在 ADR 里把这点写明。ADR-0104 addendum(2026-07-24)
结合"企业级 + 未来主要由 AI 写元数据、要防 AI 犯错"的方向,对 D3 做了两点细化:
sys_file引用存储模型 + GC + 受治理下载 +accept/maxSize权威 enforce + 迁移,协议大版本,带 R4/R5/R6 硬性验收门,需与 objectui 同步。os validate报错),运行期 warn-first 只保护存量部署数据。目标终态是两个 enforcement point 各司其职——这也回头收敛 D1/D2 已落地的 warn-first 与 tracking: 翻转 ADR-0104 值形状/参数强校验为默认严格(D1 + D2 warn-first → error） #3438 的翻转策略。Wave 1 代码(spec,非破坏)
@objectstack/spec/data新增FileValueSchema:媒体类今天实际存的内联形态{ url, name?, size?, mimeType?, alt?, duration? }(url必填),替换 D1 那个宽松的过渡 union。valueSchemaFor(file 类, 'stored')现在能抓住畸形媒体值(数字、空对象、没有url的{name}碎片)——过去被当 opaque payload 放过;同时仍接受 opaque id/url 字符串形态(import 兼容)。Wave 1 刻意不做:不给
FieldSchema加accept/maxSize——它们治的是真实上传,权威 enforce 需要服务端知道真实字节(即sys_file模型),现在加就是 ADR-0078 禁止的惰性开关。归 Wave 2。测试
url,url-less 碎片被拒){url,...}形态全部仍通过)FileLikeValueSchema;api-surface(+FileValueSchema导出)与生成参考文档已同步。不在本 PR 范围
Wave 2 全部(存储迁移 / GC / 受治理下载 / 协议大版本 / objectui 同步)——按 ADR 与我的建议,它带不可逆风险且跨仓,需要单独排期 + 明确 go,不在此自动执行。
🤖 Generated with Claude Code
https://claude.ai/code/session_01SHpGw3GBA9aFpfwVArRWfd
Generated by Claude Code