spec rc.6 refines a date `GlobalFilter.defaultValue` to reject `{ preset }` — the exact shape objectui's normalizer produces and stored dashboards carry

[yinlianghui]

A producer/consumer contract conflict surfaced by the @objectstack/spec 17.0.0-rc.6 bump in objectstack#7100. Filed as a decision, not implemented — the deciding half belongs to the spec owner, and encoding either answer consumer-side would preempt it.

What changed

rc.6 added a cross-field refinement to GlobalFilterSchema.

Measuring it correctly matters, and the obvious probe is misleading — parsing a { preset } default against the bare spec schema DOES fail, but on the OLD field type (defaultValue is string | number | boolean, invalid_union, message Invalid input), and the refinement never runs. Isolate it by widening the field first — which is exactly the shape objectui's dialect has:

const widened = SpecGlobalFilterSchema.safeExtend({ defaultValue: z.any().optional() });
widened.safeParse({ field: 'created_at', type: 'date', defaultValue: { preset: 'last_7_days' } })

That is refused, and the message names the rule:

{"preset":"last_7_days"} is not a value a type: 'date' filter can resolve. Use one of three spellings: a preset name (today, yesterday, this_week, last_week, this_month, last_month, this_quarter, last_quarter, this_year, last_year, last_7_days, last_30_days, last_90_days); an ISO date such as 2026-01-15 or 2026-01-15T08:30:00Z, meaning that day exactly; or a date-macro token such as {today} or {30_days_ago} (the full vocabulary is DATE_MACRO_TOKENS in @objectstack/spec/data). custom is not among them — it is a dateRange.defaultRange sentinel that carries no bounds of its own.

The bare preset NAME (defaultValue: 'last_7_days') is accepted by both sides.

Why it bites objectui specifically

@object-ui/types' GlobalFilterSchema derives from the spec's and pins three deliberate divergences (packages/types/src/zod/complex.zod.ts) — the widened keys are options, optionsFrom and defaultValue. The third is this one:

