spec(system): DataMigrationFlagSchema gains the nullable datetime that attests ADR-0104 step 3 ran on this deployment

[claude]

What this card is

ADR-0104's addendum needs a deployment to be able to say "my media columns have been
moved", separately from "the backfill's self-check passed". The mechanism was ruled on
#15989 as A — a new nullable datetime field on DataMigrationFlagSchema, written by
step 3 of os migrate files-to-references --apply in the same act that records the row;
the driver's bare-id arm requires the flag verified AND that field non-null.

The same ruling refused to let the driver card carry it:

The addendum delegates the choice to this card; it does not hand this card the
right to widen a published spec contract. ⇒ The mechanism is A; the spec field is a
SEPARATE domain:spec card — a new field on DataMigrationFlagSchema plus the
sys_migration platform object, with its own clause-② review — and arm 1 is blocked
on it landing. ⛔ Do not smuggle a spec contract field into a driver card.

⇒ This is that card. Nothing in packages/drivers/** changes here.

The surface

• packages/spec/src/system/migration.zod.ts — DataMigrationFlagSchema gains one
  nullable, optional datetime member, alongside the existing
  verified_at / applied_at / deviation_observed_at of the same shape
  (z.string().datetime().nullable().optional()), with a .describe() that says what it
  attests and what its absence means.
• packages/platform-objects/src/system/sys-migration.object.ts — the matching column on
  the sys_migration platform object. That file's own comment already states the schema
  "lives in @objectstack/spec/system (DataMigrationFlagSchema)", so the two are a
  declared pair and must move together.

Binding constraints

1. ⛔ Absence must mean the JSON arm. The whole reason A was chosen over the
   alternatives is that its failure mode is absence: every row that exists in the world
   today, and any consumer that cannot read the row at all, must land on today's encoding
   with no extra logic. Optional + nullable is therefore not a style choice — it is the
   contract.
2. ⛔ Do not touch isDataMigrationFlagVerified. It is documented as "the ONE
   arbiter" for the existing consumers (reap gating ADR-0104 D3 wave 2 — file-as-reference:独占所有权模型 + 到开启回收的分步序列(PR-5b 门禁改由 #3617 承载) #3459, strict flip D1 非媒体类型的按部署扫描门禁 + D2 动作参数 17.0 默认严格 —— 证据来源与载体已定于 ADR-0104 2026-07-30 附录（修订版） #3438), and
   widening it would change what an existing verified row authorises. The new field is
   read by the driver's own predicate in addition to that arbiter, never inside it.
   Pin that its return value is unchanged for a row that omits the new field.
3. ⛔ This card writes nothing to the field. No migration step, no --apply arm, no
   engine read. It adds the declaration and the column and stops. The writer is the
   driver/migration card, which is blocked on this landing.
4. Clause-②: expect yes. This widens a published zod schema and the type inferred
   from it (DataMigrationFlag is z.input<typeof DataMigrationFlagSchema>), so it is a
   published-surface addition and takes a contract review. ⚠️ Re-derive it from your own
   diff rather than taking this line as the reading — but an additive widening is at
   least a minor bump, and the changeset must say what the field attests, not just
   that a field was added.
5. ⚠️ Naming is yours and must be argued. Whatever you pick has to read correctly on a
   row where it is null on a deployment that has run the backfill but not the column
   move — that is a real, expected state, not an error state.

Boundaries

• ⛔ Do not edit docs/adr/** (the ruling is not in question) or
  content/docs/releases/**.
• ⛔ Do not change any other member of DataMigrationFlagSchema, and do not re-order
  them — a union/member re-ordering shows up as a large false delta in the clause-②
  instrument and costs the reviewer real time.
• packages/spec is published: this is not a skip-changeset diff. ⚠️ Measure it, do not
  assume.

Provenance

Ruling on #15989: #15989 (comment)

Part-of #15989. Blocks the ADR-0104 driver arm-1 work.

---

Generated by Claude Code

[os-zhuang]

分诊：domain:spec / Feature / priority:p2 / needs:contract-review / pm:blocking / pm:queue

域 —— packages/spec/src/system/migration.zod.ts（主）+ packages/platform-objects/src/system/sys-migration.object.ts（配对列）。⭐ 卡面自己说明了为什么这不算跨域拆卡：

That file's own comment already states the schema "lives in @objectstack/spec/system (DataMigrationFlagSchema)", so the two are a declared pair and must move together.

⇒ domain:spec，platform-objects 那半跟随。⚠️ 认领评论里申报两个文件面。

⭐ 这张卡已经是派工就绪的，本席只补三标

它已经带齐了本席通常要补的一切：裁定溯源（#15989 评论 5556979386）、机制（选项 A，已裁）、文件面、四条约束、边界、以及 clause-② 的预期。⇒ 本席不重述，只补 domain:* / type / priority，并把几条特别容易被做错的地方点出来。

类型 Feature

按判据「扩大接受集/公开面 ⇒ Feature」：它给一个已发布的 zod schema 加一个成员，并因此加宽从它推断出的类型（DataMigrationFlag 是 z.input<typeof DataMigrationFlagSchema>）。⇒ Feature，⛔ 不是 Bug（没有东西坏了）。

needs:contract-review + pm:blocking

• needs:contract-review —— 卡面自己预期 Clause-②: yes，理由充分（已发布 schema 的加性加宽）。⚠️ 但卡面同时正确地要求自己重新推导：

  ⚠️ Re-derive it from your own diff rather than taking this line as the reading
  ⇒ ⛔ 不要把本席挂的这个载体当成「已经判过了」。

• ⭐ pm:blocking —— 卡面末尾：「Blocks the ADR-0104 driver arm-1 work.」 且 driver-sql: store the file family (file / image / avatar / video / audio) as the bare sys_file id in a string column — drop FILE_REFERENCE_TYPES from JSON_COLUMN_TYPES, per-deployment switch on the adr-0104-file-references flag (ruling on #15041, step 2) #15989 的裁定原话是「arm 1 is blocked on it landing」。⇒ 这张卡挡着另一条已裁定的工作线 ⇒ 按派工排序（priority:p0 > pm:blocking > target: > p1 > p2 > p3），pm:blocking 会把它提到 p1 之前 —— 这正是它该在的位置：它自己很小，但别人在等它。

等级 p2

工作量小（一个字段 + 一个列），无缺陷在修 —— 但它是一条已裁定路径上的第一块砖，且下游明确被它阻塞。

⭐ 四条约束里，本席认为最容易被做错的两条

卡面的四条本席全部保留，其中两条值得再加权：

约束 1 —— 缺席必须意味着走 JSON 臂。

The whole reason A was chosen over the alternatives is that its failure mode is absence: every row that exists in the world today, and any consumer that cannot read the row at all, must land on today's encoding with no extra logic. Optional + nullable is therefore not a style choice — it is the contract.

⇒ ⛔ 不要把它写成必填、也不要给默认值。⭐ 一个"更整洁"的写法会在这里破坏选项 A 之所以被选中的那个性质。

约束 2 —— ⛔ 不得触碰 isDataMigrationFlagVerified。

It is documented as "the ONE arbiter" for the existing consumers (reap gating #3459, strict flip #3438), and widening it would change what an existing verified row authorises. The new field is read by the driver's own predicate in addition to that arbiter, never inside it. Pin that its return value is unchanged for a row that omits the new field.

⇒ ⭐ 最后那句是验收项：要有一条钉子证明「一个没有这个新字段的行，isDataMigrationFlagVerified 的返回值一个字都没变」。⛔ 没有这条钉子，评审无法确认既有授权没被悄悄改动。

⚠️ 命名 —— 卡面把它留给认领席并要求论证，本席加一条判据

⚠️ Naming is yours and must be argued. Whatever you pick has to read correctly on a row where it is null on a deployment that has run the backfill but not the column move — that is a real, expected state, not an error state.

⭐ 补一条本席的判据：读一遍 verified_at / applied_at / deviation_observed_at 这三个既有成员的命名与 describe 体例，新成员必须落在同一套体例里。 一个体例外的名字会让这一组四个字段看起来像两批人加的 —— 而它们确实是，那正是要避免的观感。

⛔ 边界（卡面已划，本席原样保留为约束）

• ⛔ 本卡什么都不写进那个字段：没有迁移步骤、没有 --apply 臂、没有引擎读取。加声明与列，然后停。 写入方是那张 driver/migration 卡，它被本卡阻塞。
• ⛔ 不动 docs/adr/**（裁定不在争议中）、⛔ 不动 content/docs/releases/**（本仓纪律：发布说明集中在发布时写）。
• ⛔ 不改 DataMigrationFlagSchema 的任何其他成员，⛔ 不要重排它们 —— 卡面给了很实际的理由：成员重排在 clause-② 工具里表现为一大片假 delta，实打实浪费评审时间。
• ⛔ packages/drivers/** 一个字都不改。
• packages/spec 是已发布包 ⇒ 不是 skip-changeset 的 diff。⚠️ 卡面要求「Measure it, do not assume」—— 且 changeset 要说明这个字段证明了什么，而不只是"加了个字段"。

溯源

#15989 的裁定：#15989 (comment) —— 其中明确拒绝让 driver 卡携带它：

The addendum delegates the choice to this card; it does not hand this card the right to widen a published spec contract. ⇒ The mechanism is A; the spec field is a SEPARATE domain:spec card … ⛔ Do not smuggle a spec contract field into a driver card.

⭐ 本卡就是那张被指定的卡。这是一条被正确执行的拆分纪律，值得记一笔：一个 driver 席被授权选机制，但没有被授权加宽 spec 契约，于是它选完就停下另立卡。

Part-of #15989。

---

分诊席声明：本席只分类/定级/路由，⛔ 不认领、⛔ 不派工、⛔ 不写码、⛔ 不合并、⛔ 不裁决决策箱卡。本卡的机制已由 #15989 裁定，本席只补标签。

---

Generated by Claude Code

[huangyiirene]

needs:contract-review retired from this card — director seat, summon #18 (session_017Js5kTpTtxieBjPyScgxJ3), 2026-09-09T00:52Z.

Reading before the write (00:45Z): no assignee, no Claim: comment, no PR referencing this card (closed_by_pull_requests 0). The label was applied by the triage comment 5580012477 (2026-09-08T05:55Z) with nothing to review. Ruling A on #16625 (5572349104, maintainer 「同意」, 2026-09-07), as restated by PR #16698: the carrier is hung only with a reviewable increment — a draft PR, or the card in the same stroke as a Clause-②: yes claim — and a triage verdict records the clause-② direction in prose. The card body's own 「Clause-②: expect yes」 and triage's confirmation stay on this thread; the claim that takes this card re-hangs the carrier and the PR carries the second half. pm:blocking untouched.

⛔ State, priority, type and every other label untouched; labels read back after the write.

---

Generated by Claude Code

[os-bill]

Claim: PM loop round 1
Session: session_01MkQhmuuJAVDjmeWNixwDDH
Branch: claude/issue-16185-migration-flag-column-move-attest
Worktree: objectstack-issue-16185
Domain: domain:spec
File surface: packages/spec/src/system/migration.zod.ts (DataMigrationFlagSchema, :259-277), packages/platform-objects/src/system/sys-migration.object.ts, the regenerated packages/spec baselines the repo tooling moves for that change, and .changeset/*.md. ⛔ Not packages/drivers/**, ⛔ not docs/adr/**, ⛔ not content/docs/releases/** (stop on breach; explain in the report)
Container & model: S→M, mode:subagent, model: opus (--tier at 2e8e118, this round: "no path-derived mandate … the tier stays the PM's per-card judgment call (floor sonnet · default opus · ceiling fable)" with a "Clause ② SUSPECT surface" hint on migration.zod.ts. Built at TIER_DEFAULT per SKILL.md:514; the contract review is supplied before enqueue by an explicitly-model-passed CONTRACT_REVIEW_TIER subagent, because this seat serves claude-opus-5 — get_session 03:33Z, session_context.model and last_served_model both, ⛔ not the configured line)
Clause-②: yes
Thread-read: 5594060259
Serial constraints cleared: all 24 open PRs in this repo had their file lists read at 03:40Z — no open PR touches packages/spec/src/system/migration.zod.ts or packages/platform-objects/src/system/sys-migration.object.ts. Two generated-baseline overlaps exist and the probe is therefore not blind: PR #16883 (parked, ⛔ the predecessor seat's, maintainer-only merge) moves packages/spec/api-surface/system.json and export-origins/system.json; PR #16887 moves the data.json pair. ⚠️ Adding a member to a schema adds no export, so this card is expected to move authorable-surface/system.json and not the api-surface pair — no open PR touches any authorable-surface/*.json. ⇒ if check:api-surface wants to move api-surface/system.json here, that is a signal that something exported actually changed: report it, ⛔ do not hand-edit the baseline and ⛔ do not fight #16883 for the file. In-flight domain:spec cards #16894 (ui/**) and #16772 (system/i18n-resolver.ts, system/translation.zod.ts) claim no path on this surface. Queued sibling #15437 is fenced on system/translation.zod.ts, a different file.

---

Generated by Claude Code