[contract] GlobalFilterSchema.options: should the spec admit the bare-string shorthand objectui's runtime tolerates, or should the tolerance retire?

[yinlianghui]

Contract-first card from the objectui seat (session session_017Qqyix2QcnpUC9XeYVDzx3), routing objectui#4356's divergence to the contract owner. Question only — no code change proposed here, and objectui will not move its runtime until this is answered.

The divergence (measured, objectui#4356)

@object-ui/core's normalizeFilterOptions accepts two option forms for dashboard globalFilters[].options: the spec's { value, label } objects AND a bare-string shorthand (options: ['EMEA', 'APAC'], lifted to {value, label} at render). Measured against @objectstack/spec@17.0.0-rc.6:

• options: ['EMEA', 'APAC'] → rejected ("Invalid input: expected object, received string" ×2)
• options: [{ value: 'emea', label: 'EMEA' }] → accepted

So a dashboard authored with the shorthand renders correctly in objectui and is refused at publish-time validation — a renderer-side tolerance that has become a second de-facto contract, hiding the producer's bug (the AGENTS.md #0.1 shape).

Current state on the objectui side

• The TYPE half is already strict: objectui#4032 / PR console 记录详情页附件面板:沉在整页最底部不可发现(无位置配置)+ 文案未 i18n 中文界面裸奔英文 #4358 bound DashboardComponentSchema.globalFilters to the spec's GlobalFilter, so the shorthand is a tsc error at authoring, pinned by dashboard-global-filters-spec-binding.test.ts.
• The RUNTIME lift remains, deliberately: already-persisted dashboards may carry the shorthand, and dropping it silently would turn a rendering filter into an empty one.
• No repo source authors the shorthand (grepped packages/apps/examples); the unknown is customer metadata.

The decision requested (one of)

1. Spec admits the shorthand (z.union([z.string(), ObjectForm]) with a documented lift) — it is a genuinely convenient authoring form; objectui's lift becomes the documented semantics and the type binding widens back accordingly.
2. Spec stays strict; runtime lift retires behind a deprecation window — needs a stored-dashboard survey on the platform side to size the migration; objectui warns now, removes later on the spec owner's schedule.
3. Spec stays strict; immediate retirement — only defensible if platform data shows zero stored shorthand usage.

objectui holds the runtime lift unchanged until ruled; the divergence is recorded and pinned on our side either way.

Refs: objectui#4356 (the measurement), objectui#4032 / PR #4358 (the type binding), ADR lineage on one-strict-contract.

---

State (2026-08-13, spec seat)

Ruled 2026-08-12: option ② (spec stays strict; lift retires behind a survey-sized window). Survey delivered and ACCEPTed 2026-08-13 — see the os-dev-report comment (three repo channels clean-or-explained; objectui docs + AI schema catalog still teach the shorthand; live-tenant channel unreachable, queries provided). Adopted schedule: Phase 0 (stop the source) + Phase 1 (warn) ship together in objectui, Phase 2 (remove) one minor later at the earliest.

Blocked-by: objectstack-ai/objectui#4356

This card resumes only to confirm the Phase 2 removal schedule after objectui#4356 ships Phases 0+1. The Channel-4 live-tenant queries in the report are ready to paste for whoever holds a deployment channel.

[hotlong]

Triage: lands in packages/spec/src/ui/ (GlobalFilterSchema.options) if option 1, in objectui's runtime lift retirement if 2/3; rationale: every option either widens the spec accept set (1) or retires shipped tolerance behavior (2/3) — protocol/public-contract class either way → needs-user-decision, domain:spec (acceptance-face question; the contract owner answers even though option 2/3's code mostly lands downstream).

