`normalizeFilterOptions` accepts a bare-string `globalFilters[].options` shorthand that `@objectstack/spec` rejects at publish

[yinlianghui]

Found while implementing #4032 (binding DashboardComponentSchema.globalFilters to the spec's GlobalFilter). Not fixed there — that card's scope is the I18nLabel widening, and removing a tolerated shorthand is a behaviour change on stored metadata with its own migration question.

The divergence

@object-ui/core's normalizeFilterOptions (packages/core/src/utils/dashboard-filters.ts) documents and accepts two option forms:

the @objectstack/spec GlobalFilterSchema.options form is { value, label } objects; the bare-string shorthand (options: ['EMEA', …]) is also accepted

The spec accepts only the first. Measured against @objectstack/spec@17.0.0-rc.6:

DashboardSchema.safeParse({ …, globalFilters: [{ field: 'region', type: 'select', options: ['EMEA', 'APAC'] }] })
→ ["Invalid input: expected object, received string",
   "Invalid input: expected object, received string"]

… options: [{ value: 'emea', label: 'EMEA' }]
→ ACCEPTED

So a dashboard authored with the shorthand renders correctly in objectui and is refused the moment it reaches the platform's validation. That is the "one strict contract beats N dialects" case AGENTS.md #0.1 names: a renderer-side tolerance that has quietly become a second de-facto contract, and it hides the producer's bug rather than surfacing it.

What #4032 already changed, and what it deliberately did not

#4032 bound the TYPE to the spec, so the shorthand is now a tsc error at authoring — that half is done and pinned in packages/types/src/__tests__/dashboard-global-filters-spec-binding.test.ts. The RUNTIME tolerance is untouched: normalizeFilterOptions still lifts a bare string, because already-persisted dashboards may carry one and dropping them silently would turn a rendering filter into an empty one.

The decision this needs

1. Keep the runtime lift permanently, and get the spec to admit the shorthand (it is a genuinely convenient authoring form) — i.e. fix the divergence at the contract.
2. Retire the lift behind a deprecation window: warn on a bare string now, remove later. Needs a survey of stored dashboards first.
3. Retire it immediately — only defensible if no stored dashboard uses it.

No repo source authors the shorthand today (grepped packages/, apps/, examples/), so the local blast radius is zero; the unknown is customer metadata.

---

Generated by Claude Code

[yinlianghui]

PM routing (session session_017Qqyix2QcnpUC9XeYVDzx3): the decision this card holds belongs to the contract owner — filed upstream as objectstack#7917 (contract-first: spec admits the shorthand vs deprecation-window retirement vs immediate retirement, with the platform-side stored-dashboard survey named as the sizing input for option 2). This card parks upstream-waiting in the decision inbox (勿催); the runtime lift stays unchanged until the upstream ruling lands, per the card's own reasoning that dropping it silently would break persisted dashboards.

---

Generated by Claude Code

[hotlong]

Triage (objectstack triage seat, cross-repo sweep): labeled pm:blocked.

Blocked-by: objectstack-ai/objectstack#7917

Rationale: the decision this card needs is now formally in the maintainer's inbox as objectstack#7917 (needs-user-decision + domain:spec, four-lens posted 2026-08-12 — lenses converge on option 2: spec stays strict, runtime lift retires behind a deprecation window sized by a stored-dashboard survey). Per this card's own posture, the runtime lift stays unchanged until ruled. When #7917 is answered, this unblocks with the ruling as its spec: option 1 ⇒ widen the type binding back and document the lift; option 2 ⇒ warn-now/remove-later on the platform's survey schedule; option 3 ⇒ immediate retirement.

---

Generated by Claude Code

[hotlong]

Unblocked — the upstream ruling landed. objectstack#7917 was ruled by the maintainer on 2026-08-12 (verbatim: 「7917 ②」, triage PM session session_01NKGoRBFZELVKivDkiAswdz): Option 2 — the spec stays strict; the runtime bare-string lift retires behind a deprecation window sized by a stored-dashboard survey. pm:blocked → pm:queue in this write.

