feat(metadata): saveMeta persists the operator spellings the spec normalized (objectui#2945)

[os-zhuang]

Prerequisite 2 of the vocabulary consolidation blocked in objectstack-ai/objectui#2945. Prerequisite 1 (this repo's #3948 item 1 — drivers throw instead of silently skipping) has already landed, so this is what remains before the alias table can be retired at all.

The defect

ViewFilterRuleSchema.operator is z.preprocess(normalizeFilterOperator, z.enum(VIEW_FILTER_OPERATORS)). A stored notEquals / gt / isNull is therefore folded to its canonical form during save-time validation — and the result is thrown away.

saveMetaItem persists the authored body verbatim, and that is deliberate: parsed.data strips the Studio-only auxiliary fields (isPinned, isDefault, sortOrder) that intentionally ride along with an overlay document (ADR-0005§Validation, and the comment on resolveOverlaySchema says so).

The consequence is not that a legacy spelling survives — it is that every save mints new legacy-alias rows.

VIEW_FILTER_OPERATOR_ALIASES describes itself as "a migration bridge [that] may be dropped in a future major". With new alias rows arriving continuously there is no point at which the last one is behind you: a migration that rewrote every existing row would be obsolete the moment the next console personalization PUT landed. That is exactly why objectui#2945 lists this as a prerequisite rather than a nice-to-have.

The fix

graftNormalizedOperators(authored, parsed.data) grafts the normalization back on without giving up the verbatim body. It walks both trees in lockstep by structure and copies across exactly one thing: an operator whose parsed value differs from the authored one.

No key list. ViewFilterRule[] appears at five declared sites today — view filter, ViewTab.filter, page filterBy, and two component.zod.ts block props — and the structural walk covers all of them, plus any added later. Enumerating paths here would have reproduced in this file the exact duplication objectui#2945 exists to remove.

Nothing else moves:

• only an operator string is rewritten, and only where both sides are strings — so a $-token FilterCondition, a different operator vocabulary entirely, cannot be reshaped by accident;
• no key is added, removed, reordered or defaulted. The unary {field, operator} form does not acquire a value, even though the schema's own output gives it one;
• a body already canonical is returned by identity, so the common case allocates nothing.

Behaviour change, stated plainly

A GET after a PUT now returns the canonical spelling rather than the one the author sent. That is the spelling the spec defines; every renderer accepts it (objectstack-ai/objectui#2974 and objectstack-ai/objectui#2989 pinned all three of objectui's operator translation tables to the full vocabulary, in both directions, with parity guards); and it is the point of the change.

Existing rows are untouched. This stops the bleeding — it is not the migration. Prerequisite 3 of objectui#2945 (scan production before writing one) still stands, and is still not something CI can do: sys_saved_report.query_json is unvalidated on both write and read, so its contents cannot be enumerated statically.

Verification

• 11 new tests. One drives every alias VIEW_FILTER_OPERATOR_ALIASES still folds through the real ViewMetadataSchema — the schema getMetadataTypeSchema('view') returns, so the same one saveMetaItem validates against — and asserts the persisted body comes out canonical in each case.
• The negative half is pinned just as hard: aux fields survive, key sets are unchanged, filter order is preserved, a $-token object is left alone, a mismatched or longer parsed tree contributes nothing.
• Full @objectstack/metadata-protocol suite: 110 tests across 18 files, green.
• tsc --noEmit: zero errors in protocol.ts and the new test (the package has no type-check script; the 21 diagnostics a raw invocation reports are pre-existing, all in seed-loader/mutation-listener test files this PR does not touch).

Refs objectstack-ai/objectui#2945, objectstack-ai/objectui#2901, #3948

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Jul 30, 2026 9:59am

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/metadata-protocol.

1 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/concepts/metadata-lifecycle.mdx (via @objectstack/metadata-protocol)

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.