[rest] `GET /data/:object/:id` folds no query aliases — the CANONICAL `fields` spelling is dropped while the alias `select` works

[hotlong]

Found while implementing #7606 (measuring that route's closed query-parameter set). Filed unassigned per Prime Directive #10; not fixed there, because widening a route's accepted spellings is surface expansion, not the recognition policy #7606 landed.

The condition

packages/spec/src/data/data-engine.zod.ts declares the alias table (RPC_QUERY_ALIAS_SLOTS) — "the ONE place the alias → canonical mapping is declared":

slot	canonical	alias
fields	fields	select
expand	expand	populate

GET /data/:object/:id reads exactly one line off the query string:

const { select, expand } = req.query || {};

So it honours the alias of the fields slot (select) and the canonical of the expand slot (expand), and folds nothing. ?fields=title and ?populate=owner never reach getData.

The asymmetry is per-slot and reads as arbitrary from outside: the same caller writing ?fields= and ?expand= gets one of the two honoured.

Why it mattered before #7606, and what changed

Until #7606 the drop was silent: ?fields=title returned the FULL record with a 200, indistinguishable from a caller who asked for everything — the exact silent-widening shape that card exists for.

Since #7606 the route declares a closed set (DATA_RECORD_READ_PARAMS = ['select', 'expand']) and both spellings are now refused with a located 400 naming select / expand as what the route accepts. So the failure is no longer silent, and this is no longer a correctness hole — it is an inconsistency with the declared alias table.

The two spellings were deliberately left OUTSIDE the closed set rather than added to it: putting them in the allowlist without implementing the fold would advertise a capability the handler does not have (declared ≠ enforced, Prime Directive #10), which is worse than refusing.

The sibling route already folds

GET /data/:object (list) passes its whole query to the metadata-protocol normalizer, which folds by the same table, extended with the wire-only spellings (filters, $filter, $expand). So ?fields= works on the list route and is refused on the by-id route.

The options

1. Fold the table on the by-id route — read the slots through foldQueryAliasSlots (or the normalizer) and add the folded spellings to the closed set. One rule, declared in one place, both routes agreeing. Costs an alias-conflict answer (?fields=a&select=b) that the route does not have today.
2. Leave it. The refusal is located and self-reporting, and select / expand are the documented spellings for this route. The table then describes the list route's ingress, not the whole data surface.
3. Retire the divergence from the other end — decide the by-id route's two names ARE the contract and note in the table that it is not universal.

Not obviously worth paying for; recording it so the next person to touch either the alias table or this handler is choosing rather than discovering.

Dedup

Searched open issues for the alias-table identifier, for select/fields/populate spelling wording, and for by-id read-route query handling. No open card covers it; #7606 is the parent this came out of, #8001 is the sibling recording a different cross-route divergence on the same file.

---

Generated by Claude Code

[hotlong]

Triage: routed domain:cli (the by-id read handler in packages/rest, same file family as sibling card #8001), held as finding — the filer's own assessment stands: since #7606 the drop is a located, self-reporting refusal, no caller is silently mis-served, and "not obviously worth paying for" is an honest grade. Grading happens at the findings round; the three options on the card are the menu. Type intent if promoted: Task.

One ordering note recorded now: if promoted, option 1 (fold the table on the by-id route) widens that route's accepted spellings — that is surface expansion on a public route, so the promotion grading should run the Feature-vs-Bug boundary test rather than assuming bug-class.

---

Generated by Claude Code

[hotlong]

Finding-grading round: escalated to needs-user-decision (domain:cli).

Premise re-verified on origin/main: DATA_RECORD_READ_PARAMS = ['select','expand'] (rest-server.ts:1782) and the in-code comment at :1779-1780 explicitly defers this question to this card. Widening a public route's accepted spellings is surface expansion — maintainer floor.

Question: is RPC_QUERY_ALIAS_SLOTS (the canonical↔alias table in packages/spec/src/data/data-engine.zod.ts) universal across data routes, or the list route's ingress only? Options: (1) fold the alias table on the record-read route (canonical fields starts working); (2) keep the narrow set but refuse unknown spellings loudly instead of dropping them silently; (3) keep + document as-is.

Four-prong analysis:

• Platform long-term coherence: one alias table read at every ingress is more coherent than per-route bespoke acceptance; today's state is the worst shape — the canonical spelling silently no-ops on one route while an alias works.
• Measured business pull: a caller following the documented canonical vocabulary gets silently ignored params today; no external user report yet, found by internal sweep.
• AI-agent error-resistance: silent drop is the trap — an agent writing ?fields= gets no error and wrong data. Option 2 (loud refusal) is the most error-resistant if the surface is to stay narrow; option 1 removes the inconsistency entirely.
• Startup scope discipline: option 1 widens an accepted surface (permanent obligation across all data routes); option 2 adds no surface and closes the silent-drop hole.

Recommendation: option 2 now (loud refusal, no surface growth), with option 1 only if the ruling declares the alias table universal — in which case it should be applied to all data routes in one card, not this route alone. Related: #8001 (sibling, closed this round), #7606 (parent).

---

Generated by Claude Code

[hotlong]

Maintainer ruling — 2026-08-12 (live PM chat, session_01GxKQfv3k8b6a2d2QrZU411; maintainer sam, verbatim: 「接受你的全部建议。」 accepting the decision-box analysis in full). Moved out of the decision box → pm:queue.

Ruling: option 2 — keep the narrow accepted set, but refuse unknown spellings loudly instead of dropping them silently. GET /data/:object/:id continues to accept select / expand, and a caller who sends fields (or any other alias-table spelling) gets a named refusal rather than silently-ignored parameters. No public surface growth.

⛔ Option 1 (fold the alias table onto this route) is not taken here: if the alias table is ever declared universal across data routes, that is one card applying it to all data routes, not a per-route widening — and it would need its own ruling. The in-code deferral comment at rest-server.ts:1779-1780 should be updated to record this ruling rather than left pointing at an open question.

Rationale on the record: today's shape is the worst of the three — the canonical spelling silently no-ops on this route while an alias works, which is precisely the trap an AI author walks into with no error to learn from. Sibling #8001 was closed this round (each route correct by its own standing rule); this ruling closes the silent-drop hole without creating the cross-route surface expansion that #8001 rejected.

---

Generated by Claude Code