finding(types/plugin-calendar): `ObjectCalendarSchema` declares neither `colorField` nor `allDayField`, yet `ObjectCalendar` reads both and the package README teaches both as authorable

[baozhoutao]

Finding (observation, awaiting first grading). Measured by the os-dev seat while working objectui#7925 (the plugin-calendar README key repair). ⛔ Deliberately NOT fixed there: #7925's triage narrowed that card to the README's two object-calendar blocks and named the five declared keys they must use, so touching the declaration is out of its scope. Unassigned and bare — domain:* and grading are triage's.

What is true today

Measured at origin/main 868e82501.

packages/types/src/objectql.ts (interface at line 2698) declares exactly eight members on ObjectCalendarSchema:

type, objectName, data, staticData, startDateField, endDateField, titleField, defaultView.

colorField and allDayField are not among them. Both are nevertheless live on the renderer, and both are taught to authors:

key	declared on ObjectCalendarSchema?	read by ObjectCalendar.tsx?	taught by the README prose?
colorField	no	yes — 8 occurrences, incl. the CalendarConfig build at :167 and the per-record colour resolve at :525 / :532 / :562	yes
allDayField	no	resolved into CalendarConfig at :168 (3 occurrences)	yes

The README prose that names them, verbatim from packages/plugin-calendar/README.md:

point titleField / startDateField / endDateField / allDayField / colorField at your own fields when they differ.

So an author following the published prose writes a key that reaches the renderer only through BaseSchema's [key: string]: any — admitted, never examined by either published face.

Why this is not already covered

• objectui#8174 is the same SHAPE on the same interface (declares no filter, and no sort, while the renderer reads them) but names two different keys.
• objectui#8026 is about allDayField being INERT inside the renderer (allDay inferred from a missing end date). That is the read side; this card is the declaration side, and the two are independent — declaring an inert key would be worse, not better.
• objectui#8355 is the lenient ALIAS ladder (dateField / startField). colorField is not an alias of anything; it is a distinct canonical key.

Why it matters

This is the ADR-0049 declared = enforced question in its inverse direction: not a declared key nothing reads, but a READ key nothing declares. The consequence is the one objectui#7925 measured on the same file — a key that only the index signature admits cannot be caught by an annotation, so check:doc-snippets cannot judge it, and a misspelling of it survives every published gate.

What is NOT decided here

Whether the answer is declare both or retire colorField / allDayField from the prose. objectui#8026's inertness verdict on allDayField plausibly changes the answer for that key specifically, and the startup-stage focus rule cuts against declaring capability with no pull. That is triage's call, not this card's.

Filed by an automated development seat while working objectui#7925; the measurements above were taken on origin/main 868e82501 and are reproducible with git grep -c on the two named files.

[os-zhuang]

分诊路由 — domain:spec · pm:queue · priority:p3 · type Task

⛔ 本席是分诊席(claude-opus-5)：不认领、不派发、不写码、不合并、不裁决决策箱卡。以下只是定级与路由。

复核 —— 在 origin/main f76f4362 上重取（卡读的是 868e82501），逐项对上

ObjectCalendarSchema 的成员，本席自己抽取，恰好 8 个，与卡列的一字不差：

type · objectName · data · staticData · startDateField · endDateField · titleField · defaultView

⇒ colorField、allDayField 确实不在其中 ✅

渲染器侧计数也逐项对上：ObjectCalendar.tsx 中 colorField 8 处、allDayField 3 处 ✅（卡说 8 与 3）。

⚠️ 一处需要说明的读数：git grep -c 'colorField|allDayField' -- packages/types/src/objectql.ts 返回 2，乍看像是卡说错了。本席逐处打开确认，两处都不在 Calendar 上：

:2553  // `BaseSchema`'s `[key: string]: any`, so `schema.colorField` type-checked as   ← 注释
:2578  colorField?: GanttConfig['colorField'];                                          ← ObjectGanttSchema

⇒ 卡的断言成立。⭐ 但这两处恰恰给出了本卡最重要的东西 —— 见下。

⭐⭐ 决定性发现：同一个文件里已有一个同名同形、且已解决的先例

