finding(core): `DateDisplayOptions.style` is read by `formatDateTime` alone — on `formatDate` it is inert AND collides with a positional parameter of the same name

[claude]

Carved out of the contract review of PR #7621 (card objectui#7443) by the domain:ui PM seat. The reviewer made filing this the explicit condition on its disposition of that PR's one open boundary flag, so it is not an optional follow-up.

The state PR #7621 ships

DateDisplayOptions is the one options bag that formatDate, formatRelativeDate and formatDateTime all take. PR #7621 added style?: string to it (packages/core/src/utils/date-display.ts:75) — and only formatDateTime reads it (:236).

Measured by the reviewer at head a43aa8101:

call	result
formatDate(v, undefined, { style: 'short', locale: 'en-US' })	Jul 4, 2024 — the default face, no diagnostic
formatRelativeDate(v, { style: 'compact' })	ignored

⭐ The sharpest form of it, which the implementing dev did not name

On formatDate the inert key collides with a positional parameter of the same name:

formatDate(value: string | Date | number, style?: string, options?: DateDisplayOptions)

So that one function now has two spellings for one concept, and one of them does nothing. A caller who writes the options spelling — the spelling formatDateTime requires — silently gets the default face.

Why this was accepted for the interim, and what that costs

The reviewer ruled the shipped shape (A) correct at the contract tier for the interim, on two measured grounds:

1. The precedent is real and the same shape. dueLike is read only at formatRelativeDate:119, t only at :122; formatDateTime(v, { dueLike: true, t: () => 'X', locale }) renders Jul 4, 2024, 07:00 AM — both keys silently inert. The module already has a one-bag convention with inert keys.
2. It is NOT an AGENTS.md #0.1 instance. #0.1 targets a tolerant fallback that makes off-contract input work, fossilising a second contract by success. An inert key never works, so no caller can come to depend on it and no dialect forms. It does share #0.1's no-diagnostic property — which is exactly why it must not be left un-owned.

Maintainer ruling B on #7443 (comment 5539935824, batch #34) names the long-run shape itself: "The long-run symmetric shape is both functions accepting options.style — additive on formatDate, and ⛔ not this card's." So option A puts the key where it will end up and makes this follow-up behaviour-only; option B (a formatDateTime-only options type) would have minted a published type name that this card then has to fold back.

What this card is

Make formatDate read options.style. Additive; the ruling already names it as the target shape.

⚠️ Open questions the implementer must answer rather than assume:

• What happens when both spellings are written — formatDate(v, 'short', { style: 'long' })? ⛔ Do not mint a precedence rule silently; objectui#7113 is the precedence precedent and finding(types): series chartType is undeclared and SILENTLY STRIPPED - the normalizer reads it first, measured not live, alias-refusal owed #7694 is the seat's recent case of an alias overwriting a canonical key.
• Should formatRelativeDate read it too, or is it genuinely style-less?
• Is the positional style parameter then owed a deprecation, or do both spellings stay?

Refs: objectui#7443 · PR #7621 · ruling B (5539935824) · objectui#7619 (two published formatDateTimes) · objectui#7620 · AGENTS.md #0.1.

---

Generated by Claude Code

[claude]

