Vocabulary consolidation (#2901): what shipped, and why Track C items 1–3 are not planned

[os-zhuang]

✅ Resolved — every track dispositioned

Track	Outcome
A — delete three orphan vocabularies	✅ objectstack-ai/objectstack#4061
B — renderer-side convergence	✅ #2974, #2940, plus the third table in #2989 and #3022
Additions-only	✅ objectstack-ai/objectstack#4070
C item 4 — AggregationFunction lockstep	✅ objectstack-ai/objectstack#4153
C items 1–3 — narrow VALID_AST_OPERATORS, retire the aliases, rename the $-tokens	⛔ Not planned — see the Track C table
Prerequisites 1, 2, 4	✅ (1 had already landed; 2 = objectstack-ai/objectstack#4107; 4 is structural + asserted)

Why items 1–3 are not planned. Each was a precondition for fixing a silent
failure, and every one of those failures has since been fixed by a cheaper
means: the drivers throw instead of dropping (objectstack-ai/objectstack#3948),
all three of objectui's translation tables are pinned to the spec with parity
guards (#2974, #2989, #3022), saveMeta stops minting alias rows
(objectstack-ai/objectstack#4107), and the orphans are gone
(objectstack-ai/objectstack#4061). What remains is reducing the count of
accepted spellings — paid for by rewriting live customer rows, against
sys_saved_report.query_json that cannot be enumerated statically. The
risk/benefit has inverted since this was filed.

Follow-ups carrying the loose ends: objectstack-ai/objectstack#4121 (protocol
rejects a malformed filter array), objectstack-ai/objectstack#4157
(number/string/boolean metric SQL), #2997 → closed.

Rewritten after a risk assessment. The original version of this issue said the work was cheap "while spec 16 is still RC". That framing was wrong on the facts and pointed at the most dangerous change first. What follows replaces it. The three tracks below have genuinely different risk, and only one of them is safe to start today.

Corrections to the original issue

1. The version premise was wrong. objectui is not pinned to spec 16 awaiting a major bump. All 40 packages are at 17.0.0 and every importer resolves to @objectstack/spec@17.0.0-rc.0 (chore(deps): upgrade @objectstack/* to 17.0.0-rc.0 #2950). There is no version window to race.
2. The 16→17 gap is not an enum gap. Re-extracted both trees: of the 30 named ui/ enum exports, zero changed values. DensityModeSchema and WcagContrastLevelSchema were removed (enforce-or-remove applied — good), and ChartAggregateFunctionSchema was added. Nothing else moved.
3. Narrowing a vocabulary is not "cheap while RC". It is loud for new authoring and completely silent for everything already stored. defineStack throws on an out-of-enum value; saveMeta returns 422 — but the metadata read path neither drops nor errors, and objectui's render path does not zod-validate view metadata at all. A narrowing lands green in CI, green in os build, and degrades quietly against customer rows.

Track A — safe, ready now: delete three orphan vocabularies

Zero consumers, verified by grep across framework packages/ + apps/:

Vocabulary	Location	Evidence
AggregationFunctionEnum	shared/enums.zod.ts:11	Only references are its own definition and its own test. Its doc comment claims it is "used across query, data-engine, analytics, field" — that is false.
FilterOperator	api/websocket.zod.ts:60	Reaches EventFilterSchema, which no server file imports. The realtime path never evaluates an event filter.
ODataFilterOperatorSchema	api/odata.zod.ts:217	Zero importers. OData $filter is handled by a string→JSON parse, not by this enum.

Deleting these removes three of the "nine disagreeing filter vocabularies" without touching a single runtime path. Framework-side PR, no migration, no cross-repo sequencing.

Track B — done: renderer-side convergence

Closed by #2974 and #2940. Recorded here because the original issue scoped it as spec work, and it wasn't.

The interesting part is why it was reachable. before/after are canonical VIEW_FILTER_OPERATORS members (ui/view.zod.ts:90) that VALID_AST_OPERATORS does not accept — and 8 of the 19 canonical view operators are in that position, including equals. Six were masked only because objectui's adapter happened to translate them; the two it missed returned unfiltered result sets, silently. Details and the server-side fix: objectstack-ai/objectstack#3948.

Both objectui translation tables are now pinned to the spec vocabularies in both directions, so a new spec operator fails a test rather than returning every row.

Track C — dispositioned: item 4 done, items 1–3 not planned

No longer blocked, and mostly no longer wanted. The prerequisites landed
(see below); item 4 shipped; items 1–3 are closed as not planned, because
every harm they existed to prevent has since been fixed by a cheaper means.

Original assessment kept below for the record, with each row's disposition.

Target	Original risk	Disposition
VALID_AST_OPERATORS	Do not narrow — removing a spelling converts a working bare-triple filter into a full-table scan with no error anywhere.	⛔ Not planned. The silent drop is fixed: both drivers throw (objectstack#3948 item 1), and VALID_AST_OPERATORS is now derived from AST_OPERATOR_MAP's keys, so "in one list but not the other" is structurally impossible. Narrowing would only reduce the count of accepted spellings — no remaining harm to fix, and a stored-metadata migration to pay for it.
VIEW_FILTER_OPERATORS aliases	Needs migration — all ~30 are actively being written to sys_metadata, because saveMeta persists the authored body verbatim and the schema's z.preprocess result is discarded.	⛔ Not planned. The write path is fixed (objectstack#4107): new saves persist canonical spellings, so the table stops growing. Every consumer already sees canonical after parse. Retiring the ~30 entries now buys a smaller spec file in exchange for rewriting live rows — and the aliases actively protect stored metadata for the day page/view props get strict validation.
The $-token set	Needs a compat shim — four hand-written driver switches hardcode it, and sys_sharing_rule.criteria_json + rollup field.filter store it.	⛔ Not planned. Renaming is still a migration, and drift is now guarded by filter-view-operator-parity.test.ts. Adding a token remains free; renaming buys nothing a test does not already give.
AggregationFunction (data/query.zod.ts)	Three places in lockstep — dataset-compiler.ts:24 a second hardcoded gate, native-sql-strategy.ts:362 a third switch.	✅ Done — objectstack#4153. This one was not cosmetic: the strategy's default: COUNT(*) meant a ninth spec aggregate would pass the compiler's gate, be advertised as supported by its error prose, then return a row count in place of the requested number, silently. Now derived from the spec with a guard that fails on a new member. A number/string/boolean metric hitting the same fallback is filed as objectstack#4157.

Precedent: d419826a8 (#3373) did this consolidation once for ViewFilterRule, and its changelog records that it also had to physically rewrite stored data. That was one plugin's seed file; the general case is customer rows.

Prerequisites — all resolved

1. ✅ objectstack#3948 item 1 — driver throws instead of skipping. Already landed when this issue was written; verified on origin/main (sql-driver.ts throws, driver-memory has 7 throw sites, both with regression tests) and objectstack#3948 is closed. Item 2 of it — the protocol passing an unparsed array through as an opaque where — continues as objectstack#4121, and is error locality, not correctness.
2. ✅ saveMeta persists the normalized filter subtree — objectstack#4107. graftNormalizedOperators walks the authored body and parsed.data in lockstep by structure and copies across only a changed operator, so the verbatim body (and its Studio-only auxiliary fields) survives.
3. ➖ Scan production before writing any migration. Moot: it gated items 1–3, which are now not planned. Still the first step if a future release chooses to retire the aliases anyway — as a self-directed cleanup, not to unblock anything.
4. ✅ Derive, don't duplicate. Partly structural rather than fixable: ui/ imports data/, so data/filter.zod.ts cannot import ui/view.zod.ts's vocabulary to derive from it. VALID_AST_OPERATORS is now derived from AST_OPERATOR_MAP, and filter-view-operator-parity.test.ts asserts the rest. The wording above is stale in one respect: that comment documents an in-repo asserted parity, not a cross-repo hand-sync.

Additions-only work that needs no migration

Safe in any order, because widening rejects nothing:

• Promote navigation into ActionType — fully implemented at core/src/actions/ActionRunner.ts:539, named in no spec enum.
• Promote or delete combo (plugin-charts/normalizeChartSchema.ts:63).
• Reconcile ActionType (6) vs WidgetActionTypeSchema (5): they differ only by form, dashboard header actions funnel into the same ActionRunner that implements form, and the narrower enum rejects at validation what the shared dispatcher executes.
• Derive ListChartConfigSchema.chartType (5) from ChartTypeSchema (19) via .extract([...]) instead of retyping it.

Do not remove members from ChartTypeSchema, ActionType, or PageComponentType. Although no framework file imports them by name, kernel/metadata-type-schemas.ts:68 maps view/dashboard/action/report/dataset to their schemas, so all of them are enforced at metadata save — a removal rejects already-stored metadata.

Refs #2901, #2231, objectstack-ai/objectstack#3948

[os-zhuang]

navigation → resolved by #2994 (merged). Not promoted, and not deleted.

The additions-only list above says "Promote navigation into ActionType". That was the wrong call, for a reason worth recording because it applies to the two rows below it as well:

The spec does not lack the concept — it spells it differently. type: 'url' is "go to a location", with openIn: 'self' | 'new-tab' for the tab choice. Promoting navigation would have put a second spec name on one operation, which is the failure this whole track is named after, committed one level up.

Deleting was worse, because it is silent: { type: 'navigation', to: … } is authored today (element:button CTAs), and without the case the action falls through to executeActionSchema, which returns { success: true } — a green toast that navigates nowhere. That is #2960's trap, reached via a cleanup.

And the alias had already drifted, which is the ordinary outcome of two implementations of one concept. executeNavigation was quietly the weaker of the two: no ${param.X} interpolation, openIn ignored, no apiBase promotion, no /api/… full-page short-circuit. So { type: 'navigation', to: '/x?p=${param.p}' } shipped the literal ${param.p} while the identical url action resolved it.

Resolved as a declared alias — ObjectUiLocalActionType, the treatment #2985 gave the page-visualization names — with both names routed through one navigator. So: a dialect row has a third option next to promote and delete, and it is often the right one.

The guard is structural rather than another assertion: built-in dispatch is now a table typed Record<RunnableActionType, …>, so an ActionType the spec adds stops compiling until an executor exists — #2942's "validates at save, renders nothing at run time" class, made a build error for actions.

---

Next item, pre-checked: combo is the same shape

The list says "Promote or delete combo (plugin-charts/normalizeChartSchema.ts:63)". It is a third case of the above, and the spec settles it outright:

// spec/src/ui/chart.zod.ts — ChartSeriesSchema
/** Series type override (combo charts) */
type: ChartTypeSchema.optional().describe('Override chart type for this series'),

The spec already models combo charts, per-series, and says so in the field's own doc comment. combo as a top-level chartType is a redundant container name for "the series have mixed families" — structurally identical to the argument the spec's own taxonomy note already makes about stacking:

stacking is not a chart family, it is a property of the series (ChartSeries.stack) … One bar family plus a series-level stack group expresses all three without multiplying the taxonomy.

So combo is not a capability the spec lacks. Unlike navigation, though, this one is a real behavior change in plugin-charts — AdvancedChartImpl.tsx:819 branches on chartType === 'combo', and the honest version derives "is combo" from whether series[].type varies. Wants its own PR.

The other two rows are unchanged and both need the framework: ActionType (6) vs WidgetActionTypeSchema (5) differ only by form, and deriving ListChartConfigSchema.chartType via .extract([...]) is spec-side.

[os-zhuang]

Progress — three PRs, and one correction to Track C's premise

Track A — done, framework #4061

All three orphans deleted, zero-consumer re-verified by grep across framework packages/ + apps/, objectui, and cloud on the current merge base.

Two things the issue's table did not anticipate:

AggregationFunctionEnum also collided by name. It exported a type called AggregationFunction; data/query.zod.ts exports a value of that name. Same identifier, two declaration spaces, different members (percentile/median/stddev/variance vs array_agg/string_agg).

The filters key could not simply go with FilterOperator. check:docs rejects deleting an authorable object key without a tombstone + a D2 conversion + a major FROM→TO mapping (ADR-0104) — the right rule, and the wrong trade for a shape nothing validated and no author writes, since Track A is meant to carry no migration. The key stays, retyped z.unknown() with the same NOT-YET-ENFORCED marker as SubscriptionEventSchema.filters (api/realtime.zod.ts). The two subscription surfaces now describe event filtering identically, and neither implies enforcement that does not exist.

Four generated ratchets had to move with the deletions — json-schema.manifest.json, authorable-surface.json, api-surface.json, and both the reference docs and the objectstack-ui skill reference index.

Additions-only — done, framework #4070

Three of the four items, plus a fork the audit did not name:

• ChartTypeSchema admits combo. The taxonomy could not name the family the rest of chart.zod.ts is written for: ChartSeriesSchema.type says "combo charts" in its own doc comment, and ChartSeriesSchema.yAxis binds left/right, which is only meaningful for mixed marks.
• WidgetActionTypeSchema is ActionType. Confirmed the issue's reading in objectui's code: DashboardRenderer routes everything except a raw url into the ActionRunner, deliberately, per the comment recording objectstack#3528.
• ListChartConfigSchema.chartType is ChartTypeSchema.extract([...]) — same five members. .extract does resolve through the lazySchema proxy.
• @objectstack/lint's chart-family set derives from the taxonomy. Not in the audit, and worth naming: validate-widget-bindings' hand-written list decides which widgets need a chartConfig measure mapping, and an unlisted family reads as "not a chart" — so the widget passes validation instead of being reported. combo was exactly that case; pinning the old list back reproduces it (zero findings).

app-showcase's coverage test — a ratchet already in place — failed the moment combo was admitted, and the Chart Gallery now demonstrates it.

navigation was deliberately not promoted, against the issue's suggestion. ActionRunner.executeNavigation is a strictly weaker executeUrl (no ${param.X} interpolation, no apiBase promotion, no openIn) differing only by a replace option, and its one live producer is the SDUI element:button action prop — which ElementButtonPropsSchema does not model at all. Promoting the name would put a second spelling of navigate into a closed vocabulary (members can't be removed later, per this issue's own rule) without closing the gap that actually exists. Filing the element:button.action gap separately.

objectui — merged, #2989

The third operator translation table, which the audit's Track B did not cover: view-config-utils' SPEC_TO_BUILDER_OP resolved 10 of the 19 canonical VIEW_FILTER_OPERATORS. Executed against the real spec:

OLD table could not resolve 9 of 19 canonical view operators:
  not_equals, starts_with, ends_with, greater_than, less_than,
  greater_than_or_equal, less_than_or_equal, is_null, is_not_null

Same cause as #2974 — spellings enumerated by hand — so it is now derived from the spec's canonical list plus VIEW_FILTER_OPERATOR_ALIASES, folded case- and separator-insensitively. @object-ui/components exports FILTER_BUILDER_OPERATORS so the mapping asserts against the builder's real vocabulary. To be precise about severity: toFilterGroup has no in-repo caller, so this was a public-API defect, not a live bug.

Correction: Track C's stated trigger is gone

The issue records that BUILDER_TO_SPEC_OP / toSpecFilter (view-config-utils.ts:46) emit 'not in', before and after verbatim, and objectstack#3948 cites that file as its reachable trigger. Both had zero callers anywhere in the repo — not exported from @object-ui/plugin-view, not even referenced by a test; they were left behind when the studio's spec-driven inspector replaced buildViewConfigSchema. They are deleted in #2989.

With #2974 merged and this deleted, objectui no longer has a live path emitting those spellings. Framework main has also since added before/after to AST_OPERATOR_MAP, which removes the trigger from the other side. objectstack#3948's remaining exposure is the server-side silent-drop itself — which is still real, and still what blocks Track C's VALID_AST_OPERATORS narrowing. The reachability argument in that issue needs updating, not the fix.

Still blocked, unchanged

Track C prerequisites 1–4 stand as written. Nothing in these three PRs narrows a vocabulary, so none of them touches stored metadata.