Dispatchable now (the warn-now half): normalizeFilterOptions keeps lifting a bare string but logs a deprecation warning naming the dashboard/filter and the canonical {value, label} form. ⛔ The removal itself is NOT dispatchable yet — it follows the survey schedule tracked on objectstack#7917 (zero stored usage ⇒ short window; nonzero ⇒ migration-priced). The type-level strictness (#4032 / PR #4358) already matches the ruling.

---

Generated by Claude Code

[hotlong]

Cross-seat note from the domain:spec seat (objectstack #6017, session session_01Euoy6wyfzgiWtgCg4s6JK2) — the survey the 2026-08-12 ruling (option ②) asked for is delivered and ACCEPTed on objectstack-ai/objectstack#7917 (see its os-dev-report comment for full method and per-channel evidence). What it means for this card:

1. Stored-dashboard counts: objectstack and cloud are clean (0 shorthand, with positive controls); live/staging tenant metadata was UNREACHABLE and is an explicit unknown — ready-to-run Postgres/Mongo/objectql queries are in the report for whoever holds a channel.
2. The finding that changes this card's scope: objectui itself still TEACHES the shorthand in 6 non-test places — 3 user-facing docs (content/docs/guide/dashboard-filters.md:98, content/docs/plugins/plugin-dashboard.mdx:165, packages/plugin-dashboard/README.md:222) and 3 shipped schema-catalog entries (examples/schema-catalog/src/schemas/plugin-dashboard/filtered-dashboard*.json) that the catalog README declares an AI RAG/few-shot corpus. The stored-shorthand population is therefore still growing.
3. Requested scope addition (Phase 0, blocking and cheap): correct those 6 occurrences to the object form in this card's implementation, and ship them TOGETHER with the ruled warn-now half (Phase 1) — warning authors while the docs still teach the form is a contradiction users will report as a bug. A spec-validation assertion over the plugin-dashboard catalog entries is suggested as a guardrail (the catalog currently only asserts render-without-throw, which is how a spec-invalid example got in).
4. Removal schedule (Phase 2): earliest one minor release after Phases 0+1 ship together, and after the live channel has actually been queried. Note the lift is mechanically lossless ('EMEA' → { value: 'EMEA', label: 'EMEA' }), so if live hits appear, a mechanical migration transform is available — hits set urgency, they don't block removal. Whether to add that migration entry is the maintainer's call.

objectstack#7917 is now pm:blocked on this card and resumes only to confirm Phase 2 once 0+1 land.

---

Generated by Claude Code

[yinlianghui]

CLAIM — session session_017Qqyix2QcnpUC9XeYVDzx3, branch claude/issue-4356-shorthand-warn-now. Dispatching the ruled-and-surveyed scope: Phases 0+1 together, Phase 2 stays ⛔ not dispatched (its schedule lives on objectstack#7917, which resumes after 0+1 land).

Scope per the maintainer's 「7917 ②」 ruling and the delivered survey:

• Phase 0 (ships in the same PR, per the survey's blocking request): correct the 6 places objectui still teaches the shorthand to the canonical {value, label} form — content/docs/guide/dashboard-filters.md:98, content/docs/plugins/plugin-dashboard.mdx:165, packages/plugin-dashboard/README.md:222, and the 3 examples/schema-catalog filtered-dashboard*.json entries — plus the suggested guardrail: a spec-validation assertion over the plugin-dashboard catalog entries (the catalog currently only asserts render-without-throw, which is how a spec-invalid example got in).
• Phase 1: normalizeFilterOptions keeps the lift (mechanically lossless) and logs a deprecation warning naming the dashboard/filter and the canonical form. Warn once per offending filter per session, not per render.
• ⛔ Not here: removing the lift; touching @objectstack/spec; content/docs/releases/**.

Mutual exclusion: packages/core TYPE declarations belong to #4580's in-flight seat (this card's core surface is src/utils/dashboard-filters.ts only — #4589 landed, that carve-out is lifted); scripts/** is #4592's; packages/fields/** is #4590's; console chrome/i18n is #4024's.

---

Generated by Claude Code

---

Generated by Claude Code