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

* wip: type ActionEngineFacade.find's filter parameter (#14175)

* wip: hoist the type-level pin to an exported alias (#14175)

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: claude[bot]

.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>>>;
 }
 
 /**