defaultValue stays z.any() — normalizeDateDefault (framework#4475) lifts a date preset NAME into { preset }, and stored dashboards carry that object form, which the spec's string | number | boolean rejects.

So objectui does not merely tolerate { preset }: @object-ui/core's dashboard-filters.ts produces it, and it is what is on disk.

The evidence chain, end to end:

1. framework#4475 introduced normalizeDateDefault, which lifts a preset name into { preset }.
2. @object-ui/core/src/utils/dashboard-filters.ts runs it, so the object form is what objectui writes.
3. packages/types/src/zod/complex.zod.ts widened defaultValue to z.any() for exactly that reason, and said so in prose.
4. packages/types/src/__tests__/report-chart-query-spec-parity.test.ts → accepts the normalized date-preset default object has pinned it since.

Widening the FIELD used to be enough, because nothing else in the spec had an opinion. A refinement is not a field type, so it no longer is: any derivation that carries the refinement refuses the object form however defaultValue is typed.

The mechanical consequence, and what objectstack#7100's PR does

rc.6 closed both extension doors on this schema:

• .extend() — what the code used to be — now throws at module load: "Cannot overwrite keys on object schemas containing refinements. Use .safeExtend() instead." It took six @object-ui/types suites down before any of them ran a test.
• .safeExtend() — zod's own suggested replacement — runs, but is "safe" precisely in that it will not let you REPLACE an existing key's type. It types every incompatible override as never, so all three divergences stop compiling (TS2322 … is not assignable to type 'never').

Some spelling therefore had to change. PR #4169 composes by spreading SpecGlobalFilterSchema.shape — the spec's fields still flow in BY REFERENCE, the three keys are replaced, and the refinement is not carried. That is byte-for-byte the behaviour this schema had at rc.5, so the bump changes nothing here and neither answer below is encoded. A tripwire pins the standstill and goes red from either side (objectui stops accepting the object form, or the refinement is withdrawn/reworded upstream).

The options

A. Upstream relaxes in rc.7 — the refinement was not meant to exclude the stored { preset } form.

• Cost to us: nothing. PR retire(studio): drop the global_nav designer surfaces with the rc.6 spec bump (objectstack#7100) #4169 waits for the release and then lands as-is; the tripwire goes red on the reworded message and is deleted with its note.
• The question for the spec owner: was { preset } considered when the three spellings were enumerated?

B. Upstream confirms intent — { preset } is deliberately not a resolvable date default.

• Then objectui migrates: change normalizeDateDefault to keep the bare preset name, drop the defaultValue divergence (the other two are unaffected), adopt the refinement, and handle stored dashboards that already hold the object form.
• Scope estimate: one function in @object-ui/core/src/utils/dashboard-filters.ts, the divergence and its prose in packages/types/src/zod/complex.zod.ts, the two pins in report-chart-query-spec-parity.test.ts, plus a read-path migration for stored dashboards (the part with real risk — until it runs, an existing dashboard fails validation). Small code, non-trivial data.
• Expressively this costs nothing: the preset NAME is already one of the three legal spellings, so it is a rewrite, not a capability loss.

C. Keep the divergence permanently. Rejected on principle, and named only so it is visibly rejected: objectui would accept a dashboard the platform refuses — the designer stays green and the save fails server-side. That is the tolerant-consumer failure AGENTS.md #0.1 exists to prevent, one level up.

Recommendation: ask upstream first (A vs B), never C. A and B differ only in who moves, and the answer is a fact about the spec owner's intent that we do not hold. Consumer-side we take neither until then; the standstill costs nothing while it lasts, because the spread preserves rc.5 behaviour exactly.

Blocking

PR #4169 stays draft until this is ruled. It carries the global_nav retirement (objectstack#7100) plus the rc.6 bump, which cannot compile apart.

[os-zhuang]

Triage: needs-user-decision — the card is filed as a decision and both directions are genuinely open: (a) keep spec rc.6's refinement and migrate objectui's producer (normalizeDateDefault in @object-ui/core's dashboard-filters.ts) plus stored dashboards off the { preset } object form, or (b) have the spec admit { preset } as a fourth legal spelling. Direction (a) touches stored-data shape (migration of what's on disk), direction (b) re-opens a just-shipped acceptance surface — either way this is a maintainer ruling, not a dispatch.

• Cross-repo note: if the ruling is (b), the execution lands in objectstack packages/spec (domain:spec lane) and this card becomes the downstream adaptation half; if (a), it stays here (normalizer + migration + divergence-pin removal in packages/types/src/zod/complex.zod.ts). Routing follows the ruling; no route label needed on a sibling-repo card (whole-repo seat owns it).
• Blocks: Track the @objectstack family at 17.0.0-rc.6 — the adaptation surface beyond what objectstack#7100 could carry #4167 (the whole rc.6 bump) carries Blocked-by: #4165 — this ruling is the bump's critical path, worth prioritizing in the decision box.
• Related, not duplicate: objectui: PRESET_RANGES 改为消费 spec 的 DATE_RANGE_PRESETS 词汇表(#4614 A 案的消费半边) #4017 (PRESET_RANGES consuming the spec's DATE_RANGE_PRESETS vocabulary, the #4614-A consumption half) is the same vocabulary family but a different card — it standardizes names; this card is about the container shape ({ preset } object vs bare string). Dup check over cached open lists found nothing else.
• Premise: measured today against the resolved rc.6 dist (rejection message quoted verbatim in the body); packages/types/src/zod/complex.zod.ts divergence pin documents { preset } as the on-disk form.

本评论来自分诊座位 Routine（#5474 试点），不构成认领。

---

Generated by Claude Code

[claude]

Maintainer ruling — 2026-08-11. From the four-lens decision review (platform long-term coherence / measured business pull / AI-agent error-resistance / startup scope discipline); the maintainer accepted the recommendation set in full.

Ruling: spec stays strict — no widening. rc.6's refinement stands; the bare preset NAME is the single canonical spelling. objectui's side of the contract: change normalizeDateDefault to emit the bare name, and treat stored { preset } as a documented legacy alias per the ADR-0089 alias-retirement pattern — lift on read, rewrite on next save, retirement window recorded at the read site. No spec change, no hard data migration; stored dashboards stay safe through the alias window.

Four-lens note: the earlier "spec accepts both spellings" direction was rejected — two accepted spellings for one meaning is permanent contract accretion, and gives AI authors and consumers two forms to drift between forever. State: needs-user-decision → pm:queue.

Recorded by the triage seat Routine (#5474 pilot) on the maintainer's direct instruction — ruling record, not a claim.

---

Generated by Claude Code

[yinlianghui]

Ruling acknowledged — execution plan (objectui whole-repo seat PM, session session_017Qqyix2QcnpUC9XeYVDzx3).

The ruling (spec stays strict; bare preset name canonical; stored { preset } becomes an ADR-0089 legacy alias — lift on read, rewrite on save, retirement window at the read site) unblocks the rc.6 train immediately, because PR #4169's standstill was designed for exactly this moment: it encodes NEITHER answer (spread of the spec shape, refinement not carried, byte-for-byte rc.5 behavior), so it is compatible with the ruling as-is. Sequencing:

1. Train releases now, in order: retire(studio): drop the global_nav designer surfaces with the rc.6 spec bump (objectstack#7100) #4169 → ready + auto-merge; on landing, fix(deps): triage the 14 rc.6 spec-symbol collisions and refresh the console parity exemptions (#4167) #4189 retargets to main (regaining real CI, the fix(gantt): an illegal dependency link says why it was refused #4210 pattern) → auto-merge; then fix(i18n): render I18nLabel objects at the 13 remaining sites #4208 the same. No rebase-onto-migration needed — the train never adopts the refinement, so stored dashboards stay valid throughout.
2. This card is now the migration card (label already pm:queue): implement the ruling — normalizeDateDefault emits the bare name; read-side ADR-0089 alias lift for stored { preset } (normalizing BEFORE schema validation so the refinement can be adopted); rewrite-on-next-save; retirement window documented at the read site; drop the defaultValue divergence in complex.zod.ts (the other two divergences stay); delete retire(studio): drop the global_nav designer surfaces with the rc.6 spec bump (objectstack#7100) #4169's tripwire with its note (it will go red exactly as designed — that red is the confirmation, not a failure). Serialized behind the train (same file complex.zod.ts as retire(studio): drop the global_nav designer surfaces with the rc.6 spec bump (objectstack#7100) #4169) — the seat dispatches it once the train is on main.
3. #6955 (the last v17 card) stays serial behind the train, unchanged.

---

Generated by Claude Code

[yinlianghui]

CLAIM — migration dispatch (objectui whole-repo seat PM, session session_017Qqyix2QcnpUC9XeYVDzx3). The train is fully on main (bb68488ff), complex.zod.ts is unlocked, and the maintainer's ruling above now executes.

• Branch claude/issue-4165-preset-alias-migration, worktree objectui-issue-4165 (M container)
• Scope = the ruling + the execution plan recorded above: normalizeDateDefault emits the bare preset name; read-side ADR-0089 alias lift for stored { preset } (normalizing BEFORE schema validation so the refinement can be adopted); rewrite-on-next-save; retirement window documented at the read site; the defaultValue divergence drops from complex.zod.ts (the other two divergences stay); retire(studio): drop the global_nav designer surfaces with the rc.6 spec bump (objectstack#7100) #4169's tripwire goes red exactly as designed and is deleted with its note — that red is the confirmation.

---

Generated by Claude Code