Four-lens block (①–④ per #7498):

• ① Platform long-term coherence — the current state is two de-facto contracts (strict spec + tolerant renderer), the AGENTS.md #0.1 shape this repo keeps paying for. Options 1 and 2 both collapse it to one contract; 1 by widening (union + documented lift), 2 by retiring the tolerance. 3 is 2 without a migration window.
• ② Measured business pull — no repo source authors the shorthand (measured: packages/apps/examples grepped clean); the only unknown is stored customer metadata, which is exactly what option 2's survey answers before anything breaks. No one has asked for the shorthand as a feature.
• ③ AI-agent error-resistance — a single strict object form with loud publish-time rejection beats a union with a lift rule an AI must also learn; the runtime-only tolerance is the worst of the three (silently trains authors on a form the door refuses). The type half is already strict (objectui#4032/PR#4358), so 2 aligns runtime with both the spec and the types.
• ④ Startup scope discipline — 1 is a permanent widening maintained forever for convenience; 2 is remove-over-declare-and-maintain with a bounded deprecation window; 3 is 2 minus safety.

Lenses converge on option 2 (spec stays strict; runtime lift retires behind a deprecation window, sized by a stored-dashboard survey on the platform side). Withheld from auto-adjudication because retiring shipped tolerance is a published-behavior removal (human floor). Dependency note: objectui holds its runtime lift unchanged until this is answered (objectui#4356).

The stored-dashboard survey (does any persisted dashboard carry the shorthand?) is dispatchable as a measurement task independent of the ruling if the maintainer wants the number first.

---

Generated by Claude Code

[hotlong]

Maintainer ruling — 2026-08-12

Ruled: Option 2 — the spec stays strict; objectui's runtime bare-string lift retires behind a deprecation window, sized by a stored-dashboard survey.

Provenance: maintainer, triage PM session chat (session_01NKGoRBFZELVKivDkiAswdz), 2026-08-12, verbatim: 「7918 A,7917 ②,7900 收敛两扇门,7929 来源标记」. Recorded by the triage seat; needs-user-decision → pm:queue swapped in the same write.

What this card now is: the survey + retirement-coordination card. No spec change lands (strictness stands as-is).

1. Survey (this card's dispatchable work): determine whether any stored dashboard carries the bare-string options shorthand — real deployments (staging control plane, any customer-metadata channel available) plus the already-measured zero in-repo usage. The survey's number sizes the window: zero everywhere ⇒ the window can be short; nonzero ⇒ the removal schedule prices in migration.
2. objectui half (unblocked now): objectui#4356 swaps to warn-now — normalizeFilterOptions logs a deprecation warning on a bare string immediately; removal follows this card's survey-determined schedule. Ruling posted there by this seat.
3. The type-level strictness (objectui#4032 / PR console 记录详情页附件面板:沉在整页最底部不可发现(无位置配置)+ 文案未 i18n 中文界面裸奔英文 #4358) already matches the ruling; nothing to widen back.

---

Generated by Claude Code

[hotlong]

Claim: PM loop round 1
Session: session_01Euoy6wyfzgiWtgCg4s6JK2
Branch: claude/issue-7917-shorthand-survey (only if any file artefact is warranted; the expected deliverable is a report comment, pr: null)
Worktree: objectstack-issue-7917
Domain: domain:spec
File surface: none expected — read-only survey per the maintainer's 2026-08-12 ruling (「7917 ②」): spec stays strict, no spec change lands; this card is the stored-dashboard survey + deprecation-window recommendation (stop on breach; explain in the report)
Container & model: S (investigation), mode:subagent, model: opus
Serial constraints cleared: none — no file writes, no overlap with any in-flight claim.

---

Generated by Claude Code

[hotlong]

Stored-dashboard survey — bare-string globalFilters[].options shorthand

Per the maintainer ruling of 2026-08-12 (option ②): the spec stays strict, no spec change lands from this card. This is the survey that sizes objectui#4356's deprecation window. No PR, no changeset, no files changed.

Headline: the in-repo counts are clean, but the survey found the shorthand's source. objectui's own user-facing docs and its AI few-shot example corpus actively teach the bare-string form today. The naive reading of a zero sweep ("nothing uses it, remove it fast") is not supported — see the window recommendation.

Method, and why plain grep is the wrong instrument

A bare grep "options: \['" over these repos returns mostly noise: field-level options (where the bare-string form is a legitimate authoring convenience — Field.select({ options: ['a','b'] })) and CLI flag options. Neither is the surface under survey.

So the sweep is structural: for every file mentioning globalFilters, bracket-match the globalFilters array, then classify each options array member inside it. Two passes were run — one keying on the first member, one flagging a bare string in any position (mixed arrays exist; one was found this way, and the first-member pass had bucketed it as object-form).

The filter-level aliases choices / values / picklist / selectOptions all normalize to options, so a bare-string array spelled choices is the same defect. All alias spellings were swept, not just options.

Per-channel results

Channel	Revision	Shorthand hits	Object-form (positive control)	Verdict
objectstack	2efd2c9bc	0	5	clean, re-measured
objectui	878140be9	11	4	see below
cloud	f5253f97	0	n/a (no globalFilters at all)	clean
staging / live customer metadata	—	not queried	—	UNREACHABLE

Channel 1 — objectstack (re-verified fresh, not inherited)

git ls-files | xargs grep -l "globalFilters" > /tmp/os-files.txt # 47 files
node scan.mjs < /tmp/os-files.txt # first-member pass
node scan2.mjs < /tmp/os-files.txt # any-position pass

• 47 files mention globalFilters; 18 contain a bracket-matchable globalFilters array.
• STRING-SHORTHAND hits: 0 (both passes).
• Positive control — object-form hits: 5. The tooling demonstrably sees real dashboards:
  • examples/app-showcase/src/ui/dashboards/ops-dashboard.dashboard.ts:71 — options: [{ value: 'backlog', label: 'Backlog' }, …]
  • examples/app-showcase/src/ui/dashboards/revenue-pulse.dashboard.ts:44 — options: [{ value: 'amer', label: 'AMER' }, …]
  • plus 3 in docs/notes/airtable-dashboard-analysis.mdx.
• Completeness control: the repo holds exactly 6 *.dashboard.* definitions; 3 declare globalFilters (ops-dashboard, revenue-pulse, platform-objects/.../system_overview); all three declare their filters inline. grep -E "globalFilters:\s*[A-Za-z_]" returns nothing, so no dashboard assembles filters from a variable where a textual sweep would miss them.
• Alias spellings (choices / picklist / selectOptions) in filter context: 0.

The previously measured zero holds.

Channel 2 — objectui (the finding)

36 files mention globalFilters; 27 contain a parseable array. 11 options arrays carry a bare string. They are not all equivalent, and the split is what matters:

(a) User-facing documentation — 3 hits. These teach the shorthand as the primary form.

• content/docs/guide/dashboard-filters.md:98
• content/docs/plugins/plugin-dashboard.mdx:165
• packages/plugin-dashboard/README.md:222

All three show the same block, and the README annotates it as the canonical example:

"globalFilters": [
 { "name": "region", "field": "region", "label": "Region",
 "type": "select", "options": ["EMEA", "APAC", "AMER"] }
]

(b) The shipped example corpus — 3 hits. examples/schema-catalog/src/schemas/plugin-dashboard/: filtered-dashboard.json:17, filtered-dashboard-dataset-widgets.json:17, filtered-dashboard-target-widgets.json:12.

That package's own README states its role: it is the single source of truth for every shipped schema example, consumed by the docs site via the SchemaExample MDX component, by smoke tests, and — decisively — by "AI agents (RAG / few-shot) — structured, machine-readable schema corpus." These entries are not spec-validated anywhere; the catalog tests assert only that they render without throwing.

That is the AGENTS.md error-resistance axis inverted: the corpus an AI author retrieves from teaches a form the platform's publish-time validation refuses. objectui has already paid for this exact shape once — examples/schema-catalog/test/fields-form-hosted.test.tsx records the objectui#3910 lesson verbatim: "these examples are the docs site's field demos and a few-shot retrieval source for AI authors, so what they show is what gets copied."

(c) Test fixtures deliberately pinning the lift — 5 hits. core/src/utils/__tests__/dashboard-filters.test.ts:46, plugin-dashboard/src/__tests__/DashboardRenderer.filters.test.tsx:84 and :141, app-shell/.../DashboardWidgetInspector.test.tsx:138, and one mixed-form array at plugin-dashboard/src/__tests__/DashboardFilterBar.i18nLabel.test.tsx:165 — options: [{ value: 'won', label: 'Won' }, 'lost']. These are expected to exist and retire with the lift; they are not authoring evidence.

Observed state of the lift itself: normalizeFilterOptions (packages/core/src/utils/dashboard-filters.ts:337) still lifts silently — its else branch is normalized.push({ value: String(o), label: String(o) }), with no deprecation warning. The warn-now half of objectui#4356 has not landed on objectui main yet. Not this card's work; recorded because the schedule below depends on when it does.

Channel 3 — cloud

git ls-files | xargs grep -l "globalFilters\|dashboard" > /tmp/cloud-files.txt # 121 files
node scan2.mjs < /tmp/cloud-files.txt

0 hits — and zero globalFilters arrays of any form. No seed, template, fixture or tenant metadata in cloud authors a dashboard global filter at all. The only textual match is a prose reference in .spec-changes-ack.json.

Positive control for this channel: cloud does carry dashboard-typed metadata (9 files, incl. packages/service-ai-studio/src/tools/blueprint-tools.ts, verify/graph-lint.ts), so the sweep reaches real dashboard metadata — those dashboards simply have no global filters.

Worth recording, because it is a metadata producer, not just a store: cloud's AI studio generates dashboards (packages/service-ai-studio/src/tools/dashboard-snap.ts). It only ever emits and adjusts widgets; it never synthesizes globalFilters. So the AI-studio channel does not manufacture shorthand today. Its sibling generators do author select-field options, and they use the object form (options: [{ label: 'New', value: 'new' }]) throughout.

Channel 4 — staging control plane / live customer metadata: NOT QUERIED

⛔ This is an unknown, not a zero. This container has no channel to any deployment: no ObjectStack credentials or endpoint in the environment, no ~/.objectstack config, no mongosh, and psql present but with no configured connection string. Nothing was queried; nothing may be inferred about live tenants from the three clean repo channels.

Whoever holds the channel can paste the following. The storage shape is real, taken from packages/metadata-core/src/objects/sys-metadata.object.ts: dashboards are rows in sys_metadata with type = the metadata type, state in draft|active|archived|deprecated (so this covers drafts as well as published), and the payload in metadata, a JSON-serialized text column.

Trap this query must not fall into: the loader has a singular/plural fallback (ql.find('sys_metadata', { where: { type: 'hook' } }) then retries 'hooks' — packages/objectql/src/plugin.ts:1688), so legacy rows may be typed dashboards. Both spellings are matched below.

Postgres — precise, any-position, matching the scanner's semantics exactly:

SELECT m.organization_id, m.namespace, m.name, m.state,
 f->>'name' AS filter_name, f->>'field' AS filter_field, f->'options' AS options
FROM sys_metadata m
CROSS JOIN LATERAL jsonb_array_elements((m.metadata::jsonb)->'globalFilters') AS f
CROSS JOIN LATERAL jsonb_array_elements(f->'options') AS opt
WHERE m.type IN ('dashboard', 'dashboards')
 AND m.metadata IS NOT NULL
 AND jsonb_typeof((m.metadata::jsonb)->'globalFilters') = 'array'
 AND jsonb_typeof(f->'options') = 'array'
 AND jsonb_typeof(opt) = 'string';

Run the positive control in the same session before trusting a zero — swap the last line to = 'object'. If that also returns nothing, the query is not reaching dashboards and the zero is meaningless. (If metadata::jsonb errors on a malformed row, guard the cast rather than dropping the filter, so bad rows are counted as unknown instead of clean.)

Repeat both against sys_metadata_history (same metadata column) for prior versions — informational only: a history hit without a current-version hit means the dashboard was already migrated and needs no action.

MongoDB — same semantics, since the payload is a string either way:

db.sys_metadata.find({ type: { $in: ['dashboard', 'dashboards'] } }).forEach((d) => {
 let m; try { m = JSON.parse(d.metadata); } catch (e) { print('UNPARSEABLE\t' + d.name); return; }
 for (const f of (m.globalFilters || [])) {
 if (Array.isArray(f.options) && f.options.some((o) => typeof o === 'string')) {
 print([d.organization_id, d.namespace, d.name, d.state, f.name || f.field,
 JSON.stringify(f.options)].join('\t'));
 }
 }
});

objectql, if a runtime is easier to reach than the database:

const rows = await ql.find('sys_metadata', { where: { type: 'dashboard' } }) ?? [];
let shorthand = 0, objectForm = 0;
for (const row of rows) {
 let m; try { m = JSON.parse(row.metadata); } catch { continue; }
 for (const f of (m.globalFilters ?? [])) {
 if (!Array.isArray(f.options)) continue;
 if (f.options.some((o) => typeof o === 'string')) { shorthand++; console.log(row.organization_id, row.name, f.name ?? f.field, f.options); }
 else objectForm++;
 }
}
console.log({ shorthand, objectForm }); // objectForm === 0 means the sweep saw nothing — not a clean result

Recommended deprecation window and removal schedule

Do not read the three clean repo channels as licence for a short window. They measure who ships the shorthand, not who stores it, and the survey found the documented authoring path still producing it. A customer following objectui's current dashboard-filters guide today authors a bare-string filter, and it renders — so the population of shorthand dashboards is still growing. Starting a removal clock now would price a migration against a number that keeps moving.

Proposed schedule, in dependency order:

Phase 0 — stop the source (blocking, and cheap). Correct the 6 non-test occurrences to the object form: 3 docs surfaces (content/docs/guide/dashboard-filters.md, content/docs/plugins/plugin-dashboard.mdx, packages/plugin-dashboard/README.md) and 3 schema-catalog entries. This is the highest-value item the survey produced and it is independent of the removal date — every day it slips, more stored shorthand is created, in customer tenants and in AI-authored dashboards drawing on the catalog corpus. It sits inside objectui#4356's completion scope, so I have not filed it separately; it needs stating as a scope item there. Consider also adding a spec-validation assertion over the plugin-dashboard catalog entries, so a catalog example the platform would refuse cannot land again.

Phase 1 — warn (objectui#4356's ruled half, unchanged). normalizeFilterOptions warns on a bare string. Suggestion from what the survey saw: have the warning name the filter (name or field) and print the object-form replacement, since the mixed-form fixture proves partial migrations occur and a warning without the offending filter's identity is hard to act on. Phases 0 and 1 should ship together — warning authors while the docs still teach the form is a contradiction users will report as a bug.

Phase 2 — remove. Earliest one minor release after Phase 0+1 have shipped together, and not before Channel 4 has actually been queried by someone with access. Then:

• Live sweep returns zero → remove at that one-minor mark. Short window justified, with the residual unknown stated below.
• Live sweep returns hits → do not price this as a hand-migration. The bare-string lift is mechanically lossless ('EMEA' becomes { value: 'EMEA', label: 'EMEA' } — precisely what the runtime already does), which distinguishes it from the judgment-class retirements in packages/spec/src/migrations/entries/semantic/. Compare 17.filter-regex-options-retired.ts, which explicitly refuses a D2 conversion because rewriting $regex to $icontains is not lossless. This one is, so it qualifies as a mechanical transform rather than a semantic TODO, and stored dashboards can be lifted on the migration path instead of by hand. That makes removal safe largely regardless of the count, and turns the unreachable Channel 4 from a blocker into a number that only sets urgency.

To be explicit about the ruling's boundary: recommending a mechanical migration entry is not a spec widening and does not reopen option ①. The accept set stays strict; the transform rewrites sources on the upgrade path. Whether to actually add that entry is the maintainer's call, not this card's.

Residual unknowns, stated plainly

1. Live and staging tenant metadata was never queried. Unreachable from this container. This is the survey's one genuine gap, and no repo evidence substitutes for it.
2. The sweep is textual/structural over three repos at the revisions named. A dashboard authored outside these repos — by a customer, by hand, or by an AI drawing on the catalog corpus — is invisible to it by construction. That is exactly the population Channel 4 exists to count.
3. Private or unpublished customer packages shipping dashboard metadata are out of reach on the same grounds.

---

Generated by Claude Code

---

Generated by Claude Code