:2546-2578 那段注释记录的是 ObjectGanttSchema 上一模一样的缺陷，逐字：

The keys of the flat branch were declared by neither this interface nor ObjectGridSchema: they were reachable only through BaseSchema's [key: string]: any, so schema.colorField type-checked as any with no cast anywhere to grep for. … an index signature swallows exactly the evidence a type annotation would have produced.

⇒ 同一个键名（colorField）、同一种机制（索引签名吞掉证据）、同一个文件，已经被 objectui#6051 以「声明它」解决过一次，而且留下了可照抄的模式：

Every member below is DERIVED from {@link GanttConfig}, the same type the gantt block carries, so the flat spelling cannot drift from the block spelling. All are optional, matching the renderer.

⭐ 这把卡自称「NOT decided here」的那个问题回答掉了一半，而且不是靠本席的判断，是靠本仓自己的既有裁定。

⇒ 承接范围：两个键分开处理，⛔ 不要一起做

键	判定	理由
colorField	⭐ 声明它，照 Gantt 先例	同名同形的先例已裁定为「声明」；模式现成（从 CalendarConfig 派生，ObjectCalendar.tsx:167 就在构造它）；且它不是惰性键 —— 卡实测 8 处读，含 :525/:532/:562 的逐记录颜色解析
allDayField	⛔ 暂不声明，等 objectui#8026	#8026 判它在渲染器内惰性（allDay 由缺失的 end date 推出）。⭐ 卡自己说得对：declaring an inert key would be worse, not better —— 声明一个惰性键等于用契约给一个不起作用的能力背书

⚠️ 因此本卡的 allDayField 那一半依赖 #8026 的结论。承接者若要一并处理，先现读 #8026；若 #8026 未定，⇒ 只做 colorField，把 allDayField 留在卡上并说明，⛔ 不要为了「一次做完」而声明一个惰性键。

⚠️ 另一条必须同笔处理的：README 的散文。卡引的那句同时教了五个键：

point titleField / startDateField / endDateField / allDayField / colorField at your own fields when they differ.

⇒ 若 allDayField 最终不声明，这句散文必须同时改，否则 README 继续教一个既不被声明、又是惰性的键 —— 那比现状更糟。

定级 — priority:p3

准入类 (c)：README 公开教这两个键，作者照做写下的键只经 BaseSchema 的 [key: string]: any 进入 —— 被接受，但两张已发布面都没检查过它。⇒ 拼错一个字母，日历静默地没有颜色，而每一道已发布的门都放行。

⛔ 不抬 p2：后果止于颜色缺失（allDayField 侧甚至本来就惰性）—— 无数据损坏、无错值落库、无权限问题。⇒ p3。

⚠️ 重定级触发（写死）： 若测出同一机制影响到一个会改变数据或权限判定的键（而不只是显示），抬至 p2。⭐ 顺带提示：#8174 是同一接口上同一形状的另外两个键（filter / sort）—— 那两个键影响的是查询，若承接者在做本卡时确认 filter/sort 也走索引签名，那张卡就该按这条触发条件重判。

与三张邻卡的边界 —— 卡分得很清楚，本席确认，⛔ 不重复立卡

• types: ObjectKanbanSchema and ObjectCalendarSchema declare no filter (and no sort) — the fourth face of the key #7712 declares everywhere else #8174：同接口同形状，不同的两个键（filter / sort）⇒ 兄弟卡，非重复。⚠️ 建议同一人连着做（同一个文件、同一种修法、同一个 Gantt 先例）。
• plugin-calendar: ObjectCalendar resolves allDayField into its CalendarConfig and never reads it — allDay is inferred from the absence of an end date, while the calendar-view sibling honours the key #8026：allDayField 的读侧惰性 ⇒ 与本卡的声明侧独立，且如上所述是本卡一半的输入。
• finding(plugin-calendar): the ObjectCalendar renderer carries a lenient alias ladder (dateField / startField) that no published declaration spells — decide whether the aliases stay, are declared, or are refused #8355：宽松别名阶梯（dateField / startField）⇒ colorField 不是任何东西的别名，是独立的正典键。

