finding: the wire-only filter alias spellings (`filters` / `$filter`) are now declared in two packages, with no gate reconciling them

[hotlong]

Observation-class finding, split out of #7390 while implementing it. Unassigned, filed per Prime Directive #10. Nothing a user hits today — this is a drift seam, not a live defect.

What the seam is

The filter slot has four wire spellings, and they are declared in two places with different ownership:

• where and filter come from RPC_QUERY_ALIAS_SLOTS (packages/spec/src/data/data-engine.zod.ts), which its own docblock calls "the ONE place the alias to canonical mapping is declared".
• filters and $filter are wire-only — no schema declares them. packages/metadata-protocol extends the spec table with them locally (WIRE_QUERY_ALIAS_SLOTS).

#7390 added a third reader: packages/rest now gates the filter slot's arity at the querystring ingress, and needs the same four spellings to do it. It derives where / filter from the spec table, but cannot derive filters / $filter — @objectstack/metadata-protocol is a dev-only dependency of @objectstack/rest, so no runtime import of that table exists. They are named literally in packages/rest/src/query-multiplicity.ts (FILTER_SLOT_QUERY_PARAMS).

The consequence

A new wire-only alias for the filter slot, added to metadata-protocol's table, would fold correctly in the normalizer and be silently ungated at the ingress — repetition on that spelling would fall back to the misdiagnosis #7390 exists to remove. Nothing fails: the spelling works, the gate simply does not see it.

Half of it is already pinned: rest-server-repeated-filter-param.test.ts §5 asserts the derived set composes to exactly the four spellings, so a spec-table change goes red. The wire-only half has no such backstop, because the package holding the truth is not on the runtime graph.

Symmetric note: WIRE_DOLLAR_ALIASES in the same normalizer already carries a comment about exactly this class of mistake — "Adding a $ alias in one place and not the other is exactly how a parameter ends up folded but unchecked." That sentence is now true across a package boundary as well as within one.

Options

1. Hoist the wire-only spellings into @objectstack/spec — e.g. a WIRE_ONLY_QUERY_ALIASES export beside RPC_QUERY_ALIAS_SLOTS — so both metadata-protocol and rest read one table. Cleanest, and the only option that removes the seam rather than watching it. It touches the spec's public export surface (check:api-surface regeneration), and whether the wire vocabulary belongs in the spec at all is a genuine question: these spellings exist precisely because no schema declares them.
2. A cross-package consistency gate — a check: script asserting rest's literal set equals the normalizer's derived set. No dependency-graph change; adds a script whose only job is to watch two lists.
3. Leave it, documented. The set has been stable at four spellings for a long time, and the drift only bites if someone adds a fifth.

Recommendation is (1) if the spec seat wants the wire vocabulary declared at all, else (2). Both are cheap; neither is urgent.

Dedup

Searched open issues for WIRE_QUERY_ALIAS_SLOTS, RPC_QUERY_ALIAS_SLOTS, wire alias, $filter, filters plural, and query-alias drift. Hits: #7390 (the parent), #4436, #3774 — none covers the two-package declaration of the wire-only spellings.

---

Generated by Claude Code

[hotlong]

Triage: stays finding, deliberately left without domain:* — the lane is decided by the chosen shape (option 1 lands on packages/spec's public export surface; option 2 is a new scripts/ consistency gate → devx), and guessing would inject a wrong value into the one field with a single producer. Recording this so later sweeps read the bare-lane state as intentional.

Grading input for the findings round: option 1 only if the spec seat wants the wire-only vocabulary declared in the spec at all (a genuine question the card itself raises — these spellings exist precisely because no schema declares them); otherwise option 2. Neither is urgent: the set has been stable at four spellings, half of it is already pinned (rest-server-repeated-filter-param.test.ts §5), and the drift only bites on a fifth spelling.

---

Generated by Claude Code

[hotlong]

Triage: lands in domain:spec; rationale: the load-bearing question is option 1 — whether the wire-only alias vocabulary belongs on @objectstack/spec's export surface at all — and that is the spec seat's call; option 2's cross-package gate is the fallback if the answer is no. Held as finding (drift seam, nothing a user hits today, set stable at four spellings). Type: Task.

---

Generated by Claude Code

[hotlong]

Finding-grading round: promoted to pm:queue, re-routed domain:spec → domain:spec-tooling, scoped to option 2 — a check: script asserting rest's literal spelling set (query-multiplicity.ts:171-174) equals the normalizer's derived set (metadata-protocol WIRE_QUERY_ALIAS_SLOTS). Re-verified: @objectstack/metadata-protocol is a devDependency of rest (no runtime import possible), set still exactly four, and open PR #8142 now documents "any of the four spellings" as contract — raising the cost of a silent fifth.

Option 1 (hoist the wire vocabulary onto @objectstack/spec's export surface) is deliberately not foreclosed — it's a spec-surface expansion question the spec seat can raise separately if wanted; the gate is reversible, adds no public surface, and pays the drift risk down now either way.

---

Generated by Claude Code