Decision: DESIGN.md §10 asks for 300 seeded contract versions, but §03 makes `file` required and a seed cannot mint one

[hotlong]

Raised by card 08 (#18, seed data), by Claude Code session session_01KcrVDXSptwDukFsHPHPR1V, rather than editing the governed surface. DESIGN.md §01–§04 is a governed surface; §10 is the seed table.

The conflict

• §03 declares clm_contract_version with file* — required. src/objects/contract-version.object.ts implements it as Field.file({ required: true, accept: ['application/pdf', '.docx'] }).
• §10 asks for 300 seeded clm_contract_version rows ("谈判中的合同有 3 到 5 版，含对方红线").
• A file value is an opaque sys_file id minted by an upload. sys_file is a fileId-to-storage-key mapping; the bytes live in the storage backend under key. A declarative seed has no upload and cannot mint one.

Measured, three ways (@objectstack/* 17.3.0, sqlite, objectstack dev)

One seed load, three version rows differing only in the spelling of file:

1. file omitted — refused, and the whole row is lost:

   ERROR [SeedLoader] Failed to write clm_contract_version record #2
         (contract+version_no=... 1): File is required
   

2. file is a URL (https://example.invalid/probe.pdf) — the row inserts, and the platform then refuses to attest its own migration:

   WARN [migration] NOT attesting 'adr-0104-file-references' on this new datastore:
        this boot already wrote 1 value(s) that the migration's own contract rejects
        (clm_contract_version.file: Expected an opaque sys_file id).
   

3. file is an id-shaped token (probe-file-token-0001) — the row inserts silently, no warning, and reads back verbatim because no sys_file matches it. It is a download that 404s.

Positive control: the other 12 rows of the same seed load inserted without complaint, so the refusal in (1) is about the value, not the seed path.

Why card 08 shipped zero versions

Option 3 is the one a seed could get away with, and it is the one AGENTS.md forbids: "Honest capabilities. No AI output that is a stub; no seeded number that looks computed. A capability the runtime does not deliver is hidden, not faked." So #18 seeds no versions at all, version_count reads an honest 0 on every one of the 120 contracts, and this card carries the decision.

What that costs today

• The version timeline of §05 is empty, and the counterparty-redline story of §10 cannot be demonstrated from the seed.
• version_count is one of the five roll-ups §10 wants shown; it is the only one that reads 0 everywhere. (The other four are verified correct against their seeded children in Seed data: demo-en (default) and demo-zh (card 08, M2) #18.)
• A seeded draft cannot be submitted through the UI. The draft to submitted guard wants "至少一个版本文件或类型带模板", and the seed can supply neither, so the ten seeded drafts refuse submission with Upload a first version, or choose a contract type that carries a template, before submitting. Driving intake in the demo means creating a new contract and uploading a real file.
• The same wall applies to clm_contract_type.template_file and clm_signature.executed_file; both are optional, so Seed data: demo-en (default) and demo-zh (card 08, M2) #18 simply leaves them empty.

Options

A. Leave §03 as it is; the seed ships no versions. What #18 does today. Zero cost, zero risk, and the demo keeps a visible hole. The file* requirement is defensible on its own terms: a version without its document is not a version.

B. Have pnpm demo upload one real document and let the fixture reference it. The priming boot in scripts/demo.mjs already signs in; it could POST a small PDF, capture the returned sys_file id, and pass it to the demo boot as an environment variable the fixture stamps on all 300 rows. sys_file ownership is exclusive per (object, record, field), and the platform copies the bytes into a fresh row rather than sharing one, so 300 references are legal. Cost: the declarative seed gains a runtime dependency, and the fixture's row count becomes conditional on a variable — if the upload fails, the version dataset has to be dropped, silently changing what pnpm demo produces.

C. Relax clm_contract_version.file to optional in §03 and in the object, and move "a version must carry a document" into the state-machine guards that already read versions (approved to signing wants a current clean version; signing to active wants a final_signed one). Cost: an edit to the governed surface, and a window where a version row can exist with nothing attached — which is arguably what a "by template" version already is.

Recommendation: A now, C when a maintainer next opens §03. B buys the demo one artefact at the price of making the seed non-declarative and its row count conditional, which is a bad trade for a fixture whose whole design is that both locales produce provably identical rows. C is the honest long-term shape, but it is a §03 decision and #18 has no mandate to take it.

[zhuangjianguo]

维护者速读

⚠️ 拟稿，不是裁决。 总监席本场服役档 claude-opus-5 ≠ CONTRACT_REVIEW_TIER（claude-fable-5-1，dispatch-gates.mjs:10446，精确比较），四职停放，⛔ 不裁不清标。本评论只补这张卡欠的四棱块与速读。标签一动未动。

事情：设计方案第 10 章要 300 条合同版本种子数据，但第 3 章把版本的 file 定为必填，而 file 的值是一次上传才能铸出的 sys_file id —— 声明式种子没有上传，铸不出来。所以卡 08 一条版本都没种，version_count 在 120 份合同上诚实地读 0。

三种写法都实测过（17.3.0）：省略 file 整行被拒；写 URL 行进去了但平台拒绝为自己的迁移背书（NOT attesting 'adr-0104-file-references'）；写一个 id 形状的假 token —— 静默插入、无警告、原样读回，因为没有 sys_file 匹配它。第三种是种子唯一「蒙得过去」的写法，也正是 AGENTS.md 的 Honest capabilities 明令禁止的。卡 08 因此选了诚实的 0。

代价里最硬的一条，容易被当成小事：draft → submitted 的守卫要「至少一个版本文件或类型带模板」，种子两样都给不了，所以 10 份种子草稿一份都提交不了。要在 demo 里演示发起流程，只能现建一份合同再真上传一个文件。这不是数据稀疏，是展品演示不了自己的主流程。

你要做的：回一个字母，A 或 C（B 见下，不建议）。

四棱分析

卡片正文（英文，卡 08 所写）推荐「A now, C when a maintainer next opens §03」。四棱我算下来同意 A 与 C 的排序，但不同意分两阶段 —— 理由是成文纪律，见第四棱。

实际业务需求 — 偏 C。判据不是「表格上少 300 行」，是上面那条：种子草稿提交不了，§05 的版本时间线是空的，§10 的对方红线故事演示不出来。version_count 是 §10 要展示的五个汇总里唯一处处读 0 的一个。展品的第一职责是展现平台能力，这三样都是能力没被展现。

项目长远合理性 — 偏 C。§03 那个 file* 在自己的语境里站得住（没有文档的版本不是版本），但 C 指出的事实更强：「按模板生成的版本」本来就没有附件，所以「版本必须带文档」这条约束放在字段上就是过紧，放在状态机守卫上才准（approved → signing 要一个 clean 版本，signing → active 要一个 final_signed，两个守卫本来就在读版本）。C 是把约束搬到它该在的那一层。

防 AI 写错 — 偏 A，且这一棱要求你知道一件事：三个选项都不闭合真正的坑。真正的坑是上面第三种写法 —— 一个 id 形状的假 token 静默插入、原样读回、下载 404。那是平台侧的缺口，应用侧关不掉。A 保住诚实的 0（不写就不会写错）。C 会开一个「版本行存在但什么都没附」的窗口，从防错角度是负分，必须靠守卫补回来。B 最差：种子从声明式变成有运行时依赖，行数随一个环境变量条件化 —— 上传失败就静默少一个数据集，正是这个仓库反复在防的形状。

创业阶段不扩散 — 这一棱否决「分两阶段」。维护者 2026-08-27 逐字裁定：「项目在创业阶段，用户也很少，短期不考虑渐进。」staged 选项仅凭具名外部用户证据才可荐，这张卡拿不出。所以「A 现在、C 以后」不是一个可推荐的形状 —— 请在 A 与 C 之间选一个，现在付清。A 的成本是零、代价是展品长期带一个可见的洞；C 的成本是一次 §03 编辑加把约束移到守卫，代价是要把两个守卫写实。

结论：长远合理性与业务需求偏 C，防错偏 A，不扩散要求二选一而非分期。按「长远合理性权重恒 ≥50%、有实测拉动则荐长远形态一次付清」，拟推荐 C 一次付清，并要求同一批把 approved → signing / signing → active 两个守卫写成真闸门 —— 否则 C 就只是把必填删掉，那才是真的更糟。

若你偏保守选 A，请一并接受 §10 的 300 行改成 0 并写进文档：沉默地留着一个永远填不满的表格，是把矛盾推给下一张卡。

⚠️ 前提新鲜度 —— 这张卡的读数会过期

全部三次实测取自 @objectstack/* 17.3.0。#35 正在把应用推到 17.4.0（396 个 changeset、35 个 breaking 标记）。本卡的核心前提是「声明式种子铸不出 sys_file id」—— 那是一句平台能力断言，17.4 落地后必须重跑那三次探针再定。

⇒ 建议：这张排在 #35 落地之后。#6、#10、#14 不受影响，可以先决。

---

Generated by Claude Code