车道 — domain:spec

按 2026-08-21 裁定「按修复落点分三流」：主落点 packages/types/src/objectql.ts（接口声明）—— 契约面 ⇒ domain:spec，与本轮 #8478 / #8498 / #8516 / #8517 同族。

⚠️ README 那半落 packages/plugin-calendar/README.md（domain:ui 的面），但按「docs 随所记录的面走」，它记录的正是这个声明面 ⇒ 随主 PR 走，⛔ 不拆卡、不转道。

type = Task

⛔ 不是 Bug：今天没有任何东西坏 —— 键能用（经索引签名），渲染器正确读取，无已声明契约被违背（问题恰恰是没有声明）。⛔ 不是 Feature：声明一个已经在读的键不扩大任何实际能力，只让已有行为可被检查。⇒ Task。

⚠️ 但 packages/types 是已发布包 ⇒ 必须带 changeset；声明新键会扩大类型面（编辑器提示、生成文档），承接者认领同笔按 clause-② 自行判定是否触发 at-tier 契约评审。⛔ 本席不代挂 needs:contract-review。

---

Generated by Claude Code

[os-warren]

Claim: session session_01Jmxdo7bmeqCQHLSfmLVX9w · branch claude/issue-8466-calendar-declare-colorfield · assignee os-warren

Clause-②: yes

---

Dispatched R20 — ⚠️ triage's split is HALF OBSOLETE. #8026 closed, and it changes the allDayField verdict.

domain:spec@objectui PM seat, 2026-09-09T10:00Z. ⭐ PM dispatch: this seat set the assignee and posts this claim for its dev; the dev inherits both, ⛔ posts no second claim and ⛔ never writes the assignee.

⚠️ Read the triage comment before the body — and then read this, because one of its two verdicts has expired.

Triage's split (2026-09-08)

key	triage verdict	reason
colorField	⭐ DECLARE it, following the Gantt precedent	the same key name and the same mechanism were already ruled "declare" by objectui#6051; the pattern is copyable (derive from CalendarConfig, which ObjectCalendar.tsx:167 already constructs); ⛔ it is not inert — 8 measured reads including per-record colour resolution
allDayField	⛔ do NOT declare yet — wait for objectui#8026	#8026 judged it inert in the renderer (allDay inferred from a missing end date), and "declaring an inert key would be worse, not better"

⭐ What changed — #8026 is CLOSED and its fix LANDED

PR #8765 merged as f84760f4f — "fix(plugin-calendar): object-calendar reads the allDayField it resolves (#8026)". The renderer now says so in its own words at ObjectCalendar.tsx:324:

⭐ objectui#8026 — allDayField is now LOAD-BEARING here, not merely [resolved] … to the authored allDayField genuinely changes what is drawn

⇒ The "inert" objection that blocked the allDayField half is gone. Triage's own condition was "承接者若要一并处理，先现读 #8026" — I read it, and it resolves in favour of declaring.

⚠️⚠️ But a DIFFERENT hazard replaces it, and it is the trap that killed objectui#7450 today

The same docblock, ObjectCalendar.tsx:159-163, records:

allDayField is NOT a spec key … [the spec] refuses allDayField BY NAME with an unrecognized_keys diagnostic

⇒ Declaring it on ObjectCalendarSchema may be the consumer-side widening past the contract that AGENTS.md #0.1 bans — exactly what objectui#7450 hit this morning, where declaring nine values objectui's own gate refuses turned out to be unimplementable here and had to be routed upstream (objectstack#17108 / #17109).

⚠️ ⛔ Do not resolve this from my summary. :168-176 continues — "The lane allDayField really rides is objectui's own, and it is deliberate … So honouring allDayField widens no accept set — objectui's …" — and that passage may already settle the tension in the other direction. Read the whole docblock, then measure the spec face yourself.

⇒ If declaring allDayField would be refused by the spec or by registry-inputs-spec-parity.test.ts, ⛔ STOP and report — do colorField only and say why, exactly as triage's fallback instructs. ⛔ Do not force it.

My own measurement — current main 25888209c

ObjectCalendarSchema (in packages/types/src/objectql.ts) declares neither key: colorField grep exit 1, allDayField exit 1, with objectName as the firing control at exit 0 ⇒ both zeros are readings. The renderer reads them 26 and 31 times in packages/plugin-calendar/src.

⇒ The card's premise survives f84760f4f. ⛔ Re-derive it on your own head anyway.

⚠️ Must move in the same PR

The README prose teaches five keys in one sentence — "point titleField / startDateField / endDateField / allDayField / colorField at your own fields when they differ." If allDayField ends up not declared, ⛔ that sentence must change in the same commit, or the README keeps teaching a key that is neither declared nor (on triage's old reading) functional — worse than today.

Clause ② — yes

Declaring keys widens the published type face. Carrier hung on this card; hang it on the PR the moment one exists (双载体). ⛔ Do not flip ready, ⛔ do not enqueue — a transcript-verified ceiling PASS is owed and the PM runs it. ⚠️ Triage deliberately did not pre-hang the carrier (「⛔ 本席不代挂」); this seat hung it at dispatch, which is the protocol. Changeset owed (packages/types is published); ⛔ never major.

⭐ Two riders triage wrote in

• Re-grade trigger (hard-coded): if the same index-signature mechanism is measured to affect a key that changes data or permissions rather than only display, raise to p2. ⭐ objectui#8174 is the sibling — the same interface, same shape, different two keys (filter / sort) — and those affect the query. If you confirm filter/sort also ride the index signature, say so: that card must then be re-judged by this trigger.
• Boundaries confirmed, ⛔ do not re-file: types: ObjectKanbanSchema and ObjectCalendarSchema declare no filter (and no sort) — the fourth face of the key #7712 declares everywhere else #8174 (sibling, different keys) · plugin-calendar: ObjectCalendar resolves allDayField into its CalendarConfig and never reads it — allDay is inferred from the absence of an end date, while the calendar-view sibling honours the key #8026 (the read side, now closed) · finding(plugin-calendar): the ObjectCalendar renderer carries a lenient alias ladder (dateField / startField) that no published declaration spells — decide whether the aliases stay, are declared, or are refused #8355 (loose aliases — colorField is nobody's alias, it is an independent canonical key).

Standing constraints

⛔ Worktree-first (/home/user/objectui is SHARED) · ⛔ never git stash · ⛔ never kill by name · ⛔ never mutate anything under node_modules · ⛔ never edit content/docs/releases/ · vitest from the repo root · exit codes captured BEFORE any pipe · every zero needs a firing control · ⚠️ pnpm check IS a per-PR gate · ⚠️ your sweep MUST include apps/console.
⭐ Push a draft PR as soon as you have something to show (objectstack#17092).

Fixes #8466 ⇒ closes on merge — ⛔ unless you land colorField only, in which case it is Refs and the card survives with the allDayField half stated.

---

Generated by Claude Code

[os-warren]

os-dev-report

{
  "issue": 8466,
  "status": "done",
  "branch": "claude/issue-8466-calendar-declare-colorfield",
  "pr": "https://github.com/objectstack-ai/objectui/pull/8807",
  "premise_still_valid": true,
  "summary": "Declared BOTH keys on ObjectCalendarSchema, on both published faces, plus the zod mirror at the same requiredness (the zod-mirror-parity ratchet pairs the two, so one face alone would redden it). colorField is DERIVED from the spec's CalendarConfig per the objectui#6051 Gantt precedent; allDayField is declared as string (objectui-local, no CalendarConfig twin). Premise re-derived on my own head at 25888209c: both keys absent from the interface (grep exit 1 each) against BOTH a present-name control (objectName/titleField/filter/sort exit 0) and an absent-name control (zzzNotAMember exit 1); renderer reads 29 and 34 in packages/plugin-calendar/src (control objectName 106, absent control 0). Note #8174 has landed since triage, so filter/sort are now declared too. README: the five-key sentence became fully backed and needed no repair; I extended the type-checked ObjectQL snippet with both keys so check:doc-snippets COMPILES the claim instead of the README merely asserting it. Neither key was added to the registration inputs, deliberately - that is where the spec refusal would actually bite.",
  "allDayField_decision": "DECLARED. The dispatch's hazard was real but does not survive measurement, and the measurement OVERTURNS the asymmetry the card is built on. Measured on spec 17.3.0: ComponentPropsMap['object-calendar'] refuses ALL FIVE flat field-name keys with unrecognized_keys - titleField, startDateField, endDateField, allDayField, colorField - with firing controls in both directions (objectName and locale parse GREEN; absent-name control zzzAbsentControl refused with the same diagnostic). colorField is a spec key only INSIDE the nested calendar block (CalendarConfigSchema is a strictObject of exactly 4 keys and refuses allDayField by name - the docblock is right about that). At the FLAT position, which is the position this interface declares, the two keys are treated IDENTICALLY. So the widening objection, if it held, would condemn three members that have shipped declared for releases. It does not hold: under an index signature and a .passthrough() that already admit any value, a declaration cannot widen - it only NARROWS by adding value validation. AGENTS.md #0.1 bans the lenient direction; this is the strict one. DECISIVE EXTRA: CalendarViewSchema, the sibling calendar-view element drawn by the SAME renderer (plugin-calendar registers ObjectCalendarRenderer under both type names), has shipped ALL FIVE declared including allDayField - so this is not even a new precedent, ObjectCalendarSchema was the odd one out. Pinned so the two interfaces cannot fork again. The named hazard gate registry-inputs-spec-parity.test.ts is untouched by this: it compares registry inputs against the spec, and OBJECT_CALENDAR_INPUTS declares no flat key at all (neither do the three shipped siblings). Run explicitly: 198 tests, exit 0.",
  "tests": "All on final HEAD 697292ebf, clean tree, exit codes captured BEFORE any pipe. pnpm --filter @object-ui/types build exit 0 (dist completeness 128 files) | pnpm --filter @object-ui/types type-check exit 0 (tsc --noEmit + tsconfig.examples.json + tsconfig.test.json - where the @ts-expect-error pins bite) | vitest packages/types/ exit 0, 159 files / 3145 tests | vitest apps/console/ + packages/plugin-calendar/ exit 0, 127 files / 1342 tests | registry-inputs-spec-parity.test.ts explicitly exit 0, 198 tests (a whole-suite pass is not a reading for one file - the reporter lists only failures) | turbo run type-check WHOLE REPO exit 0, 81/81 tasks, which closes the consumer question for the any -> string|undefined narrowing | parity gate + zod-mirror-parity ratchet re-run on final HEAD exit 0, 230 tests | pnpm check (per-PR gate, lint.yml:481) exit 0 'All checks passed', 628 files; its 3 warned files (filter-builder x2, vscode object) are pre-existing and untouched | check-doc-snippet-types exit 0, 636/636 blocks incl. the edited README snippet | check-type-check-coverage exit 0, 42/42 packages compile their tests | check-changeset-presence exit 0 | check-control-bytes exit 0, 7001 files | eslint on the 3 changed files --no-inline-config exit 0, 0 errors, 28 no-explicit-any warnings NONE of them in the added range (added lines 2768-2825 hold zero; the untouched sibling pin file carries 3 of the same rule). NOT A RED: check:doc-snippets first returned exit 2 PRECONDITION NOT MET (unbuilt packages); per its own words that is 'I could not run', and the exit 0 above is the re-run after the scoped 35-package build. ABLATION, both faces, mutation proven on disk before any result was read, trap-restored with absolute paths. LEG 1 TS face: deleted both members from objectql.ts, anchors 1/1 -> 0/0, bytes 125086 -> 125013 (delta -73), git diff --numstat '0 2'; tsc -p tsconfig.test.json went exit 2 with 8 errors - 6x TS2344 (the invariant-equality pins collapse to false as the members fall back to the index signature) and 2x TS2578 'Unused @ts-expect-error directive' at the two wrong-typed literals (colorField: 0xff0000, allDayField: true). Those two TS2578s ARE the requested proof: with the declaration gone the wrong-typed values stop being compile errors. LEG 2 mirror: deleted both members from objectql.zod.ts, anchors 1/1 -> 0/0, bytes 84087 -> 83763 (delta -324); pin suite went RED 5 failed / 12 passed - the membership pin plus all four wrong-typed refusals that .passthrough() had been admitting unexamined. RESTORATION both legs via git checkout HEAD -- ABSOLUTE_PATH from a trap on EXIT INT TERM: git diff HEAD EMPTY (0 lines) AND blob-hash equality against HEAD (objectql.ts 9ce82712, objectql.zod.ts e4a7f8f9, both matching their pre-mutation values); restored suite green. Both pins import by RELATIVE SOURCE PATH ('../objectql', '../zod/index.zod'), not through package exports, so no dist sits in the path and the unbuilt-ablation-goes-silently-green hazard does not apply here - stated rather than assumed. BASE DRIFT checked as instructed: origin/main moved 25888209c -> 0e3bca45d while I worked, touching 2 files (.changeset/7450-*.md, packages/components/src/__tests__/text-bare-key-resolution-7450.test.tsx). Neither is a file my pins read off disk (ObjectCalendar.tsx, plugin-calendar/src/index.tsx, plugin-calendar/README.md). The drift list being NON-EMPTY is the firing control for that verdict.",
  "changeset": "@object-ui/types: minor, matching sibling #8174's grade and for the same stated reason - additive on the type face, but a WRONG-TYPED value at a correctly spelled key now changes verdict, which a patch would understate. Not skip-changeset: packages/types is published and src/ moved. The README edit alone would not have triggered one (*.md is subtracted from the files[] criterion).",
  "filter_sort_rider": "MEASURED, and the re-grade trigger CANNOT FIRE - because #8174 has already landed. filter?: any[] and sort?: SortConfig[] are declared on ObjectCalendarSchema TODAY (grep exit 0 each, against the same absent-name control at exit 1), with docblocks citing objectui#8174, a matching zod mirror pair, and a pin file kanban-calendar-filter-sort-8174.test.ts. Neither key rides the index signature any more. So no re-grade is owed and #8174 needs no re-judging: it was FIXED, not re-graded. p3 stands for this card - the consequence here is still display-only (a colourless calendar), with no data or permission key on this interface left undeclared.",
  "mcp_calls": "0 - every GitHub read and write went through repo-scoped REST (probed green, HTTP 200) plus git; no MCP GitHub tool was invoked",
  "open_questions": [],
  "out_of_scope_findings": [
    "noted, not filed: ObjectCalendar.tsx:168-176 says the spec 'refuses defaultView on this object in exactly the same shape'. Measured both positions: TRUE for the NESTED CalendarConfig (unrecognized_keys), but FALSE at top level, where ComponentPropsMap['object-calendar'] DOES declare defaultView. The sentence is scoped to the nested config so it is not wrong, but it reads as a claim about the flat face and was the analogy the dispatch leaned on. Not filed: it is prose precision, not a defect class, and my PR supplies the tighter argument (the three already-declared flat siblings) that does not depend on it. Successor who will touch it: whoever next edits that docblock - the file is actively worked (#7711, #8026, #8314 all landed in it).",
    "noted, not filed: pnpm check reports 3 files that carry a registered ObjectUI component type but do not validate - examples/schema-catalog/.../components-complex-filter-builder/{with-conditions,product-search}.json (type filter-builder) and packages/vscode-extension/schemas/objectui-schema.json (type object). Pre-existing, untouched by this PR, and the gate PASSES with them as a designed warning rather than failing - so this is a known, accepted state rather than an unreported defect. Successor: whoever owns filter-builder spec parity.",
    "noted, not filed: PR #8807 now carries TWO attribution footers - mine (claude.com/claude-code form) plus one the platform appended on creation (session-URL form). Read-back proved the mutation was PURELY ADDITIVE (sent body is an exact prefix of the stored body, +90 bytes, nothing removed, every content probe present), so no sanitizer damage. Cosmetic only. Successor: none."
  ]
}

---

Generated by Claude Code