Claim: PM loop, round 6 — all-opus lane (Clause-② no)
Session: session_01KbJQ1y1J12nZxYzFWhP8Q3
Branch: claude/issue-7745-formatdate-options-style
Worktree: objectui-issue-7745
Domain: domain:ui
File surface: packages/core/src/utils/date-display.ts · packages/core/src/__tests__/（或该模块既有测试所在处）· 本卡自己的 .changeset/*.md. ⛔ Stop on breach: 任何新增或改写导出类型的改动（含给 DateDisplayOptions 加键、或新造一个 formatDateTime 专用的 options 类型）、任何 packages/types/ 的改动、任何其它包的改动。Explain in the report.
Container & model: S, mode:subagent, model: opus
Clause-②: no —— 让一个已声明的键做它声明要做的事。DateDisplayOptions.style 已经是公开面的一部分（PR #7621 加的），本卡不新增任何符号、不放宽任何校验器的接受集；改的是代码没有兑现声明这件事。⚠️ Void condition: 任何新增/改写导出类型或导出符号的改动 —— 那就是 yes，停下上报。
Serial constraints cleared: 无在飞 PR 触碰 packages/core/src/utils/date-display.ts。PR #7621 已合并（本卡从它的契约复审析出），PR #7792 也已合并（同一次复审的另一条，改的是 packages/fields/src/index.tsx 与一份 changeset 散文，与本文件不相交）。

---

缺陷

DateDisplayOptions 是 formatDate / formatRelativeDate / formatDateTime 共用的那一个 options 包。PR #7621 给它加了 style?: string（packages/core/src/utils/date-display.ts:75），而只有 formatDateTime 读它（:236）。

复审席在 head a43aa8101 实测：

调用	结果
formatDate(v, undefined, { style: 'short', locale: 'en-US' })	Jul 4, 2024 —— 默认面，无任何诊断
formatRelativeDate(v, { style: 'compact' })	被忽略

⭐ 最锐的那一层

在 formatDate 上，这个惰性键与一个同名的位置参数相撞：

formatDate(value: string | Date | number, style?: string, options?: DateDisplayOptions)

⇒ 同一个函数对同一个概念有两种拼法，而其中一种什么都不做。 写 options 拼法的调用者 —— 也就是 formatDateTime 要求的那种拼法 —— 会静默拿到默认面。

⭐ 长期形状已由维护者裁定，本卡就是去实现它

维护者在 #7443 的裁定 B（comment 5539935824，批 #34）原话：

The long-run symmetric shape is both functions accepting options.style —— additive on formatDate，⛔ 且不是那张卡的事。

⇒ 本卡就是那个 additive 的一步。⛔ 不要重新讨论方向，方向已经定了。

⚠️ 复审席也记下了为什么当时接受这个临时形状（并非疏忽）：模块已有一包多函数、部分键惰性的先例（dueLike 只在 formatRelativeDate:119 读、t 只在 :122 读），且它不是 AGENTS.md #0.1 的实例 —— #0.1 打击的是「宽容回退让不合契约的输入能用」，而惰性键从来不生效，没有调用者会依赖它、也形不成方言。⚠️ 但它共享 #0.1 的"无诊断"性质，所以不能不认领。

交付物

让 formatDate 读 options.style。

⚠️ 两种拼法相撞，必须明确定义优先级并写下来：位置参数 style 与 options.style 同时给出时，谁赢？⛔ 不许留成"看实现顺序"。⭐ 本席倾向 位置参数优先（它先存在、且现有调用者靠它），但这一条交给你判断并给出理由；无论选哪个，都要 pin 住它。

⚠️ 另请顺带判断并在报告里说明：formatRelativeDate 要不要一并读？维护者的裁定只点名了 formatDate。⛔ 若卡面/裁定没有覆盖它，不要顺手加 —— 报出你的判断，让它成为下一张卡。

验收

• 修复前后的对照读数：formatDate(v, undefined, { style: 'short', locale: 'en-US' }) 修复前是 Jul 4, 2024（默认面），修复后应给出 short 面 —— 贴出两个字符串。
• 优先级 pin：位置参数与 options.style 同时给出时的行为，写成用例。
• ⭐ 点亮控制：把新读取临时打回原状（或让优先级反过来），确认相应用例变红并指名；trap … EXIT INT TERM 下 git checkout HEAD -- <绝对路径> 还原，blob hash 相等 + 空 git diff HEAD 证明 —— ⛔ 靠状态不靠 trap；变异前先用 hash 确认落盘（空 hash 读作失败）。
• ⚠️ 回归面：dueLike / t 这两个既有惰性键的行为必须不变 —— 给出读数（例如 formatDateTime(v, { dueLike: true, t: () => 'X', locale }) 仍渲染 Jul 4, 2024, 07:00 AM）。
• pnpm --filter @object-ui/core test 与 type-check（走 turbo），报出文件数/用例数与 exit code。

变更集

改动落在发版包 src/ 下且改变运行期行为 ⇒ 很可能需要一个非空的变更集（这是行为变化，不是纯内部改动）。⛔ 不要凭规则推断：跑 node scripts/check-changeset-presence.mjs，判词原样抄进报告，按判词行事。⚠️ 若要写非空 frontmatter，按 AGENTS.md §版本号策略：objectui 自身的破坏性变更走 minor 并在正文写语义；⛔ 永不写 major（scripts/check-changeset-no-major.mjs 会拒）。

⚠️ 五个仪器陷阱

① 裸 tsc --noEmit 不是本仓的门（turbo type-check dependsOn ^build，到不了非包目录；构建前的 TS2882 是未满足的前提、不是结果）② 本容器没有「未认证的探测」，匿名样子的 POST 是真写入，探通道只用 GET ③ check-doc-links.test.ts 15s 超时是已知 flake ④ ⛔ new URL(rel, import.meta.url) 被 Vite 重写 ⑤ ⛔ 不用两点式 origin/main..HEAD 报文件数。

契约复审

Clause-② 申报 no，理由如上（不新增符号、不放宽接受集、只兑现已声明的键）。⚠️ 若实现过程中发现必须新增或改写导出类型，那就是 yes —— 停下上报，不要自行改档。

---

Generated by Claude Code

[os-sam]

os-dev-report

{
  "issue": 7745,
  "status": "done",
  "branch": "claude/issue-7745-formatdate-options-style",
  "pr": "https://github.com/objectstack-ai/objectui/pull/7813",
  "premise_still_valid": true,
  "summary": "formatDate now reads options.style. Precedence PINNED: the positional argument wins; options.style is consulted only when the positional slot is undefined (`style ?? options?.style` — `??` not `||`, so '' still counts as given and still renders the default face). Chosen because it is the only direction that is purely additive — it fires exactly on the input that is a silent no-op today, and a 16-reading before/after probe diffed to EXACTLY ONE changed line — and because the bag is shared across three functions, so a key aimed at a sibling (the module's own `dueLike`/`t` convention) must not outrank an argument written for this call: objectui#7694's shape and the silent-override half of objectui#4272. ONE THING THE CARD DID NOT NAME: formatRelativeDate delegates to formatDate outside its ±7-day window, so the new read leaked the key into formatRelativeDate for out-of-window dates AND recursed to stack exhaustion on { style: 'relative' }; both measured. The out-of-window call therefore strips the key via a module-local non-exported `absoluteFallbackOptions` — a behaviour-PRESERVING guard, not a feature. Clause-② stays `no`: no exported type or symbol added or rewritten; DateDisplayOptions keeps its same four keys with the same types, formatDate's arity is unchanged and pinned. JSDoc prose on DateDisplayOptions.style and the module header was rewritten because it stated the opposite of the new behaviour — documentation, not the declared type; flagged, not self-graded.",
  "tests": "BEFORE/AFTER (v='2024-07-04T07:00:00.000Z', TZ=UTC, locale en-US): formatDate(v, undefined, { style:'short', locale:'en-US' }) was \"Jul 4, 2024\" (default face, no diagnostic) and is now \"Jul 4, '24\". Same 16-reading probe run on both trees and diffed: exactly one line moved. PRECEDENCE PIN: formatDate(v,'short',{style:'long'}) = \"Jul 4, '24\"; formatDate(v,'long',{style:'short'}) = \"Jul 4, 2024\"; in-window formatDate(d,'short',{style:'relative'}) == formatDate(d,'short',{}); formatDate(v,'',{style:'short'}) = \"Jul 4, 2024\"; arity pin formatDate.length === 3. REGRESSION (dueLike/t, identical before and after): formatDateTime(v,{dueLike:true,t:()=>'X',locale}) = \"Jul 4, 2024, 07:00 AM\"; formatDate(v,undefined,{dueLike:true,t:()=>'X',locale}) = \"Jul 4, 2024\"; formatDateTime(v,{style:'compact',locale}) = \"7/4/2024 7:00 am\"; formatDateTime(v,{locale}) = \"Jul 4, 2024, 07:00 AM\"; formatRelativeDate(v,{style:'compact',locale}) = \"Jul 4, 2024\". LIT CONTROL — three legs, no dist involved (the pin imports '../date-display' as SOURCE, so nothing is rebuilt between mutation and measurement). Each leg: HEAD blob hash 6cbabb21ccb0eb105722aaaf87b5185b3bfebd2c confirmed equal to the on-disk hash BEFORE mutating; mutation proved landed by a NEW non-empty hash plus removed-text count 0 / injected-text count 1; then restore via `git checkout HEAD -- ABSOLUTE_PATH` under `trap ... EXIT INT TERM`, proved BY STATE — restored hash equals 6cbabb21... and `git diff HEAD` empty (an empty hash was coded to exit non-zero as FAILURE, not as 'nothing to compare'). LEG A (`style ?? options?.style` -> `style`): predicted the three 'options spelling is read' cases red; observed exactly those — 3 failed / 11 passed. LEG B (-> `options?.style ?? style`, inverted precedence): predicted the three precedence cases red; observed exactly those — 3 failed / 11 passed. A and B turn DISJOINT sets red, so neither half can be green by accident. LEG C (drop the strip): predicted two formatRelativeDate cases red; observed THREE — one more than predicted, reported as observed: `AssertionError: expected 'Jul 4, \\'24' to be 'Jul 4, 2024'` (the leak) and `RangeError: Maximum call stack size exceeded` (the recursion), plus the equivalence loop in 'the options spelling IS the positional spelling' which throws rather than mismatches. SUITES, all at head 0ef85f821 (= this branch's head, tree clean): `pnpm --filter @object-ui/core test` -> 118 files / 2509 tests passed, exit 0. `pnpm turbo run type-check --filter @object-ui/core --concurrency=2` -> 3 tasks successful, exit 0; `tsc -p tsconfig.test.json --listFiles` separately confirms the new test file IS in that program (1 occurrence), so that green covers it. `pnpm turbo run lint --filter @object-ui/core --concurrency=2` -> exit 0, 0 errors, 516 pre-existing warnings; `--format json` reports 215 files in eslint's own population with both changed files in it, eslint.config.js declares no parserOptions.project/projectService so linting is not type-aware and this diff cannot move a verdict on an untouched file; my two files 0 errors, date-display.ts's 4 no-explicit-any warnings unchanged (`as any` count 4 before, 4 after), new test file 0/0. New pin alone -> 14/14 passed, exit 0. Downstream re-export consumers `packages/fields/src/__tests__/{date-display.reexport-identity, date-formatter-residue-4272, datetime-compact-style-7443}` -> 3 files / 36 tests passed, exit 0 (read-only; no file outside packages/core was edited). All heavy runs went through the shared verify lock; verdicts read from its VERDICT line, exit codes captured by redirect-then-read, never after a pipe. CHANGESET GATE, `node scripts/check-changeset-presence.mjs`, verbatim BEFORE: 'Compared the working tree with a617bb8d3 (merge-base with origin/main): 1 file(s) changed, 1 of them published source of a package the release covers, 0 of them a manifest whose published contract moved, 0 under a package changesets ignores, 0 changeset(s) added.' / 'FAILED  1 source file(s) of 1 released package(s) changed, and this change adds no changeset: @object-ui/core packages/core/src/utils/date-display.ts'. Acted on it. Verbatim AFTER: 'Compared the working tree with a617bb8d3 (merge-base with origin/main): 1 file(s) changed, 1 of them published source of a package the release covers, 0 of them a manifest whose published contract moved, 0 under a package changesets ignores, 1 changeset(s) added.' / 'PASSED  1 source file(s) of 1 released package(s) changed, and this change declares 1 changeset(s): .changeset/7745-formatdate-options-style.md.' Scored `patch`, non-empty, with the behaviour semantics in the body; `node scripts/check-changeset-no-major.mjs` -> 'No changeset declares a major bump.', exit 0. FILE COUNT read from the recorded base a617bb8d3 (never a two-dot origin/main..HEAD diff) and corroborated by GitHub's own changed_files: 3.",
  "mcp_calls": "6 — issue_read(get), issue_read(get_comments), create_pull_request, pull_request_read(get), this add_issue_comment, and one read-back of it",
  "open_questions": [
    {
      "question": "Should formatRelativeDate read options.style too? The maintainer's ruling names formatDate only, so NOTHING was added for it here — reported for the next card, per the card's own instruction.",
      "options": [
        "A — no read at all: keep formatRelativeDate style-less, as today.",
        "B — read it only for the out-of-window ABSOLUTE fallback: formatRelativeDate(v, { style: 'short' }) on a two-year-old date renders \"Jul 4, '24\" instead of \"Jul 4, 2024\".",
        "C — read it for the relative phrase itself, which requires MINTING a relative-style vocabulary that does not exist today."
      ],
      "recommendation": "B, as a deliberate card of its own — not C, and not silently. It is not genuinely style-less: B is well-defined TODAY with zero new vocabulary, since the out-of-window path already renders the absolute face. C is out because there is no second relative phrase face to select, so the key would be accepted with nothing to name. B is nevertheless not a freebie: it makes the ±7-day boundary a VISIBLE face boundary (\"In 2 days\" inside, \"Jul 4, '24\" outside) and it changes live grid/gantt output for any caller already threading one shared bag — exactly the kind of call this card told me not to make unasked. Concretely, that card flips the single line this PR added (`absoluteFallbackOptions`), and ablation leg C is already the measurement of what flipping it costs, including the `{ style: 'relative' }` recursion it would have to handle: leg C blew the stack with RangeError. So the next card arrives with its before/after and its trap already taken."
    },
    {
      "question": "The card's third open question — is the positional `style` parameter now owed a deprecation, or do both spellings stay? — was NOT decided here, because deciding it means either changing an exported signature (the Clause-② void condition) or publishing a deprecation notice, and neither is this card's.",
      "options": [
        "A — both spellings stay permanently, with the pinned precedence as the contract (the state this PR ships).",
        "B — deprecate the positional parameter (JSDoc @deprecated only, no signature change), steering new callers to options.style while all existing calls keep working.",
        "C — remove the positional parameter in a future minor, which moves every existing formatDate(v, 'short', opts) caller's arguments and is a breaking change."
      ],
      "recommendation": "A for now; B is the cheap next step if the seat wants one spelling to win over time. C should not happen without a census: 6 call sites in this repo pass the style positionally (packages/core/src/utils/dataset-format.ts:192, packages/fields/src/index.tsx:844, packages/plugin-dashboard/src/recordFields.tsx:425, packages/plugin-grid/src/ObjectGrid.tsx:4607 and :4627, plus the two ObjectGantt.tsx sites that pass undefined), and a JavaScript caller that did not move its argument would silently hand its options bag to the style slot and lose its locale — the objectui#4272 defect the module header already records paying for once."
    }
  ],
  "out_of_scope_findings": [
    "NOT FILED, deliberately: the formatRelativeDate question above. The dispatch brief reserves it ('report your judgement so it can become the next card'), so filing it myself would duplicate what the PM plans to file. It is recorded here and in the PR body, with the recommendation and the measurement, so it cannot be lost. Say the word and I will file it.",
    "No other out-of-scope defect was found. One instrument note for other seats, not a defect: `pnpm --filter PKG exec vitest run PATH` is REFUSED by this repo's guard (objectui#3378) — running vitest from a package directory silently runs the wrong test set (it reported `Test Files 22 passed` from apps/console while running none of the target package's files). The guard failed loudly rather than going falsely green; correct form is from the repo root, `pnpm exec vitest run packages/core/src/...`."
  ]
}

---

Generated by Claude Code