feat(metadata-protocol): reject unknown $-prefixed query params with 400 (#2926 ⑩)

Unsupported $ parameters (e.g. $foo, $inlinecount) used to fall into the
implicit-filter bucket and silently match zero rows — and before the $filter
alias existed, were dropped entirely, returning the unfiltered first page to
callers that believed they had a filtered result set. All supported aliases
are consumed before the guard, so anything $-prefixed that remains is a hard
400 UNSUPPORTED_QUERY_PARAM naming the offending keys and the supported list.
Bare-key implicit equality filters are unchanged.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017bJWtKmZ2mFpRFAmmmoeqe

Author: claude

.changeset/protocol-2926-unknown-dollar-params.md

@@ -0,0 +1,5 @@
+---
+'@objectstack/metadata-protocol': patch
+---
+
+fix(metadata-protocol): findData now rejects unknown `$`-prefixed query parameters with 400 `UNSUPPORTED_QUERY_PARAM` instead of silently treating them as implicit field-equality filters that match zero rows (#2926 ⑩). A `$`-prefixed key can never be a field name, so this is loud-failure only for the unsupported-alias class; bare-key implicit equality filtering is unchanged. The error message lists the supported aliases ($top, $skip, $orderby, $select, $count, $search, $searchFields, $filter, $expand).

packages/metadata-protocol/src/protocol.ts

@@ -2404,7 +2404,26 @@ export class ObjectStackProtocolImplementation implements ObjectStackProtocol {
             if (options[key] === 'true') options[key] = true;
             else if (options[key] === 'false') options[key] = false;
         }
-        
+
+        // [#2926 ⑩] Every supported OData-style `$` alias has been consumed and
+        // deleted above ($top/$skip/$orderby/$select/$count/$search/
+        // $searchFields/$filter/$expand). A `$`-prefixed key can never be a
+        // field name, so anything left is an unsupported query parameter —
+        // fail loudly instead of letting it fall into the implicit-filter
+        // bucket below, where it silently matched zero rows (or, before the
+        // $filter alias existed, was dropped entirely and returned the
+        // UNFILTERED page — a footgun for scripts resolving ids by name).
+        const unsupportedDollarParams = Object.keys(options).filter((k) => k.startsWith('$'));
+        if (unsupportedDollarParams.length > 0) {
+            const err: any = new Error(
+                `Unsupported query parameter(s): ${unsupportedDollarParams.join(', ')}. ` +
+                'Supported $-prefixed parameters: $top, $skip, $orderby, $select, $count, $search, $searchFields, $filter, $expand.',
+            );
+            err.status = 400;
+            err.code = 'UNSUPPORTED_QUERY_PARAM';
+            throw err;
+        }
+
         // Flat field filters: REST-style query params like ?id=abc&status=open
         // After extracting all known query parameters, any remaining keys are
         // treated as implicit field-level equality filters merged into `where`.

packages/objectql/src/protocol-data.test.ts

@@ -38,6 +38,40 @@ describe('ObjectStackProtocolImplementation - Data Operations', () => {
             expect(opts.where?.searchFields).toBeUndefined();
         });
 
+        // [#2926 ⑩] Unknown `$`-prefixed params must fail loudly instead of
+        // silently matching zero rows via the implicit-filter bucket (or —
+        // pre-$filter alias — being dropped and returning the unfiltered page).
+        it('rejects an unknown $-prefixed query param with 400 UNSUPPORTED_QUERY_PARAM', async () => {
+            await expect(
+                protocol.findData({ object: 'task', query: { $foo: '1' } }),
+            ).rejects.toMatchObject({ status: 400, code: 'UNSUPPORTED_QUERY_PARAM' });
+            expect(mockEngine.find).not.toHaveBeenCalled();
+        });
+
+        it('names the offending params and the supported list in the rejection message', async () => {
+            await expect(
+                protocol.findData({ object: 'task', query: { $inlinecount: 'allpages', $format: 'json' } }),
+            ).rejects.toThrow(/\$inlinecount.*\$format|\$format.*\$inlinecount/s);
+        });
+
+        it('still accepts every supported $ alias after the unknown-$ guard', async () => {
+            await protocol.findData({
+                object: 'task',
+                query: { $top: 5, $skip: 2, $orderby: 'name', $select: 'id,name', $search: 'x', $filter: { status: 'open' } },
+            });
+            expect(mockEngine.find).toHaveBeenCalledTimes(1);
+            const opts = mockEngine.find.mock.calls[0][1];
+            expect(opts.limit).toBe(5);
+            expect(opts.offset).toBe(2);
+            expect(opts.where).toEqual({ status: 'open' });
+        });
+
+        it('keeps bare unknown params as implicit field-equality filters (unchanged behavior)', async () => {
+            await protocol.findData({ object: 'task', query: { status: 'open' } });
+            const opts = mockEngine.find.mock.calls[0][1];
+            expect(opts.where).toEqual({ status: 'open' });
+        });
+
         it('should normalize $expand (OData) string to expand Record', async () => {
             await protocol.findData({ object: 'order_item', query: { $expand: 'order,product' } });