fix(spec): type ActionEngineFacade.find's second parameter as a FilterCondition, not an ObjectQL envelope (#14175)

.changeset/action-engine-facade-find-filter.md

@@ -0,0 +1,33 @@
+---
+"@objectstack/spec": patch
+---
+
+fix(spec): `ActionEngineFacade.find` declares its second parameter as a FILTER, not an ObjectQL envelope (#14175)
+
+`find(object, query: Record<string, unknown>)` documented nothing, and its
+parameter carried the name of the envelope every other read on the platform
+takes. The runtime (`buildActionEngineFacade`,
+`packages/runtime/src/action-execution.ts`) treats the argument as the bare
+`where` half — wrapping a non-empty one as `{ where: filter }` and passing
+`{}` through unwrapped — so a handler that passed the envelope got
+`{ where: { where: … } }`, matched nothing and returned `[]` with no error,
+while its one unfiltered read kept working. A hand-written test double built
+on the same belief passed every assertion; an application's headline action
+was a silent no-op for its whole life under a green suite.
+
+The member is now `find(object, filter: FilterCondition)` — the published
+`QueryAST.where` type — with a doc comment stating the contract, the runtime's
+wrap, and both limbs (envelope wrapped; empty passed through); the facade
+docblock points at it. The parameter's TYPE now says what the runtime does
+at the one place a handler author reads.
+
+Compile-layer signal only, shipped as `patch` (the #12615 precedent — a
+compile-time narrowing with no change in what parses or runs): no runtime
+behaviour changes, nothing changes in what the facade accepts or returns, and
+the narrowing bites only a primitive or a mistyped `$and` / `$or` / `$not`.
+⚠️ It does NOT refuse `{ where: … }` at compile time — `FilterCondition`'s
+string index signature admits `where` as a field name — so the compile-time
+bar is partial and the doc comment is the contract of record. An
+implementation typed with the old `Record<string, unknown>` still satisfies
+the interface (method parameters are bivariant), so nothing constructing the
+facade changes.

content/docs/ui/actions.mdx

@@ -146,6 +146,21 @@ export async function completeTask(ctx: ActionContext): Promise<void> {
 }
 ```
 
+<Callout type="warn">
+**`ctx.engine.find(object, filter)` takes a filter, not a query.** The second
+argument is the `where` half only — `{ status: 'completed' }`, operators
+(`{ amount: { $gt: 100 } }`), `$and` / `$or` / `$not` — and the runtime wraps
+it in `where` itself. Passing an ObjectQL envelope
+(`{ where: { status: 'completed' } }`) raises no error: it becomes
+`{ where: { where: … } }`, matches no row, and returns `[]`. An empty filter
+(`{}`) is passed through unwrapped, so the one unfiltered read works under
+either reading and a handler can look partially alive. The parameter is typed
+`FilterCondition` (`ActionEngineFacade` in `@objectstack/spec/ui`), which
+refuses a primitive or a mistyped `$and` / `$or` / `$not` but still admits
+`where` as a key — the sentence above is the contract, and a hand-written test
+double must honour it too.
+</Callout>
+
 ```typescript title="objectstack.config.ts"
 export const onEnable = async (ctx: { ql: { registerAction: (...args: unknown[]) => void } }) => {
  ctx.ql.registerAction('todo_task', 'completeTask', completeTask);

packages/spec/src/ui/action-params.test.ts

@@ -5,9 +5,11 @@ import {
  validateActionParams,
  ACTION_PARAM_BUILTIN_KEYS,
  ActionSessionSchema,
+ type ActionEngineFacade,
  type ActionSession,
  type ResolvedActionParam,
 } from './action-params.zod';
+import type { FilterCondition } from '../data/filter.zod';
 import { MIGRATIONS_BY_MAJOR } from '../migrations/registry';
 
 const codes = (issues: ReturnType<typeof validateActionParams>) => issues.map((i) => i.code).sort();
@@ -392,3 +394,77 @@ describe('#5779 — ActionSession `positions` canonical + `roles` deprecated ali
  expect(entry!.acceptanceCriteria).toMatch(/ctx\.session\.positions/);
  });
 });
+
+// ---------------------------------------------------------------------------
+// #14175 — `ActionEngineFacade.find` takes a FILTER, never an ObjectQL envelope
+// ---------------------------------------------------------------------------
+
+type Eq< A, B > = (< T >() => T extends A ? 1 : 2) extends (< T >() => T extends B ? 1 : 2) ? true : false;
+type Assert< T extends true > = T;
+
+// The declared slot, read off the interface — not a retyped copy of it, so a
+// re-widening back to an open record, or a rename of the type behind it, fails
+// HERE rather than in the first consumer to notice.
+type FindFilter = Parameters<ActionEngineFacade['find']>[1];
+
+// The type-level pin (the tsc channel, `tsc -p tsconfig.test.json`). `Eq` is
+// the strict mutual-assignability test, so `Record<string, unknown>` — the type
+// this slot carried before, and the one it must not drift back to — does not
+// satisfy it (measured: the same `Assert` against `Record<string, unknown>` is
+// a TS2344). Exported, as the sibling pins are, so `noUnusedLocals` does not
+// read a type that exists only to be checked as one that is never used.
+export type FindFilterIsFilterCondition = Assert< Eq< FindFilter, FilterCondition > >;
+
+describe('#14175 — ActionEngineFacade.find takes a FILTER (the `where` half), never an ObjectQL envelope', () => {
+ it('types the second parameter as the published `FilterCondition` (the tsc channel)', () => {
+ // The value-level half of `FindFilterIsFilterCondition` above: a literal
+ // annotated with the slot type, so the runtime run exercises the same
+ // declaration the type pin reads.
+ const filter: FindFilter = { position_code: 'qa_lead', active: true };
+ expect(Object.keys(filter)).toEqual(['position_code', 'active']);
+ });
+
+ it('positive control — every shape a handler legitimately passes compiles, the empty filter included', () => {
+ const implicitEquality: FindFilter = { status: 'completed' };
+ const explicitOperator: FindFilter = { position_code: { $in: ['qa_lead', 'qa_manager'] }, active: true };
+ const logical: FindFilter = {
+ $and: [{ active: true }, { $or: [{ tier: 'a' }, { tier: 'b' }] }],
+ $not: { archived: true },
+ };
+ // The runtime passes THIS one through unwrapped — the unfiltered read, and
+ // the one call that kept working in the reporting app under either belief.
+ const unfiltered: FindFilter = {};
+
+ expect([implicitEquality, explicitOperator, logical, unfiltered].every((f) => typeof f === 'object')).toBe(true);
+ });
+
+ it('refuses at compile time what `FilterCondition` refuses — a primitive and a mistyped logical operator', () => {
+ // Each `@ts-expect-error` is itself checked: if the type ever ADMITS one of
+ // these, the directive goes unused and `tsc -p tsconfig.test.json` reds.
+ // @ts-expect-error — a filter is an object; a bare string is not a `where` half.
+ const primitive: FindFilter = 'position_code = qa_lead';
+ // @ts-expect-error — `$and` is `FilterCondition[]`; a string is refused.
+ const andNotArray: FindFilter = { $and: 'active' };
+ // @ts-expect-error — `$or` is `FilterCondition[]`; a bare object is refused.
+ const orNotArray: FindFilter = { $or: { active: true } };
+ // @ts-expect-error — `$not` is a `FilterCondition`; a string is refused.
+ const notNotFilter: FindFilter = { $not: 'archived' };
+
+ expect([primitive, andNotArray, orNotArray, notNotFilter]).toHaveLength(4);
+ });
+
+ it('MEASURED GAP — the exact envelope mistake still compiles; the doc comment, not the type, is the contract', () => {
+ // `FilterCondition`'s string index signature is what lets a field NAME be a
+ // key, and `where` is a string — so the shape that returned `[]` in silence
+ // in the reporting app (`{ where: { position_code: 'qa_lead' } }`) is
+ // admitted by the type, one level down too. This pin RECORDS that
+ // measurement rather than hiding it: a later narrowing that refuses `where`
+ // at the top level turns it red on purpose, so the member's "does NOT
+ // refuse `{ where: … }`" sentence is updated with the type instead of
+ // drifting from it.
+ const envelope: FindFilter = { where: { position_code: 'qa_lead' } };
+ const nested: FindFilter = { where: { where: { position_code: 'qa_lead' } } };
+
+ expect('where' in envelope && 'where' in nested).toBe(true);
+ });
+});

packages/spec/src/ui/action-params.zod.ts

@@ -29,6 +29,7 @@
 import { z } from 'zod';
 
 import { valueSchemaFor } from '../data/field-value.zod';
+import type { FilterCondition } from '../data/filter.zod';
 import type { FieldErrorCode } from '../api/errors.zod';
 import { lazySchema } from '../shared/lazy-schema';
 
@@ -229,12 +230,50 @@ export function validateActionParams(
  * The slim engine facade an action handler's `ctx.engine` exposes. TRUSTED —
  * context-less, RLS/FLS-bypassing by design (#2849); the boundary is enforced
  * at invoke time (`ai.exposed` + the ADR-0066 D4 capability gate), not here.
+ *
+ * `find` is the one member whose argument shape the signature alone never
+ * settled: it takes a bare FILTER — the `where` half of a query — and never
+ * an ObjectQL query envelope; read its doc comment before writing a handler
+ * or a test double against it (#14175).
  */
 export interface ActionEngineFacade {
  insert(object: string, data: Record<string, unknown>): Promise<{ id: string }>;
  update(object: string, id: string, data: Record<string, unknown>): Promise<void>;
  delete(object: string, id: string): Promise<void>;
- find(object: string, query: Record<string, unknown>): Promise<Array<Record<string, unknown>>>;
+ /**
+ * Read the rows of `object` that match `filter`.
+ *
+ * `filter` is a FILTER — the `where` HALF of an ObjectQL query, the same
+ * {@link FilterCondition} that `QueryAST.where` carries: implicit equality
+ * `{ field: value }`, explicit operators `{ field: { $in: [...] } }`,
+ * `$and` / `$or` / `$not`. It is NOT the query ENVELOPE
+ * (`{ where, fields, orderBy, limit }`) that `DataEngine.find` and ObjectQL's
+ * own `engine.find` take — the shape this parameter's former name, `query`,
+ * invited. The runtime builds the envelope itself: `buildActionEngineFacade`'s
+ * `find` arm (`packages/runtime/src/action-execution.ts`, `:1183` on
+ * `369da918`) wraps a non-empty filter as `{ where: filter }` and passes an
+ * EMPTY filter (`{}`) through unwrapped — the unfiltered read.
+ *
+ * Two consequences, both silent (#14175):
+ *
+ * - An envelope passed here becomes `{ where: { where: … } }`. No object has
+ * a field named `where`, so the read matches nothing and resolves to `[]`
+ * with no error. A handler that made this mistake ran to completion over
+ * zero rows for as long as it shipped, and its own hand-written test
+ * double — written to the same belief, reading `query.where` — passed
+ * every assertion.
+ * - Because `{}` skips the wrap, an unfiltered call works under EITHER
+ * reading, so a handler mixing one unfiltered read with envelope-shaped
+ * ones looks partially alive rather than uniformly dead.
+ *
+ * What the type buys, exactly: `FilterCondition` refuses a primitive and a
+ * mistyped logical operator (`$and` / `$or` not arrays, `$not` not a
+ * filter). It does NOT refuse `{ where: … }` — its string index signature is
+ * what lets any field name stand as a key, and `where` is a string — so the
+ * envelope mistake still compiles, and this doc comment, not the type, is
+ * the contract of record. Both halves are pinned in `action-params.test.ts`.
+ */
+ find(object: string, filter: FilterCondition): Promise<Array<Record<string, unknown>>>;
 }
 
 /**

.changeset/action-engine-facade-find-filter.md

@@ -0,0 +1,33 @@
+---
+"@objectstack/spec": patch
+---
+
+fix(spec): `ActionEngineFacade.find` declares its second parameter as a FILTER, not an ObjectQL envelope (#14175)
+
+`find(object, query: Record<string, unknown>)` documented nothing, and its
+parameter carried the name of the envelope every other read on the platform
+takes. The runtime (`buildActionEngineFacade`,
+`packages/runtime/src/action-execution.ts`) treats the argument as the bare
+`where` half — wrapping a non-empty one as `{ where: filter }` and passing
+`{}` through unwrapped — so a handler that passed the envelope got
+`{ where: { where: … } }`, matched nothing and returned `[]` with no error,
+while its one unfiltered read kept working. A hand-written test double built
+on the same belief passed every assertion; an application's headline action
+was a silent no-op for its whole life under a green suite.
+
+The member is now `find(object, filter: FilterCondition)` — the published
+`QueryAST.where` type — with a doc comment stating the contract, the runtime's
+wrap, and both limbs (envelope wrapped; empty passed through); the facade
+docblock points at it. The parameter's TYPE now says what the runtime does
+at the one place a handler author reads.
+
+Compile-layer signal only, shipped as `patch` (the #12615 precedent — a
+compile-time narrowing with no change in what parses or runs): no runtime
+behaviour changes, nothing changes in what the facade accepts or returns, and
+the narrowing bites only a primitive or a mistyped `$and` / `$or` / `$not`.
+⚠️ It does NOT refuse `{ where: … }` at compile time — `FilterCondition`'s
+string index signature admits `where` as a field name — so the compile-time
+bar is partial and the doc comment is the contract of record. An
+implementation typed with the old `Record<string, unknown>` still satisfies
+the interface (method parameters are bivariant), so nothing constructing the
+facade changes.

content/docs/ui/actions.mdx

@@ -146,6 +146,21 @@ export async function completeTask(ctx: ActionContext): Promise<void> {
 }
 ```
 
+<Callout type="warn">
+**`ctx.engine.find(object, filter)` takes a filter, not a query.** The second
+argument is the `where` half only — `{ status: 'completed' }`, operators
+(`{ amount: { $gt: 100 } }`), `$and` / `$or` / `$not` — and the runtime wraps
+it in `where` itself. Passing an ObjectQL envelope
+(`{ where: { status: 'completed' } }`) raises no error: it becomes
+`{ where: { where: … } }`, matches no row, and returns `[]`. An empty filter
+(`{}`) is passed through unwrapped, so the one unfiltered read works under
+either reading and a handler can look partially alive. The parameter is typed
+`FilterCondition` (`ActionEngineFacade` in `@objectstack/spec/ui`), which
+refuses a primitive or a mistyped `$and` / `$or` / `$not` but still admits
+`where` as a key — the sentence above is the contract, and a hand-written test
+double must honour it too.
+</Callout>
+
 ```typescript title="objectstack.config.ts"
 export const onEnable = async (ctx: { ql: { registerAction: (...args: unknown[]) => void } }) => {
  ctx.ql.registerAction('todo_task', 'completeTask', completeTask);

packages/spec/src/ui/action-params.test.ts

@@ -5,9 +5,11 @@ import {
  validateActionParams,
  ACTION_PARAM_BUILTIN_KEYS,
  ActionSessionSchema,
+ type ActionEngineFacade,
  type ActionSession,
  type ResolvedActionParam,
 } from './action-params.zod';
+import type { FilterCondition } from '../data/filter.zod';
 import { MIGRATIONS_BY_MAJOR } from '../migrations/registry';
 
 const codes = (issues: ReturnType<typeof validateActionParams>) => issues.map((i) => i.code).sort();
@@ -392,3 +394,77 @@ describe('#5779 — ActionSession `positions` canonical + `roles` deprecated ali
  expect(entry!.acceptanceCriteria).toMatch(/ctx\.session\.positions/);
  });
 });
+
+// ---------------------------------------------------------------------------
+// #14175 — `ActionEngineFacade.find` takes a FILTER, never an ObjectQL envelope
+// ---------------------------------------------------------------------------
+
+type Eq< A, B > = (< T >() => T extends A ? 1 : 2) extends (< T >() => T extends B ? 1 : 2) ? true : false;
+type Assert< T extends true > = T;
+
+// The declared slot, read off the interface — not a retyped copy of it, so a
+// re-widening back to an open record, or a rename of the type behind it, fails
+// HERE rather than in the first consumer to notice.
+type FindFilter = Parameters<ActionEngineFacade['find']>[1];
+
+// The type-level pin (the tsc channel, `tsc -p tsconfig.test.json`). `Eq` is
+// the strict mutual-assignability test, so `Record<string, unknown>` — the type
+// this slot carried before, and the one it must not drift back to — does not
+// satisfy it (measured: the same `Assert` against `Record<string, unknown>` is
+// a TS2344). Exported, as the sibling pins are, so `noUnusedLocals` does not
+// read a type that exists only to be checked as one that is never used.
+export type FindFilterIsFilterCondition = Assert< Eq< FindFilter, FilterCondition > >;
+
+describe('#14175 — ActionEngineFacade.find takes a FILTER (the `where` half), never an ObjectQL envelope', () => {
+ it('types the second parameter as the published `FilterCondition` (the tsc channel)', () => {
+ // The value-level half of `FindFilterIsFilterCondition` above: a literal
+ // annotated with the slot type, so the runtime run exercises the same
+ // declaration the type pin reads.
+ const filter: FindFilter = { position_code: 'qa_lead', active: true };
+ expect(Object.keys(filter)).toEqual(['position_code', 'active']);
+ });
+
+ it('positive control — every shape a handler legitimately passes compiles, the empty filter included', () => {
+ const implicitEquality: FindFilter = { status: 'completed' };
+ const explicitOperator: FindFilter = { position_code: { $in: ['qa_lead', 'qa_manager'] }, active: true };
+ const logical: FindFilter = {
+ $and: [{ active: true }, { $or: [{ tier: 'a' }, { tier: 'b' }] }],
+ $not: { archived: true },
+ };
+ // The runtime passes THIS one through unwrapped — the unfiltered read, and
+ // the one call that kept working in the reporting app under either belief.
+ const unfiltered: FindFilter = {};
+
+ expect([implicitEquality, explicitOperator, logical, unfiltered].every((f) => typeof f === 'object')).toBe(true);
+ });
+
+ it('refuses at compile time what `FilterCondition` refuses — a primitive and a mistyped logical operator', () => {
+ // Each `@ts-expect-error` is itself checked: if the type ever ADMITS one of
+ // these, the directive goes unused and `tsc -p tsconfig.test.json` reds.
+ // @ts-expect-error — a filter is an object; a bare string is not a `where` half.
+ const primitive: FindFilter = 'position_code = qa_lead';
+ // @ts-expect-error — `$and` is `FilterCondition[]`; a string is refused.
+ const andNotArray: FindFilter = { $and: 'active' };
+ // @ts-expect-error — `$or` is `FilterCondition[]`; a bare object is refused.
+ const orNotArray: FindFilter = { $or: { active: true } };
+ // @ts-expect-error — `$not` is a `FilterCondition`; a string is refused.
+ const notNotFilter: FindFilter = { $not: 'archived' };
+
+ expect([primitive, andNotArray, orNotArray, notNotFilter]).toHaveLength(4);
+ });
+
+ it('MEASURED GAP — the exact envelope mistake still compiles; the doc comment, not the type, is the contract', () => {
+ // `FilterCondition`'s string index signature is what lets a field NAME be a
+ // key, and `where` is a string — so the shape that returned `[]` in silence
+ // in the reporting app (`{ where: { position_code: 'qa_lead' } }`) is
+ // admitted by the type, one level down too. This pin RECORDS that
+ // measurement rather than hiding it: a later narrowing that refuses `where`
+ // at the top level turns it red on purpose, so the member's "does NOT
+ // refuse `{ where: … }`" sentence is updated with the type instead of
+ // drifting from it.
+ const envelope: FindFilter = { where: { position_code: 'qa_lead' } };
+ const nested: FindFilter = { where: { where: { position_code: 'qa_lead' } } };
+
+ expect('where' in envelope && 'where' in nested).toBe(true);
+ });
+});

packages/spec/src/ui/action-params.zod.ts

@@ -29,6 +29,7 @@
 import { z } from 'zod';
 
 import { valueSchemaFor } from '../data/field-value.zod';
+import type { FilterCondition } from '../data/filter.zod';
 import type { FieldErrorCode } from '../api/errors.zod';
 import { lazySchema } from '../shared/lazy-schema';
 
@@ -229,12 +230,50 @@ export function validateActionParams(
  * The slim engine facade an action handler's `ctx.engine` exposes. TRUSTED —
  * context-less, RLS/FLS-bypassing by design (#2849); the boundary is enforced
  * at invoke time (`ai.exposed` + the ADR-0066 D4 capability gate), not here.
+ *
+ * `find` is the one member whose argument shape the signature alone never
+ * settled: it takes a bare FILTER — the `where` half of a query — and never
+ * an ObjectQL query envelope; read its doc comment before writing a handler
+ * or a test double against it (#14175).
  */
 export interface ActionEngineFacade {
  insert(object: string, data: Record<string, unknown>): Promise<{ id: string }>;
  update(object: string, id: string, data: Record<string, unknown>): Promise<void>;
  delete(object: string, id: string): Promise<void>;
- find(object: string, query: Record<string, unknown>): Promise<Array<Record<string, unknown>>>;
+ /**
+ * Read the rows of `object` that match `filter`.
+ *
+ * `filter` is a FILTER — the `where` HALF of an ObjectQL query, the same
+ * {@link FilterCondition} that `QueryAST.where` carries: implicit equality
+ * `{ field: value }`, explicit operators `{ field: { $in: [...] } }`,
+ * `$and` / `$or` / `$not`. It is NOT the query ENVELOPE
+ * (`{ where, fields, orderBy, limit }`) that `DataEngine.find` and ObjectQL's
+ * own `engine.find` take — the shape this parameter's former name, `query`,
+ * invited. The runtime builds the envelope itself: `buildActionEngineFacade`'s
+ * `find` arm (`packages/runtime/src/action-execution.ts`, `:1183` on
+ * `369da918`) wraps a non-empty filter as `{ where: filter }` and passes an
+ * EMPTY filter (`{}`) through unwrapped — the unfiltered read.
+ *
+ * Two consequences, both silent (#14175):
+ *
+ * - An envelope passed here becomes `{ where: { where: … } }`. No object has
+ * a field named `where`, so the read matches nothing and resolves to `[]`
+ * with no error. A handler that made this mistake ran to completion over
+ * zero rows for as long as it shipped, and its own hand-written test
+ * double — written to the same belief, reading `query.where` — passed
+ * every assertion.
+ * - Because `{}` skips the wrap, an unfiltered call works under EITHER
+ * reading, so a handler mixing one unfiltered read with envelope-shaped
+ * ones looks partially alive rather than uniformly dead.
+ *
+ * What the type buys, exactly: `FilterCondition` refuses a primitive and a
+ * mistyped logical operator (`$and` / `$or` not arrays, `$not` not a
+ * filter). It does NOT refuse `{ where: … }` — its string index signature is
+ * what lets any field name stand as a key, and `where` is a string — so the
+ * envelope mistake still compiles, and this doc comment, not the type, is
+ * the contract of record. Both halves are pinned in `action-params.test.ts`.
+ */
+ find(object: string, filter: FilterCondition): Promise<Array<Record<string, unknown>>>;
 }
 
 /**

.changeset/action-engine-facade-find-filter.md

@@ -0,0 +1,33 @@
+---
+"@objectstack/spec": patch
+---
+
+fix(spec): `ActionEngineFacade.find` declares its second parameter as a FILTER, not an ObjectQL envelope (#14175)
+
+`find(object, query: Record<string, unknown>)` documented nothing, and its
+parameter carried the name of the envelope every other read on the platform
+takes. The runtime (`buildActionEngineFacade`,
+`packages/runtime/src/action-execution.ts`) treats the argument as the bare
+`where` half — wrapping a non-empty one as `{ where: filter }` and passing
+`{}` through unwrapped — so a handler that passed the envelope got
+`{ where: { where: … } }`, matched nothing and returned `[]` with no error,
+while its one unfiltered read kept working. A hand-written test double built
+on the same belief passed every assertion; an application's headline action
+was a silent no-op for its whole life under a green suite.
+
+The member is now `find(object, filter: FilterCondition)` — the published
+`QueryAST.where` type — with a doc comment stating the contract, the runtime's
+wrap, and both limbs (envelope wrapped; empty passed through); the facade
+docblock points at it. The parameter's TYPE now says what the runtime does
+at the one place a handler author reads.
+
+Compile-layer signal only, shipped as `patch` (the #12615 precedent — a
+compile-time narrowing with no change in what parses or runs): no runtime
+behaviour changes, nothing changes in what the facade accepts or returns, and
+the narrowing bites only a primitive or a mistyped `$and` / `$or` / `$not`.
+⚠️ It does NOT refuse `{ where: … }` at compile time — `FilterCondition`'s
+string index signature admits `where` as a field name — so the compile-time
+bar is partial and the doc comment is the contract of record. An
+implementation typed with the old `Record<string, unknown>` still satisfies
+the interface (method parameters are bivariant), so nothing constructing the
+facade changes.

content/docs/ui/actions.mdx

@@ -146,6 +146,21 @@ export async function completeTask(ctx: ActionContext): Promise<void> {
 }
 ```
 
+<Callout type="warn">
+**`ctx.engine.find(object, filter)` takes a filter, not a query.** The second
+argument is the `where` half only — `{ status: 'completed' }`, operators
+(`{ amount: { $gt: 100 } }`), `$and` / `$or` / `$not` — and the runtime wraps
+it in `where` itself. Passing an ObjectQL envelope
+(`{ where: { status: 'completed' } }`) raises no error: it becomes
+`{ where: { where: … } }`, matches no row, and returns `[]`. An empty filter
+(`{}`) is passed through unwrapped, so the one unfiltered read works under
+either reading and a handler can look partially alive. The parameter is typed
+`FilterCondition` (`ActionEngineFacade` in `@objectstack/spec/ui`), which
+refuses a primitive or a mistyped `$and` / `$or` / `$not` but still admits
+`where` as a key — the sentence above is the contract, and a hand-written test
+double must honour it too.
+</Callout>
+
 ```typescript title="objectstack.config.ts"
 export const onEnable = async (ctx: { ql: { registerAction: (...args: unknown[]) => void } }) => {
  ctx.ql.registerAction('todo_task', 'completeTask', completeTask);

packages/spec/src/ui/action-params.test.ts

@@ -5,9 +5,11 @@ import {
  validateActionParams,
  ACTION_PARAM_BUILTIN_KEYS,
  ActionSessionSchema,
+ type ActionEngineFacade,
  type ActionSession,
  type ResolvedActionParam,
 } from './action-params.zod';
+import type { FilterCondition } from '../data/filter.zod';
 import { MIGRATIONS_BY_MAJOR } from '../migrations/registry';
 
 const codes = (issues: ReturnType<typeof validateActionParams>) => issues.map((i) => i.code).sort();
@@ -392,3 +394,77 @@ describe('#5779 — ActionSession `positions` canonical + `roles` deprecated ali
  expect(entry!.acceptanceCriteria).toMatch(/ctx\.session\.positions/);
  });
 });
+
+// ---------------------------------------------------------------------------
+// #14175 — `ActionEngineFacade.find` takes a FILTER, never an ObjectQL envelope
+// ---------------------------------------------------------------------------
+
+type Eq< A, B > = (< T >() => T extends A ? 1 : 2) extends (< T >() => T extends B ? 1 : 2) ? true : false;
+type Assert< T extends true > = T;
+
+// The declared slot, read off the interface — not a retyped copy of it, so a
+// re-widening back to an open record, or a rename of the type behind it, fails
+// HERE rather than in the first consumer to notice.
+type FindFilter = Parameters<ActionEngineFacade['find']>[1];
+
+// The type-level pin (the tsc channel, `tsc -p tsconfig.test.json`). `Eq` is
+// the strict mutual-assignability test, so `Record<string, unknown>` — the type
+// this slot carried before, and the one it must not drift back to — does not
+// satisfy it (measured: the same `Assert` against `Record<string, unknown>` is
+// a TS2344). Exported, as the sibling pins are, so `noUnusedLocals` does not
+// read a type that exists only to be checked as one that is never used.
+export type FindFilterIsFilterCondition = Assert< Eq< FindFilter, FilterCondition > >;
+
+describe('#14175 — ActionEngineFacade.find takes a FILTER (the `where` half), never an ObjectQL envelope', () => {
+ it('types the second parameter as the published `FilterCondition` (the tsc channel)', () => {
+ // The value-level half of `FindFilterIsFilterCondition` above: a literal
+ // annotated with the slot type, so the runtime run exercises the same
+ // declaration the type pin reads.
+ const filter: FindFilter = { position_code: 'qa_lead', active: true };
+ expect(Object.keys(filter)).toEqual(['position_code', 'active']);
+ });
+
+ it('positive control — every shape a handler legitimately passes compiles, the empty filter included', () => {
+ const implicitEquality: FindFilter = { status: 'completed' };
+ const explicitOperator: FindFilter = { position_code: { $in: ['qa_lead', 'qa_manager'] }, active: true };
+ const logical: FindFilter = {
+ $and: [{ active: true }, { $or: [{ tier: 'a' }, { tier: 'b' }] }],
+ $not: { archived: true },
+ };
+ // The runtime passes THIS one through unwrapped — the unfiltered read, and
+ // the one call that kept working in the reporting app under either belief.
+ const unfiltered: FindFilter = {};
+
+ expect([implicitEquality, explicitOperator, logical, unfiltered].every((f) => typeof f === 'object')).toBe(true);
+ });
+
+ it('refuses at compile time what `FilterCondition` refuses — a primitive and a mistyped logical operator', () => {
+ // Each `@ts-expect-error` is itself checked: if the type ever ADMITS one of
+ // these, the directive goes unused and `tsc -p tsconfig.test.json` reds.
+ // @ts-expect-error — a filter is an object; a bare string is not a `where` half.
+ const primitive: FindFilter = 'position_code = qa_lead';
+ // @ts-expect-error — `$and` is `FilterCondition[]`; a string is refused.
+ const andNotArray: FindFilter = { $and: 'active' };
+ // @ts-expect-error — `$or` is `FilterCondition[]`; a bare object is refused.
+ const orNotArray: FindFilter = { $or: { active: true } };
+ // @ts-expect-error — `$not` is a `FilterCondition`; a string is refused.
+ const notNotFilter: FindFilter = { $not: 'archived' };
+
+ expect([primitive, andNotArray, orNotArray, notNotFilter]).toHaveLength(4);
+ });
+
+ it('MEASURED GAP — the exact envelope mistake still compiles; the doc comment, not the type, is the contract', () => {
+ // `FilterCondition`'s string index signature is what lets a field NAME be a
+ // key, and `where` is a string — so the shape that returned `[]` in silence
+ // in the reporting app (`{ where: { position_code: 'qa_lead' } }`) is
+ // admitted by the type, one level down too. This pin RECORDS that
+ // measurement rather than hiding it: a later narrowing that refuses `where`
+ // at the top level turns it red on purpose, so the member's "does NOT
+ // refuse `{ where: … }`" sentence is updated with the type instead of
+ // drifting from it.
+ const envelope: FindFilter = { where: { position_code: 'qa_lead' } };
+ const nested: FindFilter = { where: { where: { position_code: 'qa_lead' } } };
+
+ expect('where' in envelope && 'where' in nested).toBe(true);
+ });
+});

packages/spec/src/ui/action-params.zod.ts

@@ -29,6 +29,7 @@
 import { z } from 'zod';
 
 import { valueSchemaFor } from '../data/field-value.zod';
+import type { FilterCondition } from '../data/filter.zod';
 import type { FieldErrorCode } from '../api/errors.zod';
 import { lazySchema } from '../shared/lazy-schema';
 
@@ -229,12 +230,50 @@ export function validateActionParams(
  * The slim engine facade an action handler's `ctx.engine` exposes. TRUSTED —
  * context-less, RLS/FLS-bypassing by design (#2849); the boundary is enforced
  * at invoke time (`ai.exposed` + the ADR-0066 D4 capability gate), not here.
+ *
+ * `find` is the one member whose argument shape the signature alone never
+ * settled: it takes a bare FILTER — the `where` half of a query — and never
+ * an ObjectQL query envelope; read its doc comment before writing a handler
+ * or a test double against it (#14175).
  */
 export interface ActionEngineFacade {
  insert(object: string, data: Record<string, unknown>): Promise<{ id: string }>;
  update(object: string, id: string, data: Record<string, unknown>): Promise<void>;
  delete(object: string, id: string): Promise<void>;
- find(object: string, query: Record<string, unknown>): Promise<Array<Record<string, unknown>>>;
+ /**
+ * Read the rows of `object` that match `filter`.
+ *
+ * `filter` is a FILTER — the `where` HALF of an ObjectQL query, the same
+ * {@link FilterCondition} that `QueryAST.where` carries: implicit equality
+ * `{ field: value }`, explicit operators `{ field: { $in: [...] } }`,
+ * `$and` / `$or` / `$not`. It is NOT the query ENVELOPE
+ * (`{ where, fields, orderBy, limit }`) that `DataEngine.find` and ObjectQL's
+ * own `engine.find` take — the shape this parameter's former name, `query`,
+ * invited. The runtime builds the envelope itself: `buildActionEngineFacade`'s
+ * `find` arm (`packages/runtime/src/action-execution.ts`, `:1183` on
+ * `369da918`) wraps a non-empty filter as `{ where: filter }` and passes an
+ * EMPTY filter (`{}`) through unwrapped — the unfiltered read.
+ *
+ * Two consequences, both silent (#14175):
+ *
+ * - An envelope passed here becomes `{ where: { where: … } }`. No object has
+ * a field named `where`, so the read matches nothing and resolves to `[]`
+ * with no error. A handler that made this mistake ran to completion over
+ * zero rows for as long as it shipped, and its own hand-written test
+ * double — written to the same belief, reading `query.where` — passed
+ * every assertion.
+ * - Because `{}` skips the wrap, an unfiltered call works under EITHER
+ * reading, so a handler mixing one unfiltered read with envelope-shaped
+ * ones looks partially alive rather than uniformly dead.
+ *
+ * What the type buys, exactly: `FilterCondition` refuses a primitive and a
+ * mistyped logical operator (`$and` / `$or` not arrays, `$not` not a
+ * filter). It does NOT refuse `{ where: … }` — its string index signature is
+ * what lets any field name stand as a key, and `where` is a string — so the
+ * envelope mistake still compiles, and this doc comment, not the type, is
+ * the contract of record. Both halves are pinned in `action-params.test.ts`.
+ */
+ find(object: string, filter: FilterCondition): Promise<Array<Record<string, unknown>>>;
 }
 
 /**

.changeset/action-engine-facade-find-filter.md

@@ -0,0 +1,33 @@
+---
+"@objectstack/spec": patch
+---
+
+fix(spec): `ActionEngineFacade.find` declares its second parameter as a FILTER, not an ObjectQL envelope (#14175)
+
+`find(object, query: Record<string, unknown>)` documented nothing, and its
+parameter carried the name of the envelope every other read on the platform
+takes. The runtime (`buildActionEngineFacade`,
+`packages/runtime/src/action-execution.ts`) treats the argument as the bare
+`where` half — wrapping a non-empty one as `{ where: filter }` and passing
+`{}` through unwrapped — so a handler that passed the envelope got
+`{ where: { where: … } }`, matched nothing and returned `[]` with no error,
+while its one unfiltered read kept working. A hand-written test double built
+on the same belief passed every assertion; an application's headline action
+was a silent no-op for its whole life under a green suite.
+
+The member is now `find(object, filter: FilterCondition)` — the published
+`QueryAST.where` type — with a doc comment stating the contract, the runtime's
+wrap, and both limbs (envelope wrapped; empty passed through); the facade
+docblock points at it. The parameter's TYPE now says what the runtime does
+at the one place a handler author reads.
+
+Compile-layer signal only, shipped as `patch` (the #12615 precedent — a
+compile-time narrowing with no change in what parses or runs): no runtime
+behaviour changes, nothing changes in what the facade accepts or returns, and
+the narrowing bites only a primitive or a mistyped `$and` / `$or` / `$not`.
+⚠️ It does NOT refuse `{ where: … }` at compile time — `FilterCondition`'s
+string index signature admits `where` as a field name — so the compile-time
+bar is partial and the doc comment is the contract of record. An
+implementation typed with the old `Record<string, unknown>` still satisfies
+the interface (method parameters are bivariant), so nothing constructing the
+facade changes.

content/docs/ui/actions.mdx

@@ -146,6 +146,21 @@ export async function completeTask(ctx: ActionContext): Promise<void> {
 }
 ```
 
+<Callout type="warn">
+**`ctx.engine.find(object, filter)` takes a filter, not a query.** The second
+argument is the `where` half only — `{ status: 'completed' }`, operators
+(`{ amount: { $gt: 100 } }`), `$and` / `$or` / `$not` — and the runtime wraps
+it in `where` itself. Passing an ObjectQL envelope
+(`{ where: { status: 'completed' } }`) raises no error: it becomes
+`{ where: { where: … } }`, matches no row, and returns `[]`. An empty filter
+(`{}`) is passed through unwrapped, so the one unfiltered read works under
+either reading and a handler can look partially alive. The parameter is typed
+`FilterCondition` (`ActionEngineFacade` in `@objectstack/spec/ui`), which
+refuses a primitive or a mistyped `$and` / `$or` / `$not` but still admits
+`where` as a key — the sentence above is the contract, and a hand-written test
+double must honour it too.
+</Callout>
+
 ```typescript title="objectstack.config.ts"
 export const onEnable = async (ctx: { ql: { registerAction: (...args: unknown[]) => void } }) => {
  ctx.ql.registerAction('todo_task', 'completeTask', completeTask);

packages/spec/src/ui/action-params.test.ts

@@ -5,9 +5,11 @@ import {
  validateActionParams,
  ACTION_PARAM_BUILTIN_KEYS,
  ActionSessionSchema,
+ type ActionEngineFacade,
  type ActionSession,
  type ResolvedActionParam,
 } from './action-params.zod';
+import type { FilterCondition } from '../data/filter.zod';
 import { MIGRATIONS_BY_MAJOR } from '../migrations/registry';
 
 const codes = (issues: ReturnType<typeof validateActionParams>) => issues.map((i) => i.code).sort();
@@ -392,3 +394,77 @@ describe('#5779 — ActionSession `positions` canonical + `roles` deprecated ali
  expect(entry!.acceptanceCriteria).toMatch(/ctx\.session\.positions/);
  });
 });
+
+// ---------------------------------------------------------------------------
+// #14175 — `ActionEngineFacade.find` takes a FILTER, never an ObjectQL envelope
+// ---------------------------------------------------------------------------
+
+type Eq< A, B > = (< T >() => T extends A ? 1 : 2) extends (< T >() => T extends B ? 1 : 2) ? true : false;
+type Assert< T extends true > = T;
+
+// The declared slot, read off the interface — not a retyped copy of it, so a
+// re-widening back to an open record, or a rename of the type behind it, fails
+// HERE rather than in the first consumer to notice.
+type FindFilter = Parameters<ActionEngineFacade['find']>[1];
+
+// The type-level pin (the tsc channel, `tsc -p tsconfig.test.json`). `Eq` is
+// the strict mutual-assignability test, so `Record<string, unknown>` — the type
+// this slot carried before, and the one it must not drift back to — does not
+// satisfy it (measured: the same `Assert` against `Record<string, unknown>` is
+// a TS2344). Exported, as the sibling pins are, so `noUnusedLocals` does not
+// read a type that exists only to be checked as one that is never used.
+export type FindFilterIsFilterCondition = Assert< Eq< FindFilter, FilterCondition > >;
+
+describe('#14175 — ActionEngineFacade.find takes a FILTER (the `where` half), never an ObjectQL envelope', () => {
+ it('types the second parameter as the published `FilterCondition` (the tsc channel)', () => {
+ // The value-level half of `FindFilterIsFilterCondition` above: a literal
+ // annotated with the slot type, so the runtime run exercises the same
+ // declaration the type pin reads.
+ const filter: FindFilter = { position_code: 'qa_lead', active: true };
+ expect(Object.keys(filter)).toEqual(['position_code', 'active']);
+ });
+
+ it('positive control — every shape a handler legitimately passes compiles, the empty filter included', () => {
+ const implicitEquality: FindFilter = { status: 'completed' };
+ const explicitOperator: FindFilter = { position_code: { $in: ['qa_lead', 'qa_manager'] }, active: true };
+ const logical: FindFilter = {
+ $and: [{ active: true }, { $or: [{ tier: 'a' }, { tier: 'b' }] }],
+ $not: { archived: true },
+ };
+ // The runtime passes THIS one through unwrapped — the unfiltered read, and
+ // the one call that kept working in the reporting app under either belief.
+ const unfiltered: FindFilter = {};
+
+ expect([implicitEquality, explicitOperator, logical, unfiltered].every((f) => typeof f === 'object')).toBe(true);
+ });
+
+ it('refuses at compile time what `FilterCondition` refuses — a primitive and a mistyped logical operator', () => {
+ // Each `@ts-expect-error` is itself checked: if the type ever ADMITS one of
+ // these, the directive goes unused and `tsc -p tsconfig.test.json` reds.
+ // @ts-expect-error — a filter is an object; a bare string is not a `where` half.
+ const primitive: FindFilter = 'position_code = qa_lead';
+ // @ts-expect-error — `$and` is `FilterCondition[]`; a string is refused.
+ const andNotArray: FindFilter = { $and: 'active' };
+ // @ts-expect-error — `$or` is `FilterCondition[]`; a bare object is refused.
+ const orNotArray: FindFilter = { $or: { active: true } };
+ // @ts-expect-error — `$not` is a `FilterCondition`; a string is refused.
+ const notNotFilter: FindFilter = { $not: 'archived' };
+
+ expect([primitive, andNotArray, orNotArray, notNotFilter]).toHaveLength(4);
+ });
+
+ it('MEASURED GAP — the exact envelope mistake still compiles; the doc comment, not the type, is the contract', () => {
+ // `FilterCondition`'s string index signature is what lets a field NAME be a
+ // key, and `where` is a string — so the shape that returned `[]` in silence
+ // in the reporting app (`{ where: { position_code: 'qa_lead' } }`) is
+ // admitted by the type, one level down too. This pin RECORDS that
+ // measurement rather than hiding it: a later narrowing that refuses `where`
+ // at the top level turns it red on purpose, so the member's "does NOT
+ // refuse `{ where: … }`" sentence is updated with the type instead of
+ // drifting from it.
+ const envelope: FindFilter = { where: { position_code: 'qa_lead' } };
+ const nested: FindFilter = { where: { where: { position_code: 'qa_lead' } } };
+
+ expect('where' in envelope && 'where' in nested).toBe(true);
+ });
+});

packages/spec/src/ui/action-params.zod.ts

@@ -29,6 +29,7 @@
 import { z } from 'zod';
 
 import { valueSchemaFor } from '../data/field-value.zod';
+import type { FilterCondition } from '../data/filter.zod';
 import type { FieldErrorCode } from '../api/errors.zod';
 import { lazySchema } from '../shared/lazy-schema';
 
@@ -229,12 +230,50 @@ export function validateActionParams(
  * The slim engine facade an action handler's `ctx.engine` exposes. TRUSTED —
  * context-less, RLS/FLS-bypassing by design (#2849); the boundary is enforced
  * at invoke time (`ai.exposed` + the ADR-0066 D4 capability gate), not here.
+ *
+ * `find` is the one member whose argument shape the signature alone never
+ * settled: it takes a bare FILTER — the `where` half of a query — and never
+ * an ObjectQL query envelope; read its doc comment before writing a handler
+ * or a test double against it (#14175).
  */
 export interface ActionEngineFacade {
  insert(object: string, data: Record<string, unknown>): Promise<{ id: string }>;
  update(object: string, id: string, data: Record<string, unknown>): Promise<void>;
  delete(object: string, id: string): Promise<void>;
- find(object: string, query: Record<string, unknown>): Promise<Array<Record<string, unknown>>>;
+ /**
+ * Read the rows of `object` that match `filter`.
+ *
+ * `filter` is a FILTER — the `where` HALF of an ObjectQL query, the same
+ * {@link FilterCondition} that `QueryAST.where` carries: implicit equality
+ * `{ field: value }`, explicit operators `{ field: { $in: [...] } }`,
+ * `$and` / `$or` / `$not`. It is NOT the query ENVELOPE
+ * (`{ where, fields, orderBy, limit }`) that `DataEngine.find` and ObjectQL's
+ * own `engine.find` take — the shape this parameter's former name, `query`,
+ * invited. The runtime builds the envelope itself: `buildActionEngineFacade`'s
+ * `find` arm (`packages/runtime/src/action-execution.ts`, `:1183` on
+ * `369da918`) wraps a non-empty filter as `{ where: filter }` and passes an
+ * EMPTY filter (`{}`) through unwrapped — the unfiltered read.
+ *
+ * Two consequences, both silent (#14175):
+ *
+ * - An envelope passed here becomes `{ where: { where: … } }`. No object has
+ * a field named `where`, so the read matches nothing and resolves to `[]`
+ * with no error. A handler that made this mistake ran to completion over
+ * zero rows for as long as it shipped, and its own hand-written test
+ * double — written to the same belief, reading `query.where` — passed
+ * every assertion.
+ * - Because `{}` skips the wrap, an unfiltered call works under EITHER
+ * reading, so a handler mixing one unfiltered read with envelope-shaped
+ * ones looks partially alive rather than uniformly dead.
+ *
+ * What the type buys, exactly: `FilterCondition` refuses a primitive and a
+ * mistyped logical operator (`$and` / `$or` not arrays, `$not` not a
+ * filter). It does NOT refuse `{ where: … }` — its string index signature is
+ * what lets any field name stand as a key, and `where` is a string — so the
+ * envelope mistake still compiles, and this doc comment, not the type, is
+ * the contract of record. Both halves are pinned in `action-params.test.ts`.
+ */
+ find(object: string, filter: FilterCondition): Promise<Array<Record<string, unknown>>>;
 }
 
 /**

.changeset/action-engine-facade-find-filter.md

@@ -0,0 +1,33 @@
+---
+"@objectstack/spec": patch
+---
+
+fix(spec): `ActionEngineFacade.find` declares its second parameter as a FILTER, not an ObjectQL envelope (#14175)
+
+`find(object, query: Record<string, unknown>)` documented nothing, and its
+parameter carried the name of the envelope every other read on the platform
+takes. The runtime (`buildActionEngineFacade`,
+`packages/runtime/src/action-execution.ts`) treats the argument as the bare
+`where` half — wrapping a non-empty one as `{ where: filter }` and passing
+`{}` through unwrapped — so a handler that passed the envelope got
+`{ where: { where: … } }`, matched nothing and returned `[]` with no error,
+while its one unfiltered read kept working. A hand-written test double built
+on the same belief passed every assertion; an application's headline action
+was a silent no-op for its whole life under a green suite.
+
+The member is now `find(object, filter: FilterCondition)` — the published
+`QueryAST.where` type — with a doc comment stating the contract, the runtime's
+wrap, and both limbs (envelope wrapped; empty passed through); the facade
+docblock points at it. The parameter's TYPE now says what the runtime does
+at the one place a handler author reads.
+
+Compile-layer signal only, shipped as `patch` (the #12615 precedent — a
+compile-time narrowing with no change in what parses or runs): no runtime
+behaviour changes, nothing changes in what the facade accepts or returns, and
+the narrowing bites only a primitive or a mistyped `$and` / `$or` / `$not`.
+⚠️ It does NOT refuse `{ where: … }` at compile time — `FilterCondition`'s
+string index signature admits `where` as a field name — so the compile-time
+bar is partial and the doc comment is the contract of record. An
+implementation typed with the old `Record<string, unknown>` still satisfies
+the interface (method parameters are bivariant), so nothing constructing the
+facade changes.

content/docs/ui/actions.mdx

@@ -146,6 +146,21 @@ export async function completeTask(ctx: ActionContext): Promise<void> {
 }
 ```
 
+<Callout type="warn">
+**`ctx.engine.find(object, filter)` takes a filter, not a query.** The second
+argument is the `where` half only — `{ status: 'completed' }`, operators
+(`{ amount: { $gt: 100 } }`), `$and` / `$or` / `$not` — and the runtime wraps
+it in `where` itself. Passing an ObjectQL envelope
+(`{ where: { status: 'completed' } }`) raises no error: it becomes
+`{ where: { where: … } }`, matches no row, and returns `[]`. An empty filter
+(`{}`) is passed through unwrapped, so the one unfiltered read works under
+either reading and a handler can look partially alive. The parameter is typed
+`FilterCondition` (`ActionEngineFacade` in `@objectstack/spec/ui`), which
+refuses a primitive or a mistyped `$and` / `$or` / `$not` but still admits
+`where` as a key — the sentence above is the contract, and a hand-written test
+double must honour it too.
+</Callout>
+
 ```typescript title="objectstack.config.ts"
 export const onEnable = async (ctx: { ql: { registerAction: (...args: unknown[]) => void } }) => {
  ctx.ql.registerAction('todo_task', 'completeTask', completeTask);

packages/spec/src/ui/action-params.test.ts

@@ -5,9 +5,11 @@ import {
  validateActionParams,
  ACTION_PARAM_BUILTIN_KEYS,
  ActionSessionSchema,
+ type ActionEngineFacade,
  type ActionSession,
  type ResolvedActionParam,
 } from './action-params.zod';
+import type { FilterCondition } from '../data/filter.zod';
 import { MIGRATIONS_BY_MAJOR } from '../migrations/registry';
 
 const codes = (issues: ReturnType<typeof validateActionParams>) => issues.map((i) => i.code).sort();
@@ -392,3 +394,77 @@ describe('#5779 — ActionSession `positions` canonical + `roles` deprecated ali
  expect(entry!.acceptanceCriteria).toMatch(/ctx\.session\.positions/);
  });
 });
+
+// ---------------------------------------------------------------------------
+// #14175 — `ActionEngineFacade.find` takes a FILTER, never an ObjectQL envelope
+// ---------------------------------------------------------------------------
+
+type Eq< A, B > = (< T >() => T extends A ? 1 : 2) extends (< T >() => T extends B ? 1 : 2) ? true : false;
+type Assert< T extends true > = T;
+
+// The declared slot, read off the interface — not a retyped copy of it, so a
+// re-widening back to an open record, or a rename of the type behind it, fails
+// HERE rather than in the first consumer to notice.
+type FindFilter = Parameters<ActionEngineFacade['find']>[1];
+
+// The type-level pin (the tsc channel, `tsc -p tsconfig.test.json`). `Eq` is
+// the strict mutual-assignability test, so `Record<string, unknown>` — the type
+// this slot carried before, and the one it must not drift back to — does not
+// satisfy it (measured: the same `Assert` against `Record<string, unknown>` is
+// a TS2344). Exported, as the sibling pins are, so `noUnusedLocals` does not
+// read a type that exists only to be checked as one that is never used.
+export type FindFilterIsFilterCondition = Assert< Eq< FindFilter, FilterCondition > >;
+
+describe('#14175 — ActionEngineFacade.find takes a FILTER (the `where` half), never an ObjectQL envelope', () => {
+ it('types the second parameter as the published `FilterCondition` (the tsc channel)', () => {
+ // The value-level half of `FindFilterIsFilterCondition` above: a literal
+ // annotated with the slot type, so the runtime run exercises the same
+ // declaration the type pin reads.
+ const filter: FindFilter = { position_code: 'qa_lead', active: true };
+ expect(Object.keys(filter)).toEqual(['position_code', 'active']);
+ });
+
+ it('positive control — every shape a handler legitimately passes compiles, the empty filter included', () => {
+ const implicitEquality: FindFilter = { status: 'completed' };
+ const explicitOperator: FindFilter = { position_code: { $in: ['qa_lead', 'qa_manager'] }, active: true };
+ const logical: FindFilter = {
+ $and: [{ active: true }, { $or: [{ tier: 'a' }, { tier: 'b' }] }],
+ $not: { archived: true },
+ };
+ // The runtime passes THIS one through unwrapped — the unfiltered read, and
+ // the one call that kept working in the reporting app under either belief.
+ const unfiltered: FindFilter = {};
+
+ expect([implicitEquality, explicitOperator, logical, unfiltered].every((f) => typeof f === 'object')).toBe(true);
+ });
+
+ it('refuses at compile time what `FilterCondition` refuses — a primitive and a mistyped logical operator', () => {
+ // Each `@ts-expect-error` is itself checked: if the type ever ADMITS one of
+ // these, the directive goes unused and `tsc -p tsconfig.test.json` reds.
+ // @ts-expect-error — a filter is an object; a bare string is not a `where` half.
+ const primitive: FindFilter = 'position_code = qa_lead';
+ // @ts-expect-error — `$and` is `FilterCondition[]`; a string is refused.
+ const andNotArray: FindFilter = { $and: 'active' };
+ // @ts-expect-error — `$or` is `FilterCondition[]`; a bare object is refused.
+ const orNotArray: FindFilter = { $or: { active: true } };
+ // @ts-expect-error — `$not` is a `FilterCondition`; a string is refused.
+ const notNotFilter: FindFilter = { $not: 'archived' };
+
+ expect([primitive, andNotArray, orNotArray, notNotFilter]).toHaveLength(4);
+ });
+
+ it('MEASURED GAP — the exact envelope mistake still compiles; the doc comment, not the type, is the contract', () => {
+ // `FilterCondition`'s string index signature is what lets a field NAME be a
+ // key, and `where` is a string — so the shape that returned `[]` in silence
+ // in the reporting app (`{ where: { position_code: 'qa_lead' } }`) is
+ // admitted by the type, one level down too. This pin RECORDS that
+ // measurement rather than hiding it: a later narrowing that refuses `where`
+ // at the top level turns it red on purpose, so the member's "does NOT
+ // refuse `{ where: … }`" sentence is updated with the type instead of
+ // drifting from it.
+ const envelope: FindFilter = { where: { position_code: 'qa_lead' } };
+ const nested: FindFilter = { where: { where: { position_code: 'qa_lead' } } };
+
+ expect('where' in envelope && 'where' in nested).toBe(true);
+ });
+});

packages/spec/src/ui/action-params.zod.ts

@@ -29,6 +29,7 @@
 import { z } from 'zod';
 
 import { valueSchemaFor } from '../data/field-value.zod';
+import type { FilterCondition } from '../data/filter.zod';
 import type { FieldErrorCode } from '../api/errors.zod';
 import { lazySchema } from '../shared/lazy-schema';
 
@@ -229,12 +230,50 @@ export function validateActionParams(
  * The slim engine facade an action handler's `ctx.engine` exposes. TRUSTED —
  * context-less, RLS/FLS-bypassing by design (#2849); the boundary is enforced
  * at invoke time (`ai.exposed` + the ADR-0066 D4 capability gate), not here.
+ *
+ * `find` is the one member whose argument shape the signature alone never
+ * settled: it takes a bare FILTER — the `where` half of a query — and never
+ * an ObjectQL query envelope; read its doc comment before writing a handler
+ * or a test double against it (#14175).
  */
 export interface ActionEngineFacade {
  insert(object: string, data: Record<string, unknown>): Promise<{ id: string }>;
  update(object: string, id: string, data: Record<string, unknown>): Promise<void>;
  delete(object: string, id: string): Promise<void>;
- find(object: string, query: Record<string, unknown>): Promise<Array<Record<string, unknown>>>;
+ /**
+ * Read the rows of `object` that match `filter`.
+ *
+ * `filter` is a FILTER — the `where` HALF of an ObjectQL query, the same
+ * {@link FilterCondition} that `QueryAST.where` carries: implicit equality
+ * `{ field: value }`, explicit operators `{ field: { $in: [...] } }`,
+ * `$and` / `$or` / `$not`. It is NOT the query ENVELOPE
+ * (`{ where, fields, orderBy, limit }`) that `DataEngine.find` and ObjectQL's
+ * own `engine.find` take — the shape this parameter's former name, `query`,
+ * invited. The runtime builds the envelope itself: `buildActionEngineFacade`'s
+ * `find` arm (`packages/runtime/src/action-execution.ts`, `:1183` on
+ * `369da918`) wraps a non-empty filter as `{ where: filter }` and passes an
+ * EMPTY filter (`{}`) through unwrapped — the unfiltered read.
+ *
+ * Two consequences, both silent (#14175):
+ *
+ * - An envelope passed here becomes `{ where: { where: … } }`. No object has
+ * a field named `where`, so the read matches nothing and resolves to `[]`
+ * with no error. A handler that made this mistake ran to completion over
+ * zero rows for as long as it shipped, and its own hand-written test
+ * double — written to the same belief, reading `query.where` — passed
+ * every assertion.
+ * - Because `{}` skips the wrap, an unfiltered call works under EITHER
+ * reading, so a handler mixing one unfiltered read with envelope-shaped
+ * ones looks partially alive rather than uniformly dead.
+ *
+ * What the type buys, exactly: `FilterCondition` refuses a primitive and a
+ * mistyped logical operator (`$and` / `$or` not arrays, `$not` not a
+ * filter). It does NOT refuse `{ where: … }` — its string index signature is
+ * what lets any field name stand as a key, and `where` is a string — so the
+ * envelope mistake still compiles, and this doc comment, not the type, is
+ * the contract of record. Both halves are pinned in `action-params.test.ts`.
+ */
+ find(object: string, filter: FilterCondition): Promise<Array<Record<string, unknown>>>;
 }
 
 /**

.changeset/action-engine-facade-find-filter.md

@@ -0,0 +1,33 @@
+---
+"@objectstack/spec": patch
+---
+
+fix(spec): `ActionEngineFacade.find` declares its second parameter as a FILTER, not an ObjectQL envelope (#14175)
+
+`find(object, query: Record<string, unknown>)` documented nothing, and its
+parameter carried the name of the envelope every other read on the platform
+takes. The runtime (`buildActionEngineFacade`,
+`packages/runtime/src/action-execution.ts`) treats the argument as the bare
+`where` half — wrapping a non-empty one as `{ where: filter }` and passing
+`{}` through unwrapped — so a handler that passed the envelope got
+`{ where: { where: … } }`, matched nothing and returned `[]` with no error,
+while its one unfiltered read kept working. A hand-written test double built
+on the same belief passed every assertion; an application's headline action
+was a silent no-op for its whole life under a green suite.
+
+The member is now `find(object, filter: FilterCondition)` — the published
+`QueryAST.where` type — with a doc comment stating the contract, the runtime's
+wrap, and both limbs (envelope wrapped; empty passed through); the facade
+docblock points at it. The parameter's TYPE now says what the runtime does
+at the one place a handler author reads.
+
+Compile-layer signal only, shipped as `patch` (the #12615 precedent — a
+compile-time narrowing with no change in what parses or runs): no runtime
+behaviour changes, nothing changes in what the facade accepts or returns, and
+the narrowing bites only a primitive or a mistyped `$and` / `$or` / `$not`.
+⚠️ It does NOT refuse `{ where: … }` at compile time — `FilterCondition`'s
+string index signature admits `where` as a field name — so the compile-time
+bar is partial and the doc comment is the contract of record. An
+implementation typed with the old `Record<string, unknown>` still satisfies
+the interface (method parameters are bivariant), so nothing constructing the
+facade changes.

content/docs/ui/actions.mdx

@@ -146,6 +146,21 @@ export async function completeTask(ctx: ActionContext): Promise<void> {
 }
 ```
 
+<Callout type="warn">
+**`ctx.engine.find(object, filter)` takes a filter, not a query.** The second
+argument is the `where` half only — `{ status: 'completed' }`, operators
+(`{ amount: { $gt: 100 } }`), `$and` / `$or` / `$not` — and the runtime wraps
+it in `where` itself. Passing an ObjectQL envelope
+(`{ where: { status: 'completed' } }`) raises no error: it becomes
+`{ where: { where: … } }`, matches no row, and returns `[]`. An empty filter
+(`{}`) is passed through unwrapped, so the one unfiltered read works under
+either reading and a handler can look partially alive. The parameter is typed
+`FilterCondition` (`ActionEngineFacade` in `@objectstack/spec/ui`), which
+refuses a primitive or a mistyped `$and` / `$or` / `$not` but still admits
+`where` as a key — the sentence above is the contract, and a hand-written test
+double must honour it too.
+</Callout>
+
 ```typescript title="objectstack.config.ts"
 export const onEnable = async (ctx: { ql: { registerAction: (...args: unknown[]) => void } }) => {
  ctx.ql.registerAction('todo_task', 'completeTask', completeTask);

packages/spec/src/ui/action-params.test.ts

@@ -5,9 +5,11 @@ import {
  validateActionParams,
  ACTION_PARAM_BUILTIN_KEYS,
  ActionSessionSchema,
+ type ActionEngineFacade,
  type ActionSession,
  type ResolvedActionParam,
 } from './action-params.zod';
+import type { FilterCondition } from '../data/filter.zod';
 import { MIGRATIONS_BY_MAJOR } from '../migrations/registry';
 
 const codes = (issues: ReturnType<typeof validateActionParams>) => issues.map((i) => i.code).sort();
@@ -392,3 +394,77 @@ describe('#5779 — ActionSession `positions` canonical + `roles` deprecated ali
  expect(entry!.acceptanceCriteria).toMatch(/ctx\.session\.positions/);
  });
 });
+
+// ---------------------------------------------------------------------------
+// #14175 — `ActionEngineFacade.find` takes a FILTER, never an ObjectQL envelope
+// ---------------------------------------------------------------------------
+
+type Eq< A, B > = (< T >() => T extends A ? 1 : 2) extends (< T >() => T extends B ? 1 : 2) ? true : false;
+type Assert< T extends true > = T;
+
+// The declared slot, read off the interface — not a retyped copy of it, so a
+// re-widening back to an open record, or a rename of the type behind it, fails
+// HERE rather than in the first consumer to notice.
+type FindFilter = Parameters<ActionEngineFacade['find']>[1];
+
+// The type-level pin (the tsc channel, `tsc -p tsconfig.test.json`). `Eq` is
+// the strict mutual-assignability test, so `Record<string, unknown>` — the type
+// this slot carried before, and the one it must not drift back to — does not
+// satisfy it (measured: the same `Assert` against `Record<string, unknown>` is
+// a TS2344). Exported, as the sibling pins are, so `noUnusedLocals` does not
+// read a type that exists only to be checked as one that is never used.
+export type FindFilterIsFilterCondition = Assert< Eq< FindFilter, FilterCondition > >;
+
+describe('#14175 — ActionEngineFacade.find takes a FILTER (the `where` half), never an ObjectQL envelope', () => {
+ it('types the second parameter as the published `FilterCondition` (the tsc channel)', () => {
+ // The value-level half of `FindFilterIsFilterCondition` above: a literal
+ // annotated with the slot type, so the runtime run exercises the same
+ // declaration the type pin reads.
+ const filter: FindFilter = { position_code: 'qa_lead', active: true };
+ expect(Object.keys(filter)).toEqual(['position_code', 'active']);
+ });
+
+ it('positive control — every shape a handler legitimately passes compiles, the empty filter included', () => {
+ const implicitEquality: FindFilter = { status: 'completed' };
+ const explicitOperator: FindFilter = { position_code: { $in: ['qa_lead', 'qa_manager'] }, active: true };
+ const logical: FindFilter = {
+ $and: [{ active: true }, { $or: [{ tier: 'a' }, { tier: 'b' }] }],
+ $not: { archived: true },
+ };
+ // The runtime passes THIS one through unwrapped — the unfiltered read, and
+ // the one call that kept working in the reporting app under either belief.
+ const unfiltered: FindFilter = {};
+
+ expect([implicitEquality, explicitOperator, logical, unfiltered].every((f) => typeof f === 'object')).toBe(true);
+ });
+
+ it('refuses at compile time what `FilterCondition` refuses — a primitive and a mistyped logical operator', () => {
+ // Each `@ts-expect-error` is itself checked: if the type ever ADMITS one of
+ // these, the directive goes unused and `tsc -p tsconfig.test.json` reds.
+ // @ts-expect-error — a filter is an object; a bare string is not a `where` half.
+ const primitive: FindFilter = 'position_code = qa_lead';
+ // @ts-expect-error — `$and` is `FilterCondition[]`; a string is refused.
+ const andNotArray: FindFilter = { $and: 'active' };
+ // @ts-expect-error — `$or` is `FilterCondition[]`; a bare object is refused.
+ const orNotArray: FindFilter = { $or: { active: true } };
+ // @ts-expect-error — `$not` is a `FilterCondition`; a string is refused.
+ const notNotFilter: FindFilter = { $not: 'archived' };
+
+ expect([primitive, andNotArray, orNotArray, notNotFilter]).toHaveLength(4);
+ });
+
+ it('MEASURED GAP — the exact envelope mistake still compiles; the doc comment, not the type, is the contract', () => {
+ // `FilterCondition`'s string index signature is what lets a field NAME be a
+ // key, and `where` is a string — so the shape that returned `[]` in silence
+ // in the reporting app (`{ where: { position_code: 'qa_lead' } }`) is
+ // admitted by the type, one level down too. This pin RECORDS that
+ // measurement rather than hiding it: a later narrowing that refuses `where`
+ // at the top level turns it red on purpose, so the member's "does NOT
+ // refuse `{ where: … }`" sentence is updated with the type instead of
+ // drifting from it.
+ const envelope: FindFilter = { where: { position_code: 'qa_lead' } };
+ const nested: FindFilter = { where: { where: { position_code: 'qa_lead' } } };
+
+ expect('where' in envelope && 'where' in nested).toBe(true);
+ });
+});

packages/spec/src/ui/action-params.zod.ts

@@ -29,6 +29,7 @@
 import { z } from 'zod';
 
 import { valueSchemaFor } from '../data/field-value.zod';
+import type { FilterCondition } from '../data/filter.zod';
 import type { FieldErrorCode } from '../api/errors.zod';
 import { lazySchema } from '../shared/lazy-schema';
 
@@ -229,12 +230,50 @@ export function validateActionParams(
  * The slim engine facade an action handler's `ctx.engine` exposes. TRUSTED —
  * context-less, RLS/FLS-bypassing by design (#2849); the boundary is enforced
  * at invoke time (`ai.exposed` + the ADR-0066 D4 capability gate), not here.
+ *
+ * `find` is the one member whose argument shape the signature alone never
+ * settled: it takes a bare FILTER — the `where` half of a query — and never
+ * an ObjectQL query envelope; read its doc comment before writing a handler
+ * or a test double against it (#14175).
  */
 export interface ActionEngineFacade {
  insert(object: string, data: Record<string, unknown>): Promise<{ id: string }>;
  update(object: string, id: string, data: Record<string, unknown>): Promise<void>;
  delete(object: string, id: string): Promise<void>;
- find(object: string, query: Record<string, unknown>): Promise<Array<Record<string, unknown>>>;
+ /**
+ * Read the rows of `object` that match `filter`.
+ *
+ * `filter` is a FILTER — the `where` HALF of an ObjectQL query, the same
+ * {@link FilterCondition} that `QueryAST.where` carries: implicit equality
+ * `{ field: value }`, explicit operators `{ field: { $in: [...] } }`,
+ * `$and` / `$or` / `$not`. It is NOT the query ENVELOPE
+ * (`{ where, fields, orderBy, limit }`) that `DataEngine.find` and ObjectQL's
+ * own `engine.find` take — the shape this parameter's former name, `query`,
+ * invited. The runtime builds the envelope itself: `buildActionEngineFacade`'s
+ * `find` arm (`packages/runtime/src/action-execution.ts`, `:1183` on
+ * `369da918`) wraps a non-empty filter as `{ where: filter }` and passes an
+ * EMPTY filter (`{}`) through unwrapped — the unfiltered read.
+ *
+ * Two consequences, both silent (#14175):
+ *
+ * - An envelope passed here becomes `{ where: { where: … } }`. No object has
+ * a field named `where`, so the read matches nothing and resolves to `[]`
+ * with no error. A handler that made this mistake ran to completion over
+ * zero rows for as long as it shipped, and its own hand-written test
+ * double — written to the same belief, reading `query.where` — passed
+ * every assertion.
+ * - Because `{}` skips the wrap, an unfiltered call works under EITHER
+ * reading, so a handler mixing one unfiltered read with envelope-shaped
+ * ones looks partially alive rather than uniformly dead.
+ *
+ * What the type buys, exactly: `FilterCondition` refuses a primitive and a
+ * mistyped logical operator (`$and` / `$or` not arrays, `$not` not a
+ * filter). It does NOT refuse `{ where: … }` — its string index signature is
+ * what lets any field name stand as a key, and `where` is a string — so the
+ * envelope mistake still compiles, and this doc comment, not the type, is
+ * the contract of record. Both halves are pinned in `action-params.test.ts`.
+ */
+ find(object: string, filter: FilterCondition): Promise<Array<Record<string, unknown>>>;
 }
 
 /**

.changeset/action-engine-facade-find-filter.md

@@ -0,0 +1,33 @@
+---
+"@objectstack/spec": patch
+---
+
+fix(spec): `ActionEngineFacade.find` declares its second parameter as a FILTER, not an ObjectQL envelope (#14175)
+
+`find(object, query: Record<string, unknown>)` documented nothing, and its
+parameter carried the name of the envelope every other read on the platform
+takes. The runtime (`buildActionEngineFacade`,
+`packages/runtime/src/action-execution.ts`) treats the argument as the bare
+`where` half — wrapping a non-empty one as `{ where: filter }` and passing
+`{}` through unwrapped — so a handler that passed the envelope got
+`{ where: { where: … } }`, matched nothing and returned `[]` with no error,
+while its one unfiltered read kept working. A hand-written test double built
+on the same belief passed every assertion; an application's headline action
+was a silent no-op for its whole life under a green suite.
+
+The member is now `find(object, filter: FilterCondition)` — the published
+`QueryAST.where` type — with a doc comment stating the contract, the runtime's
+wrap, and both limbs (envelope wrapped; empty passed through); the facade
+docblock points at it. The parameter's TYPE now says what the runtime does
+at the one place a handler author reads.
+
+Compile-layer signal only, shipped as `patch` (the #12615 precedent — a
+compile-time narrowing with no change in what parses or runs): no runtime
+behaviour changes, nothing changes in what the facade accepts or returns, and
+the narrowing bites only a primitive or a mistyped `$and` / `$or` / `$not`.
+⚠️ It does NOT refuse `{ where: … }` at compile time — `FilterCondition`'s
+string index signature admits `where` as a field name — so the compile-time
+bar is partial and the doc comment is the contract of record. An
+implementation typed with the old `Record<string, unknown>` still satisfies
+the interface (method parameters are bivariant), so nothing constructing the
+facade changes.

content/docs/ui/actions.mdx

@@ -146,6 +146,21 @@ export async function completeTask(ctx: ActionContext): Promise<void> {
 }
 ```
 
+<Callout type="warn">
+**`ctx.engine.find(object, filter)` takes a filter, not a query.** The second
+argument is the `where` half only — `{ status: 'completed' }`, operators
+(`{ amount: { $gt: 100 } }`), `$and` / `$or` / `$not` — and the runtime wraps
+it in `where` itself. Passing an ObjectQL envelope
+(`{ where: { status: 'completed' } }`) raises no error: it becomes
+`{ where: { where: … } }`, matches no row, and returns `[]`. An empty filter
+(`{}`) is passed through unwrapped, so the one unfiltered read works under
+either reading and a handler can look partially alive. The parameter is typed
+`FilterCondition` (`ActionEngineFacade` in `@objectstack/spec/ui`), which
+refuses a primitive or a mistyped `$and` / `$or` / `$not` but still admits
+`where` as a key — the sentence above is the contract, and a hand-written test
+double must honour it too.
+</Callout>
+
 ```typescript title="objectstack.config.ts"
 export const onEnable = async (ctx: { ql: { registerAction: (...args: unknown[]) => void } }) => {
  ctx.ql.registerAction('todo_task', 'completeTask', completeTask);

packages/spec/src/ui/action-params.test.ts

@@ -5,9 +5,11 @@ import {
  validateActionParams,
  ACTION_PARAM_BUILTIN_KEYS,
  ActionSessionSchema,
+ type ActionEngineFacade,
  type ActionSession,
  type ResolvedActionParam,
 } from './action-params.zod';
+import type { FilterCondition } from '../data/filter.zod';
 import { MIGRATIONS_BY_MAJOR } from '../migrations/registry';
 
 const codes = (issues: ReturnType<typeof validateActionParams>) => issues.map((i) => i.code).sort();
@@ -392,3 +394,77 @@ describe('#5779 — ActionSession `positions` canonical + `roles` deprecated ali
  expect(entry!.acceptanceCriteria).toMatch(/ctx\.session\.positions/);
  });
 });
+
+// ---------------------------------------------------------------------------
+// #14175 — `ActionEngineFacade.find` takes a FILTER, never an ObjectQL envelope
+// ---------------------------------------------------------------------------
+
+type Eq< A, B > = (< T >() => T extends A ? 1 : 2) extends (< T >() => T extends B ? 1 : 2) ? true : false;
+type Assert< T extends true > = T;
+
+// The declared slot, read off the interface — not a retyped copy of it, so a
+// re-widening back to an open record, or a rename of the type behind it, fails
+// HERE rather than in the first consumer to notice.
+type FindFilter = Parameters<ActionEngineFacade['find']>[1];
+
+// The type-level pin (the tsc channel, `tsc -p tsconfig.test.json`). `Eq` is
+// the strict mutual-assignability test, so `Record<string, unknown>` — the type
+// this slot carried before, and the one it must not drift back to — does not
+// satisfy it (measured: the same `Assert` against `Record<string, unknown>` is
+// a TS2344). Exported, as the sibling pins are, so `noUnusedLocals` does not
+// read a type that exists only to be checked as one that is never used.
+export type FindFilterIsFilterCondition = Assert< Eq< FindFilter, FilterCondition > >;
+
+describe('#14175 — ActionEngineFacade.find takes a FILTER (the `where` half), never an ObjectQL envelope', () => {
+ it('types the second parameter as the published `FilterCondition` (the tsc channel)', () => {
+ // The value-level half of `FindFilterIsFilterCondition` above: a literal
+ // annotated with the slot type, so the runtime run exercises the same
+ // declaration the type pin reads.
+ const filter: FindFilter = { position_code: 'qa_lead', active: true };
+ expect(Object.keys(filter)).toEqual(['position_code', 'active']);
+ });
+
+ it('positive control — every shape a handler legitimately passes compiles, the empty filter included', () => {
+ const implicitEquality: FindFilter = { status: 'completed' };
+ const explicitOperator: FindFilter = { position_code: { $in: ['qa_lead', 'qa_manager'] }, active: true };
+ const logical: FindFilter = {
+ $and: [{ active: true }, { $or: [{ tier: 'a' }, { tier: 'b' }] }],
+ $not: { archived: true },
+ };
+ // The runtime passes THIS one through unwrapped — the unfiltered read, and
+ // the one call that kept working in the reporting app under either belief.
+ const unfiltered: FindFilter = {};
+
+ expect([implicitEquality, explicitOperator, logical, unfiltered].every((f) => typeof f === 'object')).toBe(true);
+ });
+
+ it('refuses at compile time what `FilterCondition` refuses — a primitive and a mistyped logical operator', () => {
+ // Each `@ts-expect-error` is itself checked: if the type ever ADMITS one of
+ // these, the directive goes unused and `tsc -p tsconfig.test.json` reds.
+ // @ts-expect-error — a filter is an object; a bare string is not a `where` half.
+ const primitive: FindFilter = 'position_code = qa_lead';
+ // @ts-expect-error — `$and` is `FilterCondition[]`; a string is refused.
+ const andNotArray: FindFilter = { $and: 'active' };
+ // @ts-expect-error — `$or` is `FilterCondition[]`; a bare object is refused.
+ const orNotArray: FindFilter = { $or: { active: true } };
+ // @ts-expect-error — `$not` is a `FilterCondition`; a string is refused.
+ const notNotFilter: FindFilter = { $not: 'archived' };
+
+ expect([primitive, andNotArray, orNotArray, notNotFilter]).toHaveLength(4);
+ });
+
+ it('MEASURED GAP — the exact envelope mistake still compiles; the doc comment, not the type, is the contract', () => {
+ // `FilterCondition`'s string index signature is what lets a field NAME be a
+ // key, and `where` is a string — so the shape that returned `[]` in silence
+ // in the reporting app (`{ where: { position_code: 'qa_lead' } }`) is
+ // admitted by the type, one level down too. This pin RECORDS that
+ // measurement rather than hiding it: a later narrowing that refuses `where`
+ // at the top level turns it red on purpose, so the member's "does NOT
+ // refuse `{ where: … }`" sentence is updated with the type instead of
+ // drifting from it.
+ const envelope: FindFilter = { where: { position_code: 'qa_lead' } };
+ const nested: FindFilter = { where: { where: { position_code: 'qa_lead' } } };
+
+ expect('where' in envelope && 'where' in nested).toBe(true);
+ });
+});

packages/spec/src/ui/action-params.zod.ts

@@ -29,6 +29,7 @@
 import { z } from 'zod';
 
 import { valueSchemaFor } from '../data/field-value.zod';
+import type { FilterCondition } from '../data/filter.zod';
 import type { FieldErrorCode } from '../api/errors.zod';
 import { lazySchema } from '../shared/lazy-schema';
 
@@ -229,12 +230,50 @@ export function validateActionParams(
  * The slim engine facade an action handler's `ctx.engine` exposes. TRUSTED —
  * context-less, RLS/FLS-bypassing by design (#2849); the boundary is enforced
  * at invoke time (`ai.exposed` + the ADR-0066 D4 capability gate), not here.
+ *
+ * `find` is the one member whose argument shape the signature alone never
+ * settled: it takes a bare FILTER — the `where` half of a query — and never
+ * an ObjectQL query envelope; read its doc comment before writing a handler
+ * or a test double against it (#14175).
  */
 export interface ActionEngineFacade {
  insert(object: string, data: Record<string, unknown>): Promise<{ id: string }>;
  update(object: string, id: string, data: Record<string, unknown>): Promise<void>;
  delete(object: string, id: string): Promise<void>;
- find(object: string, query: Record<string, unknown>): Promise<Array<Record<string, unknown>>>;
+ /**
+ * Read the rows of `object` that match `filter`.
+ *
+ * `filter` is a FILTER — the `where` HALF of an ObjectQL query, the same
+ * {@link FilterCondition} that `QueryAST.where` carries: implicit equality
+ * `{ field: value }`, explicit operators `{ field: { $in: [...] } }`,
+ * `$and` / `$or` / `$not`. It is NOT the query ENVELOPE
+ * (`{ where, fields, orderBy, limit }`) that `DataEngine.find` and ObjectQL's
+ * own `engine.find` take — the shape this parameter's former name, `query`,
+ * invited. The runtime builds the envelope itself: `buildActionEngineFacade`'s
+ * `find` arm (`packages/runtime/src/action-execution.ts`, `:1183` on
+ * `369da918`) wraps a non-empty filter as `{ where: filter }` and passes an
+ * EMPTY filter (`{}`) through unwrapped — the unfiltered read.
+ *
+ * Two consequences, both silent (#14175):
+ *
+ * - An envelope passed here becomes `{ where: { where: … } }`. No object has
+ * a field named `where`, so the read matches nothing and resolves to `[]`
+ * with no error. A handler that made this mistake ran to completion over
+ * zero rows for as long as it shipped, and its own hand-written test
+ * double — written to the same belief, reading `query.where` — passed
+ * every assertion.
+ * - Because `{}` skips the wrap, an unfiltered call works under EITHER
+ * reading, so a handler mixing one unfiltered read with envelope-shaped
+ * ones looks partially alive rather than uniformly dead.
+ *
+ * What the type buys, exactly: `FilterCondition` refuses a primitive and a
+ * mistyped logical operator (`$and` / `$or` not arrays, `$not` not a
+ * filter). It does NOT refuse `{ where: … }` — its string index signature is
+ * what lets any field name stand as a key, and `where` is a string — so the
+ * envelope mistake still compiles, and this doc comment, not the type, is
+ * the contract of record. Both halves are pinned in `action-params.test.ts`.
+ */
+ find(object: string, filter: FilterCondition): Promise<Array<Record<string, unknown>>>;
 }
 
 /**

.changeset/action-engine-facade-find-filter.md

@@ -0,0 +1,33 @@
+---
+"@objectstack/spec": patch
+---
+
+fix(spec): `ActionEngineFacade.find` declares its second parameter as a FILTER, not an ObjectQL envelope (#14175)
+
+`find(object, query: Record<string, unknown>)` documented nothing, and its
+parameter carried the name of the envelope every other read on the platform
+takes. The runtime (`buildActionEngineFacade`,
+`packages/runtime/src/action-execution.ts`) treats the argument as the bare
+`where` half — wrapping a non-empty one as `{ where: filter }` and passing
+`{}` through unwrapped — so a handler that passed the envelope got
+`{ where: { where: … } }`, matched nothing and returned `[]` with no error,
+while its one unfiltered read kept working. A hand-written test double built
+on the same belief passed every assertion; an application's headline action
+was a silent no-op for its whole life under a green suite.
+
+The member is now `find(object, filter: FilterCondition)` — the published
+`QueryAST.where` type — with a doc comment stating the contract, the runtime's
+wrap, and both limbs (envelope wrapped; empty passed through); the facade
+docblock points at it. The parameter's TYPE now says what the runtime does
+at the one place a handler author reads.
+
+Compile-layer signal only, shipped as `patch` (the #12615 precedent — a
+compile-time narrowing with no change in what parses or runs): no runtime
+behaviour changes, nothing changes in what the facade accepts or returns, and
+the narrowing bites only a primitive or a mistyped `$and` / `$or` / `$not`.
+⚠️ It does NOT refuse `{ where: … }` at compile time — `FilterCondition`'s
+string index signature admits `where` as a field name — so the compile-time
+bar is partial and the doc comment is the contract of record. An
+implementation typed with the old `Record<string, unknown>` still satisfies
+the interface (method parameters are bivariant), so nothing constructing the
+facade changes.

content/docs/ui/actions.mdx

@@ -146,6 +146,21 @@ export async function completeTask(ctx: ActionContext): Promise<void> {
 }
 ```
 
+<Callout type="warn">
+**`ctx.engine.find(object, filter)` takes a filter, not a query.** The second
+argument is the `where` half only — `{ status: 'completed' }`, operators
+(`{ amount: { $gt: 100 } }`), `$and` / `$or` / `$not` — and the runtime wraps
+it in `where` itself. Passing an ObjectQL envelope
+(`{ where: { status: 'completed' } }`) raises no error: it becomes
+`{ where: { where: … } }`, matches no row, and returns `[]`. An empty filter
+(`{}`) is passed through unwrapped, so the one unfiltered read works under
+either reading and a handler can look partially alive. The parameter is typed
+`FilterCondition` (`ActionEngineFacade` in `@objectstack/spec/ui`), which
+refuses a primitive or a mistyped `$and` / `$or` / `$not` but still admits
+`where` as a key — the sentence above is the contract, and a hand-written test
+double must honour it too.
+</Callout>
+
 ```typescript title="objectstack.config.ts"
 export const onEnable = async (ctx: { ql: { registerAction: (...args: unknown[]) => void } }) => {
  ctx.ql.registerAction('todo_task', 'completeTask', completeTask);

packages/spec/src/ui/action-params.test.ts

@@ -5,9 +5,11 @@ import {
  validateActionParams,
  ACTION_PARAM_BUILTIN_KEYS,
  ActionSessionSchema,
+ type ActionEngineFacade,
  type ActionSession,
  type ResolvedActionParam,
 } from './action-params.zod';
+import type { FilterCondition } from '../data/filter.zod';
 import { MIGRATIONS_BY_MAJOR } from '../migrations/registry';
 
 const codes = (issues: ReturnType<typeof validateActionParams>) => issues.map((i) => i.code).sort();
@@ -392,3 +394,77 @@ describe('#5779 — ActionSession `positions` canonical + `roles` deprecated ali
  expect(entry!.acceptanceCriteria).toMatch(/ctx\.session\.positions/);
  });
 });
+
+// ---------------------------------------------------------------------------
+// #14175 — `ActionEngineFacade.find` takes a FILTER, never an ObjectQL envelope
+// ---------------------------------------------------------------------------
+
+type Eq< A, B > = (< T >() => T extends A ? 1 : 2) extends (< T >() => T extends B ? 1 : 2) ? true : false;
+type Assert< T extends true > = T;
+
+// The declared slot, read off the interface — not a retyped copy of it, so a
+// re-widening back to an open record, or a rename of the type behind it, fails
+// HERE rather than in the first consumer to notice.
+type FindFilter = Parameters<ActionEngineFacade['find']>[1];
+
+// The type-level pin (the tsc channel, `tsc -p tsconfig.test.json`). `Eq` is
+// the strict mutual-assignability test, so `Record<string, unknown>` — the type
+// this slot carried before, and the one it must not drift back to — does not
+// satisfy it (measured: the same `Assert` against `Record<string, unknown>` is
+// a TS2344). Exported, as the sibling pins are, so `noUnusedLocals` does not
+// read a type that exists only to be checked as one that is never used.
+export type FindFilterIsFilterCondition = Assert< Eq< FindFilter, FilterCondition > >;
+
+describe('#14175 — ActionEngineFacade.find takes a FILTER (the `where` half), never an ObjectQL envelope', () => {
+ it('types the second parameter as the published `FilterCondition` (the tsc channel)', () => {
+ // The value-level half of `FindFilterIsFilterCondition` above: a literal
+ // annotated with the slot type, so the runtime run exercises the same
+ // declaration the type pin reads.
+ const filter: FindFilter = { position_code: 'qa_lead', active: true };
+ expect(Object.keys(filter)).toEqual(['position_code', 'active']);
+ });
+
+ it('positive control — every shape a handler legitimately passes compiles, the empty filter included', () => {
+ const implicitEquality: FindFilter = { status: 'completed' };
+ const explicitOperator: FindFilter = { position_code: { $in: ['qa_lead', 'qa_manager'] }, active: true };
+ const logical: FindFilter = {
+ $and: [{ active: true }, { $or: [{ tier: 'a' }, { tier: 'b' }] }],
+ $not: { archived: true },
+ };
+ // The runtime passes THIS one through unwrapped — the unfiltered read, and
+ // the one call that kept working in the reporting app under either belief.
+ const unfiltered: FindFilter = {};
+
+ expect([implicitEquality, explicitOperator, logical, unfiltered].every((f) => typeof f === 'object')).toBe(true);
+ });
+
+ it('refuses at compile time what `FilterCondition` refuses — a primitive and a mistyped logical operator', () => {
+ // Each `@ts-expect-error` is itself checked: if the type ever ADMITS one of
+ // these, the directive goes unused and `tsc -p tsconfig.test.json` reds.
+ // @ts-expect-error — a filter is an object; a bare string is not a `where` half.
+ const primitive: FindFilter = 'position_code = qa_lead';
+ // @ts-expect-error — `$and` is `FilterCondition[]`; a string is refused.
+ const andNotArray: FindFilter = { $and: 'active' };
+ // @ts-expect-error — `$or` is `FilterCondition[]`; a bare object is refused.
+ const orNotArray: FindFilter = { $or: { active: true } };
+ // @ts-expect-error — `$not` is a `FilterCondition`; a string is refused.
+ const notNotFilter: FindFilter = { $not: 'archived' };
+
+ expect([primitive, andNotArray, orNotArray, notNotFilter]).toHaveLength(4);
+ });
+
+ it('MEASURED GAP — the exact envelope mistake still compiles; the doc comment, not the type, is the contract', () => {
+ // `FilterCondition`'s string index signature is what lets a field NAME be a
+ // key, and `where` is a string — so the shape that returned `[]` in silence
+ // in the reporting app (`{ where: { position_code: 'qa_lead' } }`) is
+ // admitted by the type, one level down too. This pin RECORDS that
+ // measurement rather than hiding it: a later narrowing that refuses `where`
+ // at the top level turns it red on purpose, so the member's "does NOT
+ // refuse `{ where: … }`" sentence is updated with the type instead of
+ // drifting from it.
+ const envelope: FindFilter = { where: { position_code: 'qa_lead' } };
+ const nested: FindFilter = { where: { where: { position_code: 'qa_lead' } } };
+
+ expect('where' in envelope && 'where' in nested).toBe(true);
+ });
+});

packages/spec/src/ui/action-params.zod.ts

@@ -29,6 +29,7 @@
 import { z } from 'zod';
 
 import { valueSchemaFor } from '../data/field-value.zod';
+import type { FilterCondition } from '../data/filter.zod';
 import type { FieldErrorCode } from '../api/errors.zod';
 import { lazySchema } from '../shared/lazy-schema';
 
@@ -229,12 +230,50 @@ export function validateActionParams(
  * The slim engine facade an action handler's `ctx.engine` exposes. TRUSTED —
  * context-less, RLS/FLS-bypassing by design (#2849); the boundary is enforced
  * at invoke time (`ai.exposed` + the ADR-0066 D4 capability gate), not here.
+ *
+ * `find` is the one member whose argument shape the signature alone never
+ * settled: it takes a bare FILTER — the `where` half of a query — and never
+ * an ObjectQL query envelope; read its doc comment before writing a handler
+ * or a test double against it (#14175).
  */
 export interface ActionEngineFacade {
  insert(object: string, data: Record<string, unknown>): Promise<{ id: string }>;
  update(object: string, id: string, data: Record<string, unknown>): Promise<void>;
  delete(object: string, id: string): Promise<void>;
- find(object: string, query: Record<string, unknown>): Promise<Array<Record<string, unknown>>>;
+ /**
+ * Read the rows of `object` that match `filter`.
+ *
+ * `filter` is a FILTER — the `where` HALF of an ObjectQL query, the same
+ * {@link FilterCondition} that `QueryAST.where` carries: implicit equality
+ * `{ field: value }`, explicit operators `{ field: { $in: [...] } }`,
+ * `$and` / `$or` / `$not`. It is NOT the query ENVELOPE
+ * (`{ where, fields, orderBy, limit }`) that `DataEngine.find` and ObjectQL's
+ * own `engine.find` take — the shape this parameter's former name, `query`,
+ * invited. The runtime builds the envelope itself: `buildActionEngineFacade`'s
+ * `find` arm (`packages/runtime/src/action-execution.ts`, `:1183` on
+ * `369da918`) wraps a non-empty filter as `{ where: filter }` and passes an
+ * EMPTY filter (`{}`) through unwrapped — the unfiltered read.
+ *
+ * Two consequences, both silent (#14175):
+ *
+ * - An envelope passed here becomes `{ where: { where: … } }`. No object has
+ * a field named `where`, so the read matches nothing and resolves to `[]`
+ * with no error. A handler that made this mistake ran to completion over
+ * zero rows for as long as it shipped, and its own hand-written test
+ * double — written to the same belief, reading `query.where` — passed
+ * every assertion.
+ * - Because `{}` skips the wrap, an unfiltered call works under EITHER
+ * reading, so a handler mixing one unfiltered read with envelope-shaped
+ * ones looks partially alive rather than uniformly dead.
+ *
+ * What the type buys, exactly: `FilterCondition` refuses a primitive and a
+ * mistyped logical operator (`$and` / `$or` not arrays, `$not` not a
+ * filter). It does NOT refuse `{ where: … }` — its string index signature is
+ * what lets any field name stand as a key, and `where` is a string — so the
+ * envelope mistake still compiles, and this doc comment, not the type, is
+ * the contract of record. Both halves are pinned in `action-params.test.ts`.
+ */
+ find(object: string, filter: FilterCondition): Promise<Array<Record<string, unknown>>>;
 }
 
 /**