Pass the engine facade a bare filter, not a query envelope

src/actions/catalog.handlers.ts

@@ -110,6 +110,41 @@ export function resolveDutyTimezone(): string {
  return DEFAULT_DUTY_TIMEZONE;
 }
 
+// ── The engine facade's query shape ───────────────────────────────────
+//
+// `ctx.engine.find(object, query)` takes a BARE FILTER, not an ObjectQL query
+// envelope. The runtime builds the envelope itself — `buildActionEngineFacade`
+// in @objectstack/runtime 17.2.0, read verbatim from its `dist/index.js`:
+//
+// async find(object, query) {
+// const where = query && Object.keys(query).length ? { where: query } : {};
+// const rows = await ql.find(object, { ...where, context });
+//
+// So every read in this file passes `{ field: value }`, never
+// `{ where: { field: value } }`. Handing it an envelope produces
+// `{ where: { where: { … } } }`; no row has a field called `where`, so the read
+// comes back EMPTY WITH NO ERROR. That is the failure this file shipped with:
+// `duly_catalog_apply` reported a successful run of zero, `duly_catalog_sync`
+// scanned nothing and called every duty unchanged, and `resolveBusinessUnit`
+// anchored no duty at all — silently, because "no position row" is a legitimate
+// day-one state. The ONE unfiltered read survived, because
+// `Object.keys({}).length === 0` skips the wrapping entirely, which is exactly
+// what made the handler look partially alive.
+//
+// `ActionEngineFacade.find` in @objectstack/spec types `query` as a plain
+// record of string to unknown and says nothing about which of the two shapes it
+// is — the runtime's implementation is the only thing that decides, and this
+// app read it the other way. Filed upstream as
+// **objectstack-ai/objectstack#14175** so the shape is DECLARED rather than
+// discovered; until that lands this comment is the contract.
+//
+// ⛔ Do NOT add a tolerant `query.where ?? query` rung — not here, not in a
+// test double. A consumer that accepts both shapes is precisely what let the
+// wrong one ship green: `test/catalog-instantiate.test.ts`'s fake honoured the
+// envelope, so 78 assertions passed against a shape production never produces.
+// The test that can see this is one that dispatches through the REAL route and
+// lets the runtime build its own facade — `test/catalog-engine-facade.test.ts`.
+
 // ── Shapes ──────────────────────────────────────────────────────────────────
 
 export interface CatalogApplyParams extends Record<string, unknown> {
@@ -256,12 +291,21 @@ export function pairKey(catalogItem: unknown, owner: unknown): string {
  * exists on the platform. It is NOT read here — the issue names the
  * assignment-level anchor, and adding a fallback rung is a product decision,
  * reported rather than taken.)
+ *
+ * ⚠️ That tolerance is why this read's query shape matters more than the other
+ * three. The other reads fail into a visibly empty report — zero items, zero
+ * scanned — but this one fails into a state the handler is WRITTEN to accept:
+ * an envelope-shaped filter returned nothing, "nothing" reads as "not yet
+ * modelled", and every duty was created unanchored with no error anywhere. The
+ * rollups that the business unit exists to feed were simply empty. See the
+ * facade-shape note above; the end-to-end coverage is in
+ * `test/catalog-engine-facade.test.ts`.
  */
 async function resolveBusinessUnit(
  engine: ActionEngineFacade,
  userId: string,
 ): Promise<string | undefined> {
- const rows = await engine.find('sys_user_position', { where: { user_id: userId } });
+ const rows = await engine.find('sys_user_position', { user_id: userId });
  for (const row of rows) {
  // A person can hold several positions; take the first anchored one.
  // Unanchored rows (`null`) are legacy/tenant-wide and carry no depth.
@@ -282,13 +326,14 @@ export const applyCatalogHandler: ActionHandler<CatalogApplyParams> = async (ctx
  // stopped asking for; handing it to a new hire on their first day is the
  // opposite of what deactivating it meant.
  const items = await engine.find('duly_catalog_item', {
- where: { position_code: positionCode, active: true },
+ position_code: positionCode,
+ active: true,
  });
  const activeItems = items.filter((item) => item?.active !== false);
 
  // One probe for the whole run, not one per (item, user). The pair set is
  // what makes a second apply create nothing.
- const existing = await engine.find('duly_duty', { where: { owner: { $in: users } } });
+ const existing = await engine.find('duly_duty', { owner: { $in: users } });
  const taken = new Set<string>();
  for (const duty of existing) {
  // Any duty already pointing at this catalog item for this person counts —
@@ -384,15 +429,15 @@ export const syncCatalogHandler: ActionHandler<CatalogSyncParams> = async (ctx)
  // the retired report is made of, so it has to come back from this read.
  const items = await engine.find(
  'duly_catalog_item',
- positionCode ? { where: { position_code: positionCode } } : {},
+ positionCode ? { position_code: positionCode } : {},
  );
  const byId = new Map<string, Record<string, unknown>>();
  for (const item of items) {
  if (positionCode && text(item?.position_code) !== positionCode) continue;
  byId.set(recordId(item), item);
  }
 
- const duties = await engine.find('duly_duty', { where: { source: 'catalog' } });
+ const duties = await engine.find('duly_duty', { source: 'catalog' });
 
  const changes: CatalogSyncChange[] = [];
  const retired: CatalogSyncRetired[] = [];

test/catalog-apply-cadence.test.ts

@@ -23,7 +23,7 @@ import type { CatalogApplyResult } from '../src/actions/catalog.handlers.js';
  * apply path unprotected is half a fix.
  *
  * ── Why a REAL booted engine and not `catalog-instantiate.test.ts`'s fake ──
- * That suite's `FakeEngine` is a Map with a `where` matcher: it runs no
+ * That suite's `FakeEngine` is a Map with a filter matcher: it runs no
  * validation rules and stamps no defaults, so every claim below would pass on
  * it for the wrong reason. Validation and `applyFieldDefaults` are precisely
  * what is under test here, so the handler is dispatched through the app's own
@@ -60,7 +60,7 @@ afterAll(async () => {
  await kernel?.shutdown?.();
 });
 
-// ── The two engine facades ──────────────────────────────────────────────────
+// ── The engine facade ───────────────────────────────────────────────────────
 
 interface Facade {
  insert(object: string, values: AnyRow): Promise<{ id: string }>;
@@ -70,15 +70,29 @@ interface Facade {
 }
 
 /**
- * The facade `applyCatalogHandler` is WRITTEN against: `find(object, query)`
- * takes ObjectQL's own query envelope, `where` and all. It is the convention
- * `catalog-instantiate.test.ts`'s `FakeEngine` honours too, so this is the
- * shape every existing assertion about the handler is made under.
+ * The facade the RUNTIME builds, reproduced line for line —
+ * `buildActionEngineFacade` in @objectstack/runtime 17.2.0:
+ *
+ * async find(object, query) {
+ * const where = query && Object.keys(query).length ? { where: query } : {};
+ * const rows = await ql.find(object, { ...where, context });
+ *
+ * `find(object, query)` therefore takes a BARE FILTER and wraps it here. This
+ * file used to carry TWO facades — this one honouring the handler's own
+ * `where` envelope, and a second reproducing the runtime — with a tripwire
+ * pinning the gap between them (#79). The handler now passes flat filters, so
+ * there is one convention and one facade.
+ *
+ * It is still a double, which is all it can be: the second test below has to
+ * put a row in front of the handler that `duly_catalog_item`'s own rules
+ * refuse, and only a hand-supplied facade can do that. What a double cannot do
+ * is prove the wire shape is right — it encodes the author's belief about it.
+ * That proof lives in `test/catalog-engine-facade.test.ts`, which dispatches
+ * through the real action route and lets the runtime build its own facade.
  *
  * `catalogItems`, when given, replaces the catalog read with rows handed
  * straight to the handler (unfiltered — the handler re-applies its own
- * `active` filter). That is how a row the object's own rules now REFUSE can
- * still be put in front of the handler, which one test below needs.
+ * `active` filter).
  */
 function handlerFacade(catalogItems?: AnyRow[]): Facade {
  return {
@@ -94,28 +108,6 @@ function handlerFacade(catalogItems?: AnyRow[]): Facade {
  },
  find: async (object, query) => {
  if (catalogItems && object === 'duly_catalog_item') return catalogItems.map((r) => ({ ...r }));
- return data.find(object, query);
- },
- };
-}
-
-/**
- * The facade the RUNTIME actually builds — `buildActionEngineFacade` in
- * @objectstack/runtime 17.2.0, reproduced line for line:
- *
- * async find(object, query) {
- * const where = query && Object.keys(query).length ? { where: query } : {};
- * const rows = await ql.find(object, { ...where, context });
- * ...
- *
- * It wraps whatever it is handed in a `where` of its own. Used by exactly one
- * test, the tripwire at the bottom.
- */
-function runtimeFacade(): Facade {
- const base = handlerFacade();
- return {
- ...base,
- find: async (object, query) => {
  const where = query && Object.keys(query).length ? { where: query } : {};
  return data.find(object, { ...where });
  },
@@ -227,41 +219,3 @@ describe('duly_catalog_apply — the cadence it replicates (#65)', () => {
  for (const field of CADENCE_FIELDS) expect(duty?.[field] ?? null, field).toBeNull();
  });
 });
-
-// ───────────────────────────────────────────────────────────────────────────
-// A tripwire on a filed defect — NOT an assertion that this is correct
-// ───────────────────────────────────────────────────────────────────────────
-describe('the handler\'s query shape does not survive the runtime\'s own facade', () => {
- /**
- * Measured while covering the apply path for #65 and filed as #79 — a
- * different defect from the missing validation rule, and not fixed here.
- *
- * `applyCatalogHandler` calls `engine.find('duly_catalog_item', { where: …
- * })`. The runtime's `buildActionEngineFacade` wraps whatever it is given:
- * `ql.find(object, { where: query })`. So through the real dispatcher the
- * handler's own `where` becomes `{ where: { where: … } }`, no row has a
- * field called `where`, and the read comes back EMPTY — with no error. The
- * action then reports `{ created: 0 }` and a successful run.
- *
- * Pinned so the seam is visible rather than folklore. When #79 is fixed
- * this goes red: delete this describe block — do not adjust it — and
- * `handlerFacade` above becomes the only convention in the file.
- */
- it('finds nothing, creates nothing, and reports success', async () => {
- const position = 'apply_runtime_facade';
- await insertItem({ position_code: position, form: 'recurring', frequency: 'weekly' });
-
- // Same item, same params, the only difference being which facade.
- const viaHandlerConvention = await apply(handlerFacade(), {
- position_code: position,
- users: ['u_f1'],
- });
- expect(viaHandlerConvention.catalog_items).toBe(1);
- expect(viaHandlerConvention.created).toBe(1);
-
- const viaRuntime = await apply(runtimeFacade(), { position_code: position, users: ['u_f2'] });
- expect(viaRuntime.catalog_items).toBe(0);
- expect(viaRuntime.created).toBe(0);
- expect(await dutiesOf('u_f2')).toEqual([]);
- });
-});

src/actions/catalog.handlers.ts

@@ -110,6 +110,41 @@ export function resolveDutyTimezone(): string {
  return DEFAULT_DUTY_TIMEZONE;
 }
 
+// ── The engine facade's query shape ───────────────────────────────────
+//
+// `ctx.engine.find(object, query)` takes a BARE FILTER, not an ObjectQL query
+// envelope. The runtime builds the envelope itself — `buildActionEngineFacade`
+// in @objectstack/runtime 17.2.0, read verbatim from its `dist/index.js`:
+//
+// async find(object, query) {
+// const where = query && Object.keys(query).length ? { where: query } : {};
+// const rows = await ql.find(object, { ...where, context });
+//
+// So every read in this file passes `{ field: value }`, never
+// `{ where: { field: value } }`. Handing it an envelope produces
+// `{ where: { where: { … } } }`; no row has a field called `where`, so the read
+// comes back EMPTY WITH NO ERROR. That is the failure this file shipped with:
+// `duly_catalog_apply` reported a successful run of zero, `duly_catalog_sync`
+// scanned nothing and called every duty unchanged, and `resolveBusinessUnit`
+// anchored no duty at all — silently, because "no position row" is a legitimate
+// day-one state. The ONE unfiltered read survived, because
+// `Object.keys({}).length === 0` skips the wrapping entirely, which is exactly
+// what made the handler look partially alive.
+//
+// `ActionEngineFacade.find` in @objectstack/spec types `query` as a plain
+// record of string to unknown and says nothing about which of the two shapes it
+// is — the runtime's implementation is the only thing that decides, and this
+// app read it the other way. Filed upstream as
+// **objectstack-ai/objectstack#14175** so the shape is DECLARED rather than
+// discovered; until that lands this comment is the contract.
+//
+// ⛔ Do NOT add a tolerant `query.where ?? query` rung — not here, not in a
+// test double. A consumer that accepts both shapes is precisely what let the
+// wrong one ship green: `test/catalog-instantiate.test.ts`'s fake honoured the
+// envelope, so 78 assertions passed against a shape production never produces.
+// The test that can see this is one that dispatches through the REAL route and
+// lets the runtime build its own facade — `test/catalog-engine-facade.test.ts`.
+
 // ── Shapes ──────────────────────────────────────────────────────────────────
 
 export interface CatalogApplyParams extends Record<string, unknown> {
@@ -256,12 +291,21 @@ export function pairKey(catalogItem: unknown, owner: unknown): string {
  * exists on the platform. It is NOT read here — the issue names the
  * assignment-level anchor, and adding a fallback rung is a product decision,
  * reported rather than taken.)
+ *
+ * ⚠️ That tolerance is why this read's query shape matters more than the other
+ * three. The other reads fail into a visibly empty report — zero items, zero
+ * scanned — but this one fails into a state the handler is WRITTEN to accept:
+ * an envelope-shaped filter returned nothing, "nothing" reads as "not yet
+ * modelled", and every duty was created unanchored with no error anywhere. The
+ * rollups that the business unit exists to feed were simply empty. See the
+ * facade-shape note above; the end-to-end coverage is in
+ * `test/catalog-engine-facade.test.ts`.
  */
 async function resolveBusinessUnit(
  engine: ActionEngineFacade,
  userId: string,
 ): Promise<string | undefined> {
- const rows = await engine.find('sys_user_position', { where: { user_id: userId } });
+ const rows = await engine.find('sys_user_position', { user_id: userId });
  for (const row of rows) {
  // A person can hold several positions; take the first anchored one.
  // Unanchored rows (`null`) are legacy/tenant-wide and carry no depth.
@@ -282,13 +326,14 @@ export const applyCatalogHandler: ActionHandler<CatalogApplyParams> = async (ctx
  // stopped asking for; handing it to a new hire on their first day is the
  // opposite of what deactivating it meant.
  const items = await engine.find('duly_catalog_item', {
- where: { position_code: positionCode, active: true },
+ position_code: positionCode,
+ active: true,
  });
  const activeItems = items.filter((item) => item?.active !== false);
 
  // One probe for the whole run, not one per (item, user). The pair set is
  // what makes a second apply create nothing.
- const existing = await engine.find('duly_duty', { where: { owner: { $in: users } } });
+ const existing = await engine.find('duly_duty', { owner: { $in: users } });
  const taken = new Set<string>();
  for (const duty of existing) {
  // Any duty already pointing at this catalog item for this person counts —
@@ -384,15 +429,15 @@ export const syncCatalogHandler: ActionHandler<CatalogSyncParams> = async (ctx)
  // the retired report is made of, so it has to come back from this read.
  const items = await engine.find(
  'duly_catalog_item',
- positionCode ? { where: { position_code: positionCode } } : {},
+ positionCode ? { position_code: positionCode } : {},
  );
  const byId = new Map<string, Record<string, unknown>>();
  for (const item of items) {
  if (positionCode && text(item?.position_code) !== positionCode) continue;
  byId.set(recordId(item), item);
  }
 
- const duties = await engine.find('duly_duty', { where: { source: 'catalog' } });
+ const duties = await engine.find('duly_duty', { source: 'catalog' });
 
  const changes: CatalogSyncChange[] = [];
  const retired: CatalogSyncRetired[] = [];

test/catalog-apply-cadence.test.ts

@@ -23,7 +23,7 @@ import type { CatalogApplyResult } from '../src/actions/catalog.handlers.js';
  * apply path unprotected is half a fix.
  *
  * ── Why a REAL booted engine and not `catalog-instantiate.test.ts`'s fake ──
- * That suite's `FakeEngine` is a Map with a `where` matcher: it runs no
+ * That suite's `FakeEngine` is a Map with a filter matcher: it runs no
  * validation rules and stamps no defaults, so every claim below would pass on
  * it for the wrong reason. Validation and `applyFieldDefaults` are precisely
  * what is under test here, so the handler is dispatched through the app's own
@@ -60,7 +60,7 @@ afterAll(async () => {
  await kernel?.shutdown?.();
 });
 
-// ── The two engine facades ──────────────────────────────────────────────────
+// ── The engine facade ───────────────────────────────────────────────────────
 
 interface Facade {
  insert(object: string, values: AnyRow): Promise<{ id: string }>;
@@ -70,15 +70,29 @@ interface Facade {
 }
 
 /**
- * The facade `applyCatalogHandler` is WRITTEN against: `find(object, query)`
- * takes ObjectQL's own query envelope, `where` and all. It is the convention
- * `catalog-instantiate.test.ts`'s `FakeEngine` honours too, so this is the
- * shape every existing assertion about the handler is made under.
+ * The facade the RUNTIME builds, reproduced line for line —
+ * `buildActionEngineFacade` in @objectstack/runtime 17.2.0:
+ *
+ * async find(object, query) {
+ * const where = query && Object.keys(query).length ? { where: query } : {};
+ * const rows = await ql.find(object, { ...where, context });
+ *
+ * `find(object, query)` therefore takes a BARE FILTER and wraps it here. This
+ * file used to carry TWO facades — this one honouring the handler's own
+ * `where` envelope, and a second reproducing the runtime — with a tripwire
+ * pinning the gap between them (#79). The handler now passes flat filters, so
+ * there is one convention and one facade.
+ *
+ * It is still a double, which is all it can be: the second test below has to
+ * put a row in front of the handler that `duly_catalog_item`'s own rules
+ * refuse, and only a hand-supplied facade can do that. What a double cannot do
+ * is prove the wire shape is right — it encodes the author's belief about it.
+ * That proof lives in `test/catalog-engine-facade.test.ts`, which dispatches
+ * through the real action route and lets the runtime build its own facade.
  *
  * `catalogItems`, when given, replaces the catalog read with rows handed
  * straight to the handler (unfiltered — the handler re-applies its own
- * `active` filter). That is how a row the object's own rules now REFUSE can
- * still be put in front of the handler, which one test below needs.
+ * `active` filter).
  */
 function handlerFacade(catalogItems?: AnyRow[]): Facade {
  return {
@@ -94,28 +108,6 @@ function handlerFacade(catalogItems?: AnyRow[]): Facade {
  },
  find: async (object, query) => {
  if (catalogItems && object === 'duly_catalog_item') return catalogItems.map((r) => ({ ...r }));
- return data.find(object, query);
- },
- };
-}
-
-/**
- * The facade the RUNTIME actually builds — `buildActionEngineFacade` in
- * @objectstack/runtime 17.2.0, reproduced line for line:
- *
- * async find(object, query) {
- * const where = query && Object.keys(query).length ? { where: query } : {};
- * const rows = await ql.find(object, { ...where, context });
- * ...
- *
- * It wraps whatever it is handed in a `where` of its own. Used by exactly one
- * test, the tripwire at the bottom.
- */
-function runtimeFacade(): Facade {
- const base = handlerFacade();
- return {
- ...base,
- find: async (object, query) => {
  const where = query && Object.keys(query).length ? { where: query } : {};
  return data.find(object, { ...where });
  },
@@ -227,41 +219,3 @@ describe('duly_catalog_apply — the cadence it replicates (#65)', () => {
  for (const field of CADENCE_FIELDS) expect(duty?.[field] ?? null, field).toBeNull();
  });
 });
-
-// ───────────────────────────────────────────────────────────────────────────
-// A tripwire on a filed defect — NOT an assertion that this is correct
-// ───────────────────────────────────────────────────────────────────────────
-describe('the handler\'s query shape does not survive the runtime\'s own facade', () => {
- /**
- * Measured while covering the apply path for #65 and filed as #79 — a
- * different defect from the missing validation rule, and not fixed here.
- *
- * `applyCatalogHandler` calls `engine.find('duly_catalog_item', { where: …
- * })`. The runtime's `buildActionEngineFacade` wraps whatever it is given:
- * `ql.find(object, { where: query })`. So through the real dispatcher the
- * handler's own `where` becomes `{ where: { where: … } }`, no row has a
- * field called `where`, and the read comes back EMPTY — with no error. The
- * action then reports `{ created: 0 }` and a successful run.
- *
- * Pinned so the seam is visible rather than folklore. When #79 is fixed
- * this goes red: delete this describe block — do not adjust it — and
- * `handlerFacade` above becomes the only convention in the file.
- */
- it('finds nothing, creates nothing, and reports success', async () => {
- const position = 'apply_runtime_facade';
- await insertItem({ position_code: position, form: 'recurring', frequency: 'weekly' });
-
- // Same item, same params, the only difference being which facade.
- const viaHandlerConvention = await apply(handlerFacade(), {
- position_code: position,
- users: ['u_f1'],
- });
- expect(viaHandlerConvention.catalog_items).toBe(1);
- expect(viaHandlerConvention.created).toBe(1);
-
- const viaRuntime = await apply(runtimeFacade(), { position_code: position, users: ['u_f2'] });
- expect(viaRuntime.catalog_items).toBe(0);
- expect(viaRuntime.created).toBe(0);
- expect(await dutiesOf('u_f2')).toEqual([]);
- });
-});

src/actions/catalog.handlers.ts

@@ -110,6 +110,41 @@ export function resolveDutyTimezone(): string {
  return DEFAULT_DUTY_TIMEZONE;
 }
 
+// ── The engine facade's query shape ───────────────────────────────────
+//
+// `ctx.engine.find(object, query)` takes a BARE FILTER, not an ObjectQL query
+// envelope. The runtime builds the envelope itself — `buildActionEngineFacade`
+// in @objectstack/runtime 17.2.0, read verbatim from its `dist/index.js`:
+//
+// async find(object, query) {
+// const where = query && Object.keys(query).length ? { where: query } : {};
+// const rows = await ql.find(object, { ...where, context });
+//
+// So every read in this file passes `{ field: value }`, never
+// `{ where: { field: value } }`. Handing it an envelope produces
+// `{ where: { where: { … } } }`; no row has a field called `where`, so the read
+// comes back EMPTY WITH NO ERROR. That is the failure this file shipped with:
+// `duly_catalog_apply` reported a successful run of zero, `duly_catalog_sync`
+// scanned nothing and called every duty unchanged, and `resolveBusinessUnit`
+// anchored no duty at all — silently, because "no position row" is a legitimate
+// day-one state. The ONE unfiltered read survived, because
+// `Object.keys({}).length === 0` skips the wrapping entirely, which is exactly
+// what made the handler look partially alive.
+//
+// `ActionEngineFacade.find` in @objectstack/spec types `query` as a plain
+// record of string to unknown and says nothing about which of the two shapes it
+// is — the runtime's implementation is the only thing that decides, and this
+// app read it the other way. Filed upstream as
+// **objectstack-ai/objectstack#14175** so the shape is DECLARED rather than
+// discovered; until that lands this comment is the contract.
+//
+// ⛔ Do NOT add a tolerant `query.where ?? query` rung — not here, not in a
+// test double. A consumer that accepts both shapes is precisely what let the
+// wrong one ship green: `test/catalog-instantiate.test.ts`'s fake honoured the
+// envelope, so 78 assertions passed against a shape production never produces.
+// The test that can see this is one that dispatches through the REAL route and
+// lets the runtime build its own facade — `test/catalog-engine-facade.test.ts`.
+
 // ── Shapes ──────────────────────────────────────────────────────────────────
 
 export interface CatalogApplyParams extends Record<string, unknown> {
@@ -256,12 +291,21 @@ export function pairKey(catalogItem: unknown, owner: unknown): string {
  * exists on the platform. It is NOT read here — the issue names the
  * assignment-level anchor, and adding a fallback rung is a product decision,
  * reported rather than taken.)
+ *
+ * ⚠️ That tolerance is why this read's query shape matters more than the other
+ * three. The other reads fail into a visibly empty report — zero items, zero
+ * scanned — but this one fails into a state the handler is WRITTEN to accept:
+ * an envelope-shaped filter returned nothing, "nothing" reads as "not yet
+ * modelled", and every duty was created unanchored with no error anywhere. The
+ * rollups that the business unit exists to feed were simply empty. See the
+ * facade-shape note above; the end-to-end coverage is in
+ * `test/catalog-engine-facade.test.ts`.
  */
 async function resolveBusinessUnit(
  engine: ActionEngineFacade,
  userId: string,
 ): Promise<string | undefined> {
- const rows = await engine.find('sys_user_position', { where: { user_id: userId } });
+ const rows = await engine.find('sys_user_position', { user_id: userId });
  for (const row of rows) {
  // A person can hold several positions; take the first anchored one.
  // Unanchored rows (`null`) are legacy/tenant-wide and carry no depth.
@@ -282,13 +326,14 @@ export const applyCatalogHandler: ActionHandler<CatalogApplyParams> = async (ctx
  // stopped asking for; handing it to a new hire on their first day is the
  // opposite of what deactivating it meant.
  const items = await engine.find('duly_catalog_item', {
- where: { position_code: positionCode, active: true },
+ position_code: positionCode,
+ active: true,
  });
  const activeItems = items.filter((item) => item?.active !== false);
 
  // One probe for the whole run, not one per (item, user). The pair set is
  // what makes a second apply create nothing.
- const existing = await engine.find('duly_duty', { where: { owner: { $in: users } } });
+ const existing = await engine.find('duly_duty', { owner: { $in: users } });
  const taken = new Set<string>();
  for (const duty of existing) {
  // Any duty already pointing at this catalog item for this person counts —
@@ -384,15 +429,15 @@ export const syncCatalogHandler: ActionHandler<CatalogSyncParams> = async (ctx)
  // the retired report is made of, so it has to come back from this read.
  const items = await engine.find(
  'duly_catalog_item',
- positionCode ? { where: { position_code: positionCode } } : {},
+ positionCode ? { position_code: positionCode } : {},
  );
  const byId = new Map<string, Record<string, unknown>>();
  for (const item of items) {
  if (positionCode && text(item?.position_code) !== positionCode) continue;
  byId.set(recordId(item), item);
  }
 
- const duties = await engine.find('duly_duty', { where: { source: 'catalog' } });
+ const duties = await engine.find('duly_duty', { source: 'catalog' });
 
  const changes: CatalogSyncChange[] = [];
  const retired: CatalogSyncRetired[] = [];

test/catalog-apply-cadence.test.ts

@@ -23,7 +23,7 @@ import type { CatalogApplyResult } from '../src/actions/catalog.handlers.js';
  * apply path unprotected is half a fix.
  *
  * ── Why a REAL booted engine and not `catalog-instantiate.test.ts`'s fake ──
- * That suite's `FakeEngine` is a Map with a `where` matcher: it runs no
+ * That suite's `FakeEngine` is a Map with a filter matcher: it runs no
  * validation rules and stamps no defaults, so every claim below would pass on
  * it for the wrong reason. Validation and `applyFieldDefaults` are precisely
  * what is under test here, so the handler is dispatched through the app's own
@@ -60,7 +60,7 @@ afterAll(async () => {
  await kernel?.shutdown?.();
 });
 
-// ── The two engine facades ──────────────────────────────────────────────────
+// ── The engine facade ───────────────────────────────────────────────────────
 
 interface Facade {
  insert(object: string, values: AnyRow): Promise<{ id: string }>;
@@ -70,15 +70,29 @@ interface Facade {
 }
 
 /**
- * The facade `applyCatalogHandler` is WRITTEN against: `find(object, query)`
- * takes ObjectQL's own query envelope, `where` and all. It is the convention
- * `catalog-instantiate.test.ts`'s `FakeEngine` honours too, so this is the
- * shape every existing assertion about the handler is made under.
+ * The facade the RUNTIME builds, reproduced line for line —
+ * `buildActionEngineFacade` in @objectstack/runtime 17.2.0:
+ *
+ * async find(object, query) {
+ * const where = query && Object.keys(query).length ? { where: query } : {};
+ * const rows = await ql.find(object, { ...where, context });
+ *
+ * `find(object, query)` therefore takes a BARE FILTER and wraps it here. This
+ * file used to carry TWO facades — this one honouring the handler's own
+ * `where` envelope, and a second reproducing the runtime — with a tripwire
+ * pinning the gap between them (#79). The handler now passes flat filters, so
+ * there is one convention and one facade.
+ *
+ * It is still a double, which is all it can be: the second test below has to
+ * put a row in front of the handler that `duly_catalog_item`'s own rules
+ * refuse, and only a hand-supplied facade can do that. What a double cannot do
+ * is prove the wire shape is right — it encodes the author's belief about it.
+ * That proof lives in `test/catalog-engine-facade.test.ts`, which dispatches
+ * through the real action route and lets the runtime build its own facade.
  *
  * `catalogItems`, when given, replaces the catalog read with rows handed
  * straight to the handler (unfiltered — the handler re-applies its own
- * `active` filter). That is how a row the object's own rules now REFUSE can
- * still be put in front of the handler, which one test below needs.
+ * `active` filter).
  */
 function handlerFacade(catalogItems?: AnyRow[]): Facade {
  return {
@@ -94,28 +108,6 @@ function handlerFacade(catalogItems?: AnyRow[]): Facade {
  },
  find: async (object, query) => {
  if (catalogItems && object === 'duly_catalog_item') return catalogItems.map((r) => ({ ...r }));
- return data.find(object, query);
- },
- };
-}
-
-/**
- * The facade the RUNTIME actually builds — `buildActionEngineFacade` in
- * @objectstack/runtime 17.2.0, reproduced line for line:
- *
- * async find(object, query) {
- * const where = query && Object.keys(query).length ? { where: query } : {};
- * const rows = await ql.find(object, { ...where, context });
- * ...
- *
- * It wraps whatever it is handed in a `where` of its own. Used by exactly one
- * test, the tripwire at the bottom.
- */
-function runtimeFacade(): Facade {
- const base = handlerFacade();
- return {
- ...base,
- find: async (object, query) => {
  const where = query && Object.keys(query).length ? { where: query } : {};
  return data.find(object, { ...where });
  },
@@ -227,41 +219,3 @@ describe('duly_catalog_apply — the cadence it replicates (#65)', () => {
  for (const field of CADENCE_FIELDS) expect(duty?.[field] ?? null, field).toBeNull();
  });
 });
-
-// ───────────────────────────────────────────────────────────────────────────
-// A tripwire on a filed defect — NOT an assertion that this is correct
-// ───────────────────────────────────────────────────────────────────────────
-describe('the handler\'s query shape does not survive the runtime\'s own facade', () => {
- /**
- * Measured while covering the apply path for #65 and filed as #79 — a
- * different defect from the missing validation rule, and not fixed here.
- *
- * `applyCatalogHandler` calls `engine.find('duly_catalog_item', { where: …
- * })`. The runtime's `buildActionEngineFacade` wraps whatever it is given:
- * `ql.find(object, { where: query })`. So through the real dispatcher the
- * handler's own `where` becomes `{ where: { where: … } }`, no row has a
- * field called `where`, and the read comes back EMPTY — with no error. The
- * action then reports `{ created: 0 }` and a successful run.
- *
- * Pinned so the seam is visible rather than folklore. When #79 is fixed
- * this goes red: delete this describe block — do not adjust it — and
- * `handlerFacade` above becomes the only convention in the file.
- */
- it('finds nothing, creates nothing, and reports success', async () => {
- const position = 'apply_runtime_facade';
- await insertItem({ position_code: position, form: 'recurring', frequency: 'weekly' });
-
- // Same item, same params, the only difference being which facade.
- const viaHandlerConvention = await apply(handlerFacade(), {
- position_code: position,
- users: ['u_f1'],
- });
- expect(viaHandlerConvention.catalog_items).toBe(1);
- expect(viaHandlerConvention.created).toBe(1);
-
- const viaRuntime = await apply(runtimeFacade(), { position_code: position, users: ['u_f2'] });
- expect(viaRuntime.catalog_items).toBe(0);
- expect(viaRuntime.created).toBe(0);
- expect(await dutiesOf('u_f2')).toEqual([]);
- });
-});

src/actions/catalog.handlers.ts

@@ -110,6 +110,41 @@ export function resolveDutyTimezone(): string {
  return DEFAULT_DUTY_TIMEZONE;
 }
 
+// ── The engine facade's query shape ───────────────────────────────────
+//
+// `ctx.engine.find(object, query)` takes a BARE FILTER, not an ObjectQL query
+// envelope. The runtime builds the envelope itself — `buildActionEngineFacade`
+// in @objectstack/runtime 17.2.0, read verbatim from its `dist/index.js`:
+//
+// async find(object, query) {
+// const where = query && Object.keys(query).length ? { where: query } : {};
+// const rows = await ql.find(object, { ...where, context });
+//
+// So every read in this file passes `{ field: value }`, never
+// `{ where: { field: value } }`. Handing it an envelope produces
+// `{ where: { where: { … } } }`; no row has a field called `where`, so the read
+// comes back EMPTY WITH NO ERROR. That is the failure this file shipped with:
+// `duly_catalog_apply` reported a successful run of zero, `duly_catalog_sync`
+// scanned nothing and called every duty unchanged, and `resolveBusinessUnit`
+// anchored no duty at all — silently, because "no position row" is a legitimate
+// day-one state. The ONE unfiltered read survived, because
+// `Object.keys({}).length === 0` skips the wrapping entirely, which is exactly
+// what made the handler look partially alive.
+//
+// `ActionEngineFacade.find` in @objectstack/spec types `query` as a plain
+// record of string to unknown and says nothing about which of the two shapes it
+// is — the runtime's implementation is the only thing that decides, and this
+// app read it the other way. Filed upstream as
+// **objectstack-ai/objectstack#14175** so the shape is DECLARED rather than
+// discovered; until that lands this comment is the contract.
+//
+// ⛔ Do NOT add a tolerant `query.where ?? query` rung — not here, not in a
+// test double. A consumer that accepts both shapes is precisely what let the
+// wrong one ship green: `test/catalog-instantiate.test.ts`'s fake honoured the
+// envelope, so 78 assertions passed against a shape production never produces.
+// The test that can see this is one that dispatches through the REAL route and
+// lets the runtime build its own facade — `test/catalog-engine-facade.test.ts`.
+
 // ── Shapes ──────────────────────────────────────────────────────────────────
 
 export interface CatalogApplyParams extends Record<string, unknown> {
@@ -256,12 +291,21 @@ export function pairKey(catalogItem: unknown, owner: unknown): string {
  * exists on the platform. It is NOT read here — the issue names the
  * assignment-level anchor, and adding a fallback rung is a product decision,
  * reported rather than taken.)
+ *
+ * ⚠️ That tolerance is why this read's query shape matters more than the other
+ * three. The other reads fail into a visibly empty report — zero items, zero
+ * scanned — but this one fails into a state the handler is WRITTEN to accept:
+ * an envelope-shaped filter returned nothing, "nothing" reads as "not yet
+ * modelled", and every duty was created unanchored with no error anywhere. The
+ * rollups that the business unit exists to feed were simply empty. See the
+ * facade-shape note above; the end-to-end coverage is in
+ * `test/catalog-engine-facade.test.ts`.
  */
 async function resolveBusinessUnit(
  engine: ActionEngineFacade,
  userId: string,
 ): Promise<string | undefined> {
- const rows = await engine.find('sys_user_position', { where: { user_id: userId } });
+ const rows = await engine.find('sys_user_position', { user_id: userId });
  for (const row of rows) {
  // A person can hold several positions; take the first anchored one.
  // Unanchored rows (`null`) are legacy/tenant-wide and carry no depth.
@@ -282,13 +326,14 @@ export const applyCatalogHandler: ActionHandler<CatalogApplyParams> = async (ctx
  // stopped asking for; handing it to a new hire on their first day is the
  // opposite of what deactivating it meant.
  const items = await engine.find('duly_catalog_item', {
- where: { position_code: positionCode, active: true },
+ position_code: positionCode,
+ active: true,
  });
  const activeItems = items.filter((item) => item?.active !== false);
 
  // One probe for the whole run, not one per (item, user). The pair set is
  // what makes a second apply create nothing.
- const existing = await engine.find('duly_duty', { where: { owner: { $in: users } } });
+ const existing = await engine.find('duly_duty', { owner: { $in: users } });
  const taken = new Set<string>();
  for (const duty of existing) {
  // Any duty already pointing at this catalog item for this person counts —
@@ -384,15 +429,15 @@ export const syncCatalogHandler: ActionHandler<CatalogSyncParams> = async (ctx)
  // the retired report is made of, so it has to come back from this read.
  const items = await engine.find(
  'duly_catalog_item',
- positionCode ? { where: { position_code: positionCode } } : {},
+ positionCode ? { position_code: positionCode } : {},
  );
  const byId = new Map<string, Record<string, unknown>>();
  for (const item of items) {
  if (positionCode && text(item?.position_code) !== positionCode) continue;
  byId.set(recordId(item), item);
  }
 
- const duties = await engine.find('duly_duty', { where: { source: 'catalog' } });
+ const duties = await engine.find('duly_duty', { source: 'catalog' });
 
  const changes: CatalogSyncChange[] = [];
  const retired: CatalogSyncRetired[] = [];

test/catalog-apply-cadence.test.ts

@@ -23,7 +23,7 @@ import type { CatalogApplyResult } from '../src/actions/catalog.handlers.js';
  * apply path unprotected is half a fix.
  *
  * ── Why a REAL booted engine and not `catalog-instantiate.test.ts`'s fake ──
- * That suite's `FakeEngine` is a Map with a `where` matcher: it runs no
+ * That suite's `FakeEngine` is a Map with a filter matcher: it runs no
  * validation rules and stamps no defaults, so every claim below would pass on
  * it for the wrong reason. Validation and `applyFieldDefaults` are precisely
  * what is under test here, so the handler is dispatched through the app's own
@@ -60,7 +60,7 @@ afterAll(async () => {
  await kernel?.shutdown?.();
 });
 
-// ── The two engine facades ──────────────────────────────────────────────────
+// ── The engine facade ───────────────────────────────────────────────────────
 
 interface Facade {
  insert(object: string, values: AnyRow): Promise<{ id: string }>;
@@ -70,15 +70,29 @@ interface Facade {
 }
 
 /**
- * The facade `applyCatalogHandler` is WRITTEN against: `find(object, query)`
- * takes ObjectQL's own query envelope, `where` and all. It is the convention
- * `catalog-instantiate.test.ts`'s `FakeEngine` honours too, so this is the
- * shape every existing assertion about the handler is made under.
+ * The facade the RUNTIME builds, reproduced line for line —
+ * `buildActionEngineFacade` in @objectstack/runtime 17.2.0:
+ *
+ * async find(object, query) {
+ * const where = query && Object.keys(query).length ? { where: query } : {};
+ * const rows = await ql.find(object, { ...where, context });
+ *
+ * `find(object, query)` therefore takes a BARE FILTER and wraps it here. This
+ * file used to carry TWO facades — this one honouring the handler's own
+ * `where` envelope, and a second reproducing the runtime — with a tripwire
+ * pinning the gap between them (#79). The handler now passes flat filters, so
+ * there is one convention and one facade.
+ *
+ * It is still a double, which is all it can be: the second test below has to
+ * put a row in front of the handler that `duly_catalog_item`'s own rules
+ * refuse, and only a hand-supplied facade can do that. What a double cannot do
+ * is prove the wire shape is right — it encodes the author's belief about it.
+ * That proof lives in `test/catalog-engine-facade.test.ts`, which dispatches
+ * through the real action route and lets the runtime build its own facade.
  *
  * `catalogItems`, when given, replaces the catalog read with rows handed
  * straight to the handler (unfiltered — the handler re-applies its own
- * `active` filter). That is how a row the object's own rules now REFUSE can
- * still be put in front of the handler, which one test below needs.
+ * `active` filter).
  */
 function handlerFacade(catalogItems?: AnyRow[]): Facade {
  return {
@@ -94,28 +108,6 @@ function handlerFacade(catalogItems?: AnyRow[]): Facade {
  },
  find: async (object, query) => {
  if (catalogItems && object === 'duly_catalog_item') return catalogItems.map((r) => ({ ...r }));
- return data.find(object, query);
- },
- };
-}
-
-/**
- * The facade the RUNTIME actually builds — `buildActionEngineFacade` in
- * @objectstack/runtime 17.2.0, reproduced line for line:
- *
- * async find(object, query) {
- * const where = query && Object.keys(query).length ? { where: query } : {};
- * const rows = await ql.find(object, { ...where, context });
- * ...
- *
- * It wraps whatever it is handed in a `where` of its own. Used by exactly one
- * test, the tripwire at the bottom.
- */
-function runtimeFacade(): Facade {
- const base = handlerFacade();
- return {
- ...base,
- find: async (object, query) => {
  const where = query && Object.keys(query).length ? { where: query } : {};
  return data.find(object, { ...where });
  },
@@ -227,41 +219,3 @@ describe('duly_catalog_apply — the cadence it replicates (#65)', () => {
  for (const field of CADENCE_FIELDS) expect(duty?.[field] ?? null, field).toBeNull();
  });
 });
-
-// ───────────────────────────────────────────────────────────────────────────
-// A tripwire on a filed defect — NOT an assertion that this is correct
-// ───────────────────────────────────────────────────────────────────────────
-describe('the handler\'s query shape does not survive the runtime\'s own facade', () => {
- /**
- * Measured while covering the apply path for #65 and filed as #79 — a
- * different defect from the missing validation rule, and not fixed here.
- *
- * `applyCatalogHandler` calls `engine.find('duly_catalog_item', { where: …
- * })`. The runtime's `buildActionEngineFacade` wraps whatever it is given:
- * `ql.find(object, { where: query })`. So through the real dispatcher the
- * handler's own `where` becomes `{ where: { where: … } }`, no row has a
- * field called `where`, and the read comes back EMPTY — with no error. The
- * action then reports `{ created: 0 }` and a successful run.
- *
- * Pinned so the seam is visible rather than folklore. When #79 is fixed
- * this goes red: delete this describe block — do not adjust it — and
- * `handlerFacade` above becomes the only convention in the file.
- */
- it('finds nothing, creates nothing, and reports success', async () => {
- const position = 'apply_runtime_facade';
- await insertItem({ position_code: position, form: 'recurring', frequency: 'weekly' });
-
- // Same item, same params, the only difference being which facade.
- const viaHandlerConvention = await apply(handlerFacade(), {
- position_code: position,
- users: ['u_f1'],
- });
- expect(viaHandlerConvention.catalog_items).toBe(1);
- expect(viaHandlerConvention.created).toBe(1);
-
- const viaRuntime = await apply(runtimeFacade(), { position_code: position, users: ['u_f2'] });
- expect(viaRuntime.catalog_items).toBe(0);
- expect(viaRuntime.created).toBe(0);
- expect(await dutiesOf('u_f2')).toEqual([]);
- });
-});

src/actions/catalog.handlers.ts

@@ -110,6 +110,41 @@ export function resolveDutyTimezone(): string {
  return DEFAULT_DUTY_TIMEZONE;
 }
 
+// ── The engine facade's query shape ───────────────────────────────────
+//
+// `ctx.engine.find(object, query)` takes a BARE FILTER, not an ObjectQL query
+// envelope. The runtime builds the envelope itself — `buildActionEngineFacade`
+// in @objectstack/runtime 17.2.0, read verbatim from its `dist/index.js`:
+//
+// async find(object, query) {
+// const where = query && Object.keys(query).length ? { where: query } : {};
+// const rows = await ql.find(object, { ...where, context });
+//
+// So every read in this file passes `{ field: value }`, never
+// `{ where: { field: value } }`. Handing it an envelope produces
+// `{ where: { where: { … } } }`; no row has a field called `where`, so the read
+// comes back EMPTY WITH NO ERROR. That is the failure this file shipped with:
+// `duly_catalog_apply` reported a successful run of zero, `duly_catalog_sync`
+// scanned nothing and called every duty unchanged, and `resolveBusinessUnit`
+// anchored no duty at all — silently, because "no position row" is a legitimate
+// day-one state. The ONE unfiltered read survived, because
+// `Object.keys({}).length === 0` skips the wrapping entirely, which is exactly
+// what made the handler look partially alive.
+//
+// `ActionEngineFacade.find` in @objectstack/spec types `query` as a plain
+// record of string to unknown and says nothing about which of the two shapes it
+// is — the runtime's implementation is the only thing that decides, and this
+// app read it the other way. Filed upstream as
+// **objectstack-ai/objectstack#14175** so the shape is DECLARED rather than
+// discovered; until that lands this comment is the contract.
+//
+// ⛔ Do NOT add a tolerant `query.where ?? query` rung — not here, not in a
+// test double. A consumer that accepts both shapes is precisely what let the
+// wrong one ship green: `test/catalog-instantiate.test.ts`'s fake honoured the
+// envelope, so 78 assertions passed against a shape production never produces.
+// The test that can see this is one that dispatches through the REAL route and
+// lets the runtime build its own facade — `test/catalog-engine-facade.test.ts`.
+
 // ── Shapes ──────────────────────────────────────────────────────────────────
 
 export interface CatalogApplyParams extends Record<string, unknown> {
@@ -256,12 +291,21 @@ export function pairKey(catalogItem: unknown, owner: unknown): string {
  * exists on the platform. It is NOT read here — the issue names the
  * assignment-level anchor, and adding a fallback rung is a product decision,
  * reported rather than taken.)
+ *
+ * ⚠️ That tolerance is why this read's query shape matters more than the other
+ * three. The other reads fail into a visibly empty report — zero items, zero
+ * scanned — but this one fails into a state the handler is WRITTEN to accept:
+ * an envelope-shaped filter returned nothing, "nothing" reads as "not yet
+ * modelled", and every duty was created unanchored with no error anywhere. The
+ * rollups that the business unit exists to feed were simply empty. See the
+ * facade-shape note above; the end-to-end coverage is in
+ * `test/catalog-engine-facade.test.ts`.
  */
 async function resolveBusinessUnit(
  engine: ActionEngineFacade,
  userId: string,
 ): Promise<string | undefined> {
- const rows = await engine.find('sys_user_position', { where: { user_id: userId } });
+ const rows = await engine.find('sys_user_position', { user_id: userId });
  for (const row of rows) {
  // A person can hold several positions; take the first anchored one.
  // Unanchored rows (`null`) are legacy/tenant-wide and carry no depth.
@@ -282,13 +326,14 @@ export const applyCatalogHandler: ActionHandler<CatalogApplyParams> = async (ctx
  // stopped asking for; handing it to a new hire on their first day is the
  // opposite of what deactivating it meant.
  const items = await engine.find('duly_catalog_item', {
- where: { position_code: positionCode, active: true },
+ position_code: positionCode,
+ active: true,
  });
  const activeItems = items.filter((item) => item?.active !== false);
 
  // One probe for the whole run, not one per (item, user). The pair set is
  // what makes a second apply create nothing.
- const existing = await engine.find('duly_duty', { where: { owner: { $in: users } } });
+ const existing = await engine.find('duly_duty', { owner: { $in: users } });
  const taken = new Set<string>();
  for (const duty of existing) {
  // Any duty already pointing at this catalog item for this person counts —
@@ -384,15 +429,15 @@ export const syncCatalogHandler: ActionHandler<CatalogSyncParams> = async (ctx)
  // the retired report is made of, so it has to come back from this read.
  const items = await engine.find(
  'duly_catalog_item',
- positionCode ? { where: { position_code: positionCode } } : {},
+ positionCode ? { position_code: positionCode } : {},
  );
  const byId = new Map<string, Record<string, unknown>>();
  for (const item of items) {
  if (positionCode && text(item?.position_code) !== positionCode) continue;
  byId.set(recordId(item), item);
  }
 
- const duties = await engine.find('duly_duty', { where: { source: 'catalog' } });
+ const duties = await engine.find('duly_duty', { source: 'catalog' });
 
  const changes: CatalogSyncChange[] = [];
  const retired: CatalogSyncRetired[] = [];

test/catalog-apply-cadence.test.ts

@@ -23,7 +23,7 @@ import type { CatalogApplyResult } from '../src/actions/catalog.handlers.js';
  * apply path unprotected is half a fix.
  *
  * ── Why a REAL booted engine and not `catalog-instantiate.test.ts`'s fake ──
- * That suite's `FakeEngine` is a Map with a `where` matcher: it runs no
+ * That suite's `FakeEngine` is a Map with a filter matcher: it runs no
  * validation rules and stamps no defaults, so every claim below would pass on
  * it for the wrong reason. Validation and `applyFieldDefaults` are precisely
  * what is under test here, so the handler is dispatched through the app's own
@@ -60,7 +60,7 @@ afterAll(async () => {
  await kernel?.shutdown?.();
 });
 
-// ── The two engine facades ──────────────────────────────────────────────────
+// ── The engine facade ───────────────────────────────────────────────────────
 
 interface Facade {
  insert(object: string, values: AnyRow): Promise<{ id: string }>;
@@ -70,15 +70,29 @@ interface Facade {
 }
 
 /**
- * The facade `applyCatalogHandler` is WRITTEN against: `find(object, query)`
- * takes ObjectQL's own query envelope, `where` and all. It is the convention
- * `catalog-instantiate.test.ts`'s `FakeEngine` honours too, so this is the
- * shape every existing assertion about the handler is made under.
+ * The facade the RUNTIME builds, reproduced line for line —
+ * `buildActionEngineFacade` in @objectstack/runtime 17.2.0:
+ *
+ * async find(object, query) {
+ * const where = query && Object.keys(query).length ? { where: query } : {};
+ * const rows = await ql.find(object, { ...where, context });
+ *
+ * `find(object, query)` therefore takes a BARE FILTER and wraps it here. This
+ * file used to carry TWO facades — this one honouring the handler's own
+ * `where` envelope, and a second reproducing the runtime — with a tripwire
+ * pinning the gap between them (#79). The handler now passes flat filters, so
+ * there is one convention and one facade.
+ *
+ * It is still a double, which is all it can be: the second test below has to
+ * put a row in front of the handler that `duly_catalog_item`'s own rules
+ * refuse, and only a hand-supplied facade can do that. What a double cannot do
+ * is prove the wire shape is right — it encodes the author's belief about it.
+ * That proof lives in `test/catalog-engine-facade.test.ts`, which dispatches
+ * through the real action route and lets the runtime build its own facade.
  *
  * `catalogItems`, when given, replaces the catalog read with rows handed
  * straight to the handler (unfiltered — the handler re-applies its own
- * `active` filter). That is how a row the object's own rules now REFUSE can
- * still be put in front of the handler, which one test below needs.
+ * `active` filter).
  */
 function handlerFacade(catalogItems?: AnyRow[]): Facade {
  return {
@@ -94,28 +108,6 @@ function handlerFacade(catalogItems?: AnyRow[]): Facade {
  },
  find: async (object, query) => {
  if (catalogItems && object === 'duly_catalog_item') return catalogItems.map((r) => ({ ...r }));
- return data.find(object, query);
- },
- };
-}
-
-/**
- * The facade the RUNTIME actually builds — `buildActionEngineFacade` in
- * @objectstack/runtime 17.2.0, reproduced line for line:
- *
- * async find(object, query) {
- * const where = query && Object.keys(query).length ? { where: query } : {};
- * const rows = await ql.find(object, { ...where, context });
- * ...
- *
- * It wraps whatever it is handed in a `where` of its own. Used by exactly one
- * test, the tripwire at the bottom.
- */
-function runtimeFacade(): Facade {
- const base = handlerFacade();
- return {
- ...base,
- find: async (object, query) => {
  const where = query && Object.keys(query).length ? { where: query } : {};
  return data.find(object, { ...where });
  },
@@ -227,41 +219,3 @@ describe('duly_catalog_apply — the cadence it replicates (#65)', () => {
  for (const field of CADENCE_FIELDS) expect(duty?.[field] ?? null, field).toBeNull();
  });
 });
-
-// ───────────────────────────────────────────────────────────────────────────
-// A tripwire on a filed defect — NOT an assertion that this is correct
-// ───────────────────────────────────────────────────────────────────────────
-describe('the handler\'s query shape does not survive the runtime\'s own facade', () => {
- /**
- * Measured while covering the apply path for #65 and filed as #79 — a
- * different defect from the missing validation rule, and not fixed here.
- *
- * `applyCatalogHandler` calls `engine.find('duly_catalog_item', { where: …
- * })`. The runtime's `buildActionEngineFacade` wraps whatever it is given:
- * `ql.find(object, { where: query })`. So through the real dispatcher the
- * handler's own `where` becomes `{ where: { where: … } }`, no row has a
- * field called `where`, and the read comes back EMPTY — with no error. The
- * action then reports `{ created: 0 }` and a successful run.
- *
- * Pinned so the seam is visible rather than folklore. When #79 is fixed
- * this goes red: delete this describe block — do not adjust it — and
- * `handlerFacade` above becomes the only convention in the file.
- */
- it('finds nothing, creates nothing, and reports success', async () => {
- const position = 'apply_runtime_facade';
- await insertItem({ position_code: position, form: 'recurring', frequency: 'weekly' });
-
- // Same item, same params, the only difference being which facade.
- const viaHandlerConvention = await apply(handlerFacade(), {
- position_code: position,
- users: ['u_f1'],
- });
- expect(viaHandlerConvention.catalog_items).toBe(1);
- expect(viaHandlerConvention.created).toBe(1);
-
- const viaRuntime = await apply(runtimeFacade(), { position_code: position, users: ['u_f2'] });
- expect(viaRuntime.catalog_items).toBe(0);
- expect(viaRuntime.created).toBe(0);
- expect(await dutiesOf('u_f2')).toEqual([]);
- });
-});

src/actions/catalog.handlers.ts

@@ -110,6 +110,41 @@ export function resolveDutyTimezone(): string {
  return DEFAULT_DUTY_TIMEZONE;
 }
 
+// ── The engine facade's query shape ───────────────────────────────────
+//
+// `ctx.engine.find(object, query)` takes a BARE FILTER, not an ObjectQL query
+// envelope. The runtime builds the envelope itself — `buildActionEngineFacade`
+// in @objectstack/runtime 17.2.0, read verbatim from its `dist/index.js`:
+//
+// async find(object, query) {
+// const where = query && Object.keys(query).length ? { where: query } : {};
+// const rows = await ql.find(object, { ...where, context });
+//
+// So every read in this file passes `{ field: value }`, never
+// `{ where: { field: value } }`. Handing it an envelope produces
+// `{ where: { where: { … } } }`; no row has a field called `where`, so the read
+// comes back EMPTY WITH NO ERROR. That is the failure this file shipped with:
+// `duly_catalog_apply` reported a successful run of zero, `duly_catalog_sync`
+// scanned nothing and called every duty unchanged, and `resolveBusinessUnit`
+// anchored no duty at all — silently, because "no position row" is a legitimate
+// day-one state. The ONE unfiltered read survived, because
+// `Object.keys({}).length === 0` skips the wrapping entirely, which is exactly
+// what made the handler look partially alive.
+//
+// `ActionEngineFacade.find` in @objectstack/spec types `query` as a plain
+// record of string to unknown and says nothing about which of the two shapes it
+// is — the runtime's implementation is the only thing that decides, and this
+// app read it the other way. Filed upstream as
+// **objectstack-ai/objectstack#14175** so the shape is DECLARED rather than
+// discovered; until that lands this comment is the contract.
+//
+// ⛔ Do NOT add a tolerant `query.where ?? query` rung — not here, not in a
+// test double. A consumer that accepts both shapes is precisely what let the
+// wrong one ship green: `test/catalog-instantiate.test.ts`'s fake honoured the
+// envelope, so 78 assertions passed against a shape production never produces.
+// The test that can see this is one that dispatches through the REAL route and
+// lets the runtime build its own facade — `test/catalog-engine-facade.test.ts`.
+
 // ── Shapes ──────────────────────────────────────────────────────────────────
 
 export interface CatalogApplyParams extends Record<string, unknown> {
@@ -256,12 +291,21 @@ export function pairKey(catalogItem: unknown, owner: unknown): string {
  * exists on the platform. It is NOT read here — the issue names the
  * assignment-level anchor, and adding a fallback rung is a product decision,
  * reported rather than taken.)
+ *
+ * ⚠️ That tolerance is why this read's query shape matters more than the other
+ * three. The other reads fail into a visibly empty report — zero items, zero
+ * scanned — but this one fails into a state the handler is WRITTEN to accept:
+ * an envelope-shaped filter returned nothing, "nothing" reads as "not yet
+ * modelled", and every duty was created unanchored with no error anywhere. The
+ * rollups that the business unit exists to feed were simply empty. See the
+ * facade-shape note above; the end-to-end coverage is in
+ * `test/catalog-engine-facade.test.ts`.
  */
 async function resolveBusinessUnit(
  engine: ActionEngineFacade,
  userId: string,
 ): Promise<string | undefined> {
- const rows = await engine.find('sys_user_position', { where: { user_id: userId } });
+ const rows = await engine.find('sys_user_position', { user_id: userId });
  for (const row of rows) {
  // A person can hold several positions; take the first anchored one.
  // Unanchored rows (`null`) are legacy/tenant-wide and carry no depth.
@@ -282,13 +326,14 @@ export const applyCatalogHandler: ActionHandler<CatalogApplyParams> = async (ctx
  // stopped asking for; handing it to a new hire on their first day is the
  // opposite of what deactivating it meant.
  const items = await engine.find('duly_catalog_item', {
- where: { position_code: positionCode, active: true },
+ position_code: positionCode,
+ active: true,
  });
  const activeItems = items.filter((item) => item?.active !== false);
 
  // One probe for the whole run, not one per (item, user). The pair set is
  // what makes a second apply create nothing.
- const existing = await engine.find('duly_duty', { where: { owner: { $in: users } } });
+ const existing = await engine.find('duly_duty', { owner: { $in: users } });
  const taken = new Set<string>();
  for (const duty of existing) {
  // Any duty already pointing at this catalog item for this person counts —
@@ -384,15 +429,15 @@ export const syncCatalogHandler: ActionHandler<CatalogSyncParams> = async (ctx)
  // the retired report is made of, so it has to come back from this read.
  const items = await engine.find(
  'duly_catalog_item',
- positionCode ? { where: { position_code: positionCode } } : {},
+ positionCode ? { position_code: positionCode } : {},
  );
  const byId = new Map<string, Record<string, unknown>>();
  for (const item of items) {
  if (positionCode && text(item?.position_code) !== positionCode) continue;
  byId.set(recordId(item), item);
  }
 
- const duties = await engine.find('duly_duty', { where: { source: 'catalog' } });
+ const duties = await engine.find('duly_duty', { source: 'catalog' });
 
  const changes: CatalogSyncChange[] = [];
  const retired: CatalogSyncRetired[] = [];

test/catalog-apply-cadence.test.ts

@@ -23,7 +23,7 @@ import type { CatalogApplyResult } from '../src/actions/catalog.handlers.js';
  * apply path unprotected is half a fix.
  *
  * ── Why a REAL booted engine and not `catalog-instantiate.test.ts`'s fake ──
- * That suite's `FakeEngine` is a Map with a `where` matcher: it runs no
+ * That suite's `FakeEngine` is a Map with a filter matcher: it runs no
  * validation rules and stamps no defaults, so every claim below would pass on
  * it for the wrong reason. Validation and `applyFieldDefaults` are precisely
  * what is under test here, so the handler is dispatched through the app's own
@@ -60,7 +60,7 @@ afterAll(async () => {
  await kernel?.shutdown?.();
 });
 
-// ── The two engine facades ──────────────────────────────────────────────────
+// ── The engine facade ───────────────────────────────────────────────────────
 
 interface Facade {
  insert(object: string, values: AnyRow): Promise<{ id: string }>;
@@ -70,15 +70,29 @@ interface Facade {
 }
 
 /**
- * The facade `applyCatalogHandler` is WRITTEN against: `find(object, query)`
- * takes ObjectQL's own query envelope, `where` and all. It is the convention
- * `catalog-instantiate.test.ts`'s `FakeEngine` honours too, so this is the
- * shape every existing assertion about the handler is made under.
+ * The facade the RUNTIME builds, reproduced line for line —
+ * `buildActionEngineFacade` in @objectstack/runtime 17.2.0:
+ *
+ * async find(object, query) {
+ * const where = query && Object.keys(query).length ? { where: query } : {};
+ * const rows = await ql.find(object, { ...where, context });
+ *
+ * `find(object, query)` therefore takes a BARE FILTER and wraps it here. This
+ * file used to carry TWO facades — this one honouring the handler's own
+ * `where` envelope, and a second reproducing the runtime — with a tripwire
+ * pinning the gap between them (#79). The handler now passes flat filters, so
+ * there is one convention and one facade.
+ *
+ * It is still a double, which is all it can be: the second test below has to
+ * put a row in front of the handler that `duly_catalog_item`'s own rules
+ * refuse, and only a hand-supplied facade can do that. What a double cannot do
+ * is prove the wire shape is right — it encodes the author's belief about it.
+ * That proof lives in `test/catalog-engine-facade.test.ts`, which dispatches
+ * through the real action route and lets the runtime build its own facade.
  *
  * `catalogItems`, when given, replaces the catalog read with rows handed
  * straight to the handler (unfiltered — the handler re-applies its own
- * `active` filter). That is how a row the object's own rules now REFUSE can
- * still be put in front of the handler, which one test below needs.
+ * `active` filter).
  */
 function handlerFacade(catalogItems?: AnyRow[]): Facade {
  return {
@@ -94,28 +108,6 @@ function handlerFacade(catalogItems?: AnyRow[]): Facade {
  },
  find: async (object, query) => {
  if (catalogItems && object === 'duly_catalog_item') return catalogItems.map((r) => ({ ...r }));
- return data.find(object, query);
- },
- };
-}
-
-/**
- * The facade the RUNTIME actually builds — `buildActionEngineFacade` in
- * @objectstack/runtime 17.2.0, reproduced line for line:
- *
- * async find(object, query) {
- * const where = query && Object.keys(query).length ? { where: query } : {};
- * const rows = await ql.find(object, { ...where, context });
- * ...
- *
- * It wraps whatever it is handed in a `where` of its own. Used by exactly one
- * test, the tripwire at the bottom.
- */
-function runtimeFacade(): Facade {
- const base = handlerFacade();
- return {
- ...base,
- find: async (object, query) => {
  const where = query && Object.keys(query).length ? { where: query } : {};
  return data.find(object, { ...where });
  },
@@ -227,41 +219,3 @@ describe('duly_catalog_apply — the cadence it replicates (#65)', () => {
  for (const field of CADENCE_FIELDS) expect(duty?.[field] ?? null, field).toBeNull();
  });
 });
-
-// ───────────────────────────────────────────────────────────────────────────
-// A tripwire on a filed defect — NOT an assertion that this is correct
-// ───────────────────────────────────────────────────────────────────────────
-describe('the handler\'s query shape does not survive the runtime\'s own facade', () => {
- /**
- * Measured while covering the apply path for #65 and filed as #79 — a
- * different defect from the missing validation rule, and not fixed here.
- *
- * `applyCatalogHandler` calls `engine.find('duly_catalog_item', { where: …
- * })`. The runtime's `buildActionEngineFacade` wraps whatever it is given:
- * `ql.find(object, { where: query })`. So through the real dispatcher the
- * handler's own `where` becomes `{ where: { where: … } }`, no row has a
- * field called `where`, and the read comes back EMPTY — with no error. The
- * action then reports `{ created: 0 }` and a successful run.
- *
- * Pinned so the seam is visible rather than folklore. When #79 is fixed
- * this goes red: delete this describe block — do not adjust it — and
- * `handlerFacade` above becomes the only convention in the file.
- */
- it('finds nothing, creates nothing, and reports success', async () => {
- const position = 'apply_runtime_facade';
- await insertItem({ position_code: position, form: 'recurring', frequency: 'weekly' });
-
- // Same item, same params, the only difference being which facade.
- const viaHandlerConvention = await apply(handlerFacade(), {
- position_code: position,
- users: ['u_f1'],
- });
- expect(viaHandlerConvention.catalog_items).toBe(1);
- expect(viaHandlerConvention.created).toBe(1);
-
- const viaRuntime = await apply(runtimeFacade(), { position_code: position, users: ['u_f2'] });
- expect(viaRuntime.catalog_items).toBe(0);
- expect(viaRuntime.created).toBe(0);
- expect(await dutiesOf('u_f2')).toEqual([]);
- });
-});

src/actions/catalog.handlers.ts

@@ -110,6 +110,41 @@ export function resolveDutyTimezone(): string {
  return DEFAULT_DUTY_TIMEZONE;
 }
 
+// ── The engine facade's query shape ───────────────────────────────────
+//
+// `ctx.engine.find(object, query)` takes a BARE FILTER, not an ObjectQL query
+// envelope. The runtime builds the envelope itself — `buildActionEngineFacade`
+// in @objectstack/runtime 17.2.0, read verbatim from its `dist/index.js`:
+//
+// async find(object, query) {
+// const where = query && Object.keys(query).length ? { where: query } : {};
+// const rows = await ql.find(object, { ...where, context });
+//
+// So every read in this file passes `{ field: value }`, never
+// `{ where: { field: value } }`. Handing it an envelope produces
+// `{ where: { where: { … } } }`; no row has a field called `where`, so the read
+// comes back EMPTY WITH NO ERROR. That is the failure this file shipped with:
+// `duly_catalog_apply` reported a successful run of zero, `duly_catalog_sync`
+// scanned nothing and called every duty unchanged, and `resolveBusinessUnit`
+// anchored no duty at all — silently, because "no position row" is a legitimate
+// day-one state. The ONE unfiltered read survived, because
+// `Object.keys({}).length === 0` skips the wrapping entirely, which is exactly
+// what made the handler look partially alive.
+//
+// `ActionEngineFacade.find` in @objectstack/spec types `query` as a plain
+// record of string to unknown and says nothing about which of the two shapes it
+// is — the runtime's implementation is the only thing that decides, and this
+// app read it the other way. Filed upstream as
+// **objectstack-ai/objectstack#14175** so the shape is DECLARED rather than
+// discovered; until that lands this comment is the contract.
+//
+// ⛔ Do NOT add a tolerant `query.where ?? query` rung — not here, not in a
+// test double. A consumer that accepts both shapes is precisely what let the
+// wrong one ship green: `test/catalog-instantiate.test.ts`'s fake honoured the
+// envelope, so 78 assertions passed against a shape production never produces.
+// The test that can see this is one that dispatches through the REAL route and
+// lets the runtime build its own facade — `test/catalog-engine-facade.test.ts`.
+
 // ── Shapes ──────────────────────────────────────────────────────────────────
 
 export interface CatalogApplyParams extends Record<string, unknown> {
@@ -256,12 +291,21 @@ export function pairKey(catalogItem: unknown, owner: unknown): string {
  * exists on the platform. It is NOT read here — the issue names the
  * assignment-level anchor, and adding a fallback rung is a product decision,
  * reported rather than taken.)
+ *
+ * ⚠️ That tolerance is why this read's query shape matters more than the other
+ * three. The other reads fail into a visibly empty report — zero items, zero
+ * scanned — but this one fails into a state the handler is WRITTEN to accept:
+ * an envelope-shaped filter returned nothing, "nothing" reads as "not yet
+ * modelled", and every duty was created unanchored with no error anywhere. The
+ * rollups that the business unit exists to feed were simply empty. See the
+ * facade-shape note above; the end-to-end coverage is in
+ * `test/catalog-engine-facade.test.ts`.
  */
 async function resolveBusinessUnit(
  engine: ActionEngineFacade,
  userId: string,
 ): Promise<string | undefined> {
- const rows = await engine.find('sys_user_position', { where: { user_id: userId } });
+ const rows = await engine.find('sys_user_position', { user_id: userId });
  for (const row of rows) {
  // A person can hold several positions; take the first anchored one.
  // Unanchored rows (`null`) are legacy/tenant-wide and carry no depth.
@@ -282,13 +326,14 @@ export const applyCatalogHandler: ActionHandler<CatalogApplyParams> = async (ctx
  // stopped asking for; handing it to a new hire on their first day is the
  // opposite of what deactivating it meant.
  const items = await engine.find('duly_catalog_item', {
- where: { position_code: positionCode, active: true },
+ position_code: positionCode,
+ active: true,
  });
  const activeItems = items.filter((item) => item?.active !== false);
 
  // One probe for the whole run, not one per (item, user). The pair set is
  // what makes a second apply create nothing.
- const existing = await engine.find('duly_duty', { where: { owner: { $in: users } } });
+ const existing = await engine.find('duly_duty', { owner: { $in: users } });
  const taken = new Set<string>();
  for (const duty of existing) {
  // Any duty already pointing at this catalog item for this person counts —
@@ -384,15 +429,15 @@ export const syncCatalogHandler: ActionHandler<CatalogSyncParams> = async (ctx)
  // the retired report is made of, so it has to come back from this read.
  const items = await engine.find(
  'duly_catalog_item',
- positionCode ? { where: { position_code: positionCode } } : {},
+ positionCode ? { position_code: positionCode } : {},
  );
  const byId = new Map<string, Record<string, unknown>>();
  for (const item of items) {
  if (positionCode && text(item?.position_code) !== positionCode) continue;
  byId.set(recordId(item), item);
  }
 
- const duties = await engine.find('duly_duty', { where: { source: 'catalog' } });
+ const duties = await engine.find('duly_duty', { source: 'catalog' });
 
  const changes: CatalogSyncChange[] = [];
  const retired: CatalogSyncRetired[] = [];

test/catalog-apply-cadence.test.ts

@@ -23,7 +23,7 @@ import type { CatalogApplyResult } from '../src/actions/catalog.handlers.js';
  * apply path unprotected is half a fix.
  *
  * ── Why a REAL booted engine and not `catalog-instantiate.test.ts`'s fake ──
- * That suite's `FakeEngine` is a Map with a `where` matcher: it runs no
+ * That suite's `FakeEngine` is a Map with a filter matcher: it runs no
  * validation rules and stamps no defaults, so every claim below would pass on
  * it for the wrong reason. Validation and `applyFieldDefaults` are precisely
  * what is under test here, so the handler is dispatched through the app's own
@@ -60,7 +60,7 @@ afterAll(async () => {
  await kernel?.shutdown?.();
 });
 
-// ── The two engine facades ──────────────────────────────────────────────────
+// ── The engine facade ───────────────────────────────────────────────────────
 
 interface Facade {
  insert(object: string, values: AnyRow): Promise<{ id: string }>;
@@ -70,15 +70,29 @@ interface Facade {
 }
 
 /**
- * The facade `applyCatalogHandler` is WRITTEN against: `find(object, query)`
- * takes ObjectQL's own query envelope, `where` and all. It is the convention
- * `catalog-instantiate.test.ts`'s `FakeEngine` honours too, so this is the
- * shape every existing assertion about the handler is made under.
+ * The facade the RUNTIME builds, reproduced line for line —
+ * `buildActionEngineFacade` in @objectstack/runtime 17.2.0:
+ *
+ * async find(object, query) {
+ * const where = query && Object.keys(query).length ? { where: query } : {};
+ * const rows = await ql.find(object, { ...where, context });
+ *
+ * `find(object, query)` therefore takes a BARE FILTER and wraps it here. This
+ * file used to carry TWO facades — this one honouring the handler's own
+ * `where` envelope, and a second reproducing the runtime — with a tripwire
+ * pinning the gap between them (#79). The handler now passes flat filters, so
+ * there is one convention and one facade.
+ *
+ * It is still a double, which is all it can be: the second test below has to
+ * put a row in front of the handler that `duly_catalog_item`'s own rules
+ * refuse, and only a hand-supplied facade can do that. What a double cannot do
+ * is prove the wire shape is right — it encodes the author's belief about it.
+ * That proof lives in `test/catalog-engine-facade.test.ts`, which dispatches
+ * through the real action route and lets the runtime build its own facade.
  *
  * `catalogItems`, when given, replaces the catalog read with rows handed
  * straight to the handler (unfiltered — the handler re-applies its own
- * `active` filter). That is how a row the object's own rules now REFUSE can
- * still be put in front of the handler, which one test below needs.
+ * `active` filter).
  */
 function handlerFacade(catalogItems?: AnyRow[]): Facade {
  return {
@@ -94,28 +108,6 @@ function handlerFacade(catalogItems?: AnyRow[]): Facade {
  },
  find: async (object, query) => {
  if (catalogItems && object === 'duly_catalog_item') return catalogItems.map((r) => ({ ...r }));
- return data.find(object, query);
- },
- };
-}
-
-/**
- * The facade the RUNTIME actually builds — `buildActionEngineFacade` in
- * @objectstack/runtime 17.2.0, reproduced line for line:
- *
- * async find(object, query) {
- * const where = query && Object.keys(query).length ? { where: query } : {};
- * const rows = await ql.find(object, { ...where, context });
- * ...
- *
- * It wraps whatever it is handed in a `where` of its own. Used by exactly one
- * test, the tripwire at the bottom.
- */
-function runtimeFacade(): Facade {
- const base = handlerFacade();
- return {
- ...base,
- find: async (object, query) => {
  const where = query && Object.keys(query).length ? { where: query } : {};
  return data.find(object, { ...where });
  },
@@ -227,41 +219,3 @@ describe('duly_catalog_apply — the cadence it replicates (#65)', () => {
  for (const field of CADENCE_FIELDS) expect(duty?.[field] ?? null, field).toBeNull();
  });
 });
-
-// ───────────────────────────────────────────────────────────────────────────
-// A tripwire on a filed defect — NOT an assertion that this is correct
-// ───────────────────────────────────────────────────────────────────────────
-describe('the handler\'s query shape does not survive the runtime\'s own facade', () => {
- /**
- * Measured while covering the apply path for #65 and filed as #79 — a
- * different defect from the missing validation rule, and not fixed here.
- *
- * `applyCatalogHandler` calls `engine.find('duly_catalog_item', { where: …
- * })`. The runtime's `buildActionEngineFacade` wraps whatever it is given:
- * `ql.find(object, { where: query })`. So through the real dispatcher the
- * handler's own `where` becomes `{ where: { where: … } }`, no row has a
- * field called `where`, and the read comes back EMPTY — with no error. The
- * action then reports `{ created: 0 }` and a successful run.
- *
- * Pinned so the seam is visible rather than folklore. When #79 is fixed
- * this goes red: delete this describe block — do not adjust it — and
- * `handlerFacade` above becomes the only convention in the file.
- */
- it('finds nothing, creates nothing, and reports success', async () => {
- const position = 'apply_runtime_facade';
- await insertItem({ position_code: position, form: 'recurring', frequency: 'weekly' });
-
- // Same item, same params, the only difference being which facade.
- const viaHandlerConvention = await apply(handlerFacade(), {
- position_code: position,
- users: ['u_f1'],
- });
- expect(viaHandlerConvention.catalog_items).toBe(1);
- expect(viaHandlerConvention.created).toBe(1);
-
- const viaRuntime = await apply(runtimeFacade(), { position_code: position, users: ['u_f2'] });
- expect(viaRuntime.catalog_items).toBe(0);
- expect(viaRuntime.created).toBe(0);
- expect(await dutiesOf('u_f2')).toEqual([]);
- });
-});

src/actions/catalog.handlers.ts

@@ -110,6 +110,41 @@ export function resolveDutyTimezone(): string {
  return DEFAULT_DUTY_TIMEZONE;
 }
 
+// ── The engine facade's query shape ───────────────────────────────────
+//
+// `ctx.engine.find(object, query)` takes a BARE FILTER, not an ObjectQL query
+// envelope. The runtime builds the envelope itself — `buildActionEngineFacade`
+// in @objectstack/runtime 17.2.0, read verbatim from its `dist/index.js`:
+//
+// async find(object, query) {
+// const where = query && Object.keys(query).length ? { where: query } : {};
+// const rows = await ql.find(object, { ...where, context });
+//
+// So every read in this file passes `{ field: value }`, never
+// `{ where: { field: value } }`. Handing it an envelope produces
+// `{ where: { where: { … } } }`; no row has a field called `where`, so the read
+// comes back EMPTY WITH NO ERROR. That is the failure this file shipped with:
+// `duly_catalog_apply` reported a successful run of zero, `duly_catalog_sync`
+// scanned nothing and called every duty unchanged, and `resolveBusinessUnit`
+// anchored no duty at all — silently, because "no position row" is a legitimate
+// day-one state. The ONE unfiltered read survived, because
+// `Object.keys({}).length === 0` skips the wrapping entirely, which is exactly
+// what made the handler look partially alive.
+//
+// `ActionEngineFacade.find` in @objectstack/spec types `query` as a plain
+// record of string to unknown and says nothing about which of the two shapes it
+// is — the runtime's implementation is the only thing that decides, and this
+// app read it the other way. Filed upstream as
+// **objectstack-ai/objectstack#14175** so the shape is DECLARED rather than
+// discovered; until that lands this comment is the contract.
+//
+// ⛔ Do NOT add a tolerant `query.where ?? query` rung — not here, not in a
+// test double. A consumer that accepts both shapes is precisely what let the
+// wrong one ship green: `test/catalog-instantiate.test.ts`'s fake honoured the
+// envelope, so 78 assertions passed against a shape production never produces.
+// The test that can see this is one that dispatches through the REAL route and
+// lets the runtime build its own facade — `test/catalog-engine-facade.test.ts`.
+
 // ── Shapes ──────────────────────────────────────────────────────────────────
 
 export interface CatalogApplyParams extends Record<string, unknown> {
@@ -256,12 +291,21 @@ export function pairKey(catalogItem: unknown, owner: unknown): string {
  * exists on the platform. It is NOT read here — the issue names the
  * assignment-level anchor, and adding a fallback rung is a product decision,
  * reported rather than taken.)
+ *
+ * ⚠️ That tolerance is why this read's query shape matters more than the other
+ * three. The other reads fail into a visibly empty report — zero items, zero
+ * scanned — but this one fails into a state the handler is WRITTEN to accept:
+ * an envelope-shaped filter returned nothing, "nothing" reads as "not yet
+ * modelled", and every duty was created unanchored with no error anywhere. The
+ * rollups that the business unit exists to feed were simply empty. See the
+ * facade-shape note above; the end-to-end coverage is in
+ * `test/catalog-engine-facade.test.ts`.
  */
 async function resolveBusinessUnit(
  engine: ActionEngineFacade,
  userId: string,
 ): Promise<string | undefined> {
- const rows = await engine.find('sys_user_position', { where: { user_id: userId } });
+ const rows = await engine.find('sys_user_position', { user_id: userId });
  for (const row of rows) {
  // A person can hold several positions; take the first anchored one.
  // Unanchored rows (`null`) are legacy/tenant-wide and carry no depth.
@@ -282,13 +326,14 @@ export const applyCatalogHandler: ActionHandler<CatalogApplyParams> = async (ctx
  // stopped asking for; handing it to a new hire on their first day is the
  // opposite of what deactivating it meant.
  const items = await engine.find('duly_catalog_item', {
- where: { position_code: positionCode, active: true },
+ position_code: positionCode,
+ active: true,
  });
  const activeItems = items.filter((item) => item?.active !== false);
 
  // One probe for the whole run, not one per (item, user). The pair set is
  // what makes a second apply create nothing.
- const existing = await engine.find('duly_duty', { where: { owner: { $in: users } } });
+ const existing = await engine.find('duly_duty', { owner: { $in: users } });
  const taken = new Set<string>();
  for (const duty of existing) {
  // Any duty already pointing at this catalog item for this person counts —
@@ -384,15 +429,15 @@ export const syncCatalogHandler: ActionHandler<CatalogSyncParams> = async (ctx)
  // the retired report is made of, so it has to come back from this read.
  const items = await engine.find(
  'duly_catalog_item',
- positionCode ? { where: { position_code: positionCode } } : {},
+ positionCode ? { position_code: positionCode } : {},
  );
  const byId = new Map<string, Record<string, unknown>>();
  for (const item of items) {
  if (positionCode && text(item?.position_code) !== positionCode) continue;
  byId.set(recordId(item), item);
  }
 
- const duties = await engine.find('duly_duty', { where: { source: 'catalog' } });
+ const duties = await engine.find('duly_duty', { source: 'catalog' });
 
  const changes: CatalogSyncChange[] = [];
  const retired: CatalogSyncRetired[] = [];

test/catalog-apply-cadence.test.ts

@@ -23,7 +23,7 @@ import type { CatalogApplyResult } from '../src/actions/catalog.handlers.js';
  * apply path unprotected is half a fix.
  *
  * ── Why a REAL booted engine and not `catalog-instantiate.test.ts`'s fake ──
- * That suite's `FakeEngine` is a Map with a `where` matcher: it runs no
+ * That suite's `FakeEngine` is a Map with a filter matcher: it runs no
  * validation rules and stamps no defaults, so every claim below would pass on
  * it for the wrong reason. Validation and `applyFieldDefaults` are precisely
  * what is under test here, so the handler is dispatched through the app's own
@@ -60,7 +60,7 @@ afterAll(async () => {
  await kernel?.shutdown?.();
 });
 
-// ── The two engine facades ──────────────────────────────────────────────────
+// ── The engine facade ───────────────────────────────────────────────────────
 
 interface Facade {
  insert(object: string, values: AnyRow): Promise<{ id: string }>;
@@ -70,15 +70,29 @@ interface Facade {
 }
 
 /**
- * The facade `applyCatalogHandler` is WRITTEN against: `find(object, query)`
- * takes ObjectQL's own query envelope, `where` and all. It is the convention
- * `catalog-instantiate.test.ts`'s `FakeEngine` honours too, so this is the
- * shape every existing assertion about the handler is made under.
+ * The facade the RUNTIME builds, reproduced line for line —
+ * `buildActionEngineFacade` in @objectstack/runtime 17.2.0:
+ *
+ * async find(object, query) {
+ * const where = query && Object.keys(query).length ? { where: query } : {};
+ * const rows = await ql.find(object, { ...where, context });
+ *
+ * `find(object, query)` therefore takes a BARE FILTER and wraps it here. This
+ * file used to carry TWO facades — this one honouring the handler's own
+ * `where` envelope, and a second reproducing the runtime — with a tripwire
+ * pinning the gap between them (#79). The handler now passes flat filters, so
+ * there is one convention and one facade.
+ *
+ * It is still a double, which is all it can be: the second test below has to
+ * put a row in front of the handler that `duly_catalog_item`'s own rules
+ * refuse, and only a hand-supplied facade can do that. What a double cannot do
+ * is prove the wire shape is right — it encodes the author's belief about it.
+ * That proof lives in `test/catalog-engine-facade.test.ts`, which dispatches
+ * through the real action route and lets the runtime build its own facade.
  *
  * `catalogItems`, when given, replaces the catalog read with rows handed
  * straight to the handler (unfiltered — the handler re-applies its own
- * `active` filter). That is how a row the object's own rules now REFUSE can
- * still be put in front of the handler, which one test below needs.
+ * `active` filter).
  */
 function handlerFacade(catalogItems?: AnyRow[]): Facade {
  return {
@@ -94,28 +108,6 @@ function handlerFacade(catalogItems?: AnyRow[]): Facade {
  },
  find: async (object, query) => {
  if (catalogItems && object === 'duly_catalog_item') return catalogItems.map((r) => ({ ...r }));
- return data.find(object, query);
- },
- };
-}
-
-/**
- * The facade the RUNTIME actually builds — `buildActionEngineFacade` in
- * @objectstack/runtime 17.2.0, reproduced line for line:
- *
- * async find(object, query) {
- * const where = query && Object.keys(query).length ? { where: query } : {};
- * const rows = await ql.find(object, { ...where, context });
- * ...
- *
- * It wraps whatever it is handed in a `where` of its own. Used by exactly one
- * test, the tripwire at the bottom.
- */
-function runtimeFacade(): Facade {
- const base = handlerFacade();
- return {
- ...base,
- find: async (object, query) => {
  const where = query && Object.keys(query).length ? { where: query } : {};
  return data.find(object, { ...where });
  },
@@ -227,41 +219,3 @@ describe('duly_catalog_apply — the cadence it replicates (#65)', () => {
  for (const field of CADENCE_FIELDS) expect(duty?.[field] ?? null, field).toBeNull();
  });
 });
-
-// ───────────────────────────────────────────────────────────────────────────
-// A tripwire on a filed defect — NOT an assertion that this is correct
-// ───────────────────────────────────────────────────────────────────────────
-describe('the handler\'s query shape does not survive the runtime\'s own facade', () => {
- /**
- * Measured while covering the apply path for #65 and filed as #79 — a
- * different defect from the missing validation rule, and not fixed here.
- *
- * `applyCatalogHandler` calls `engine.find('duly_catalog_item', { where: …
- * })`. The runtime's `buildActionEngineFacade` wraps whatever it is given:
- * `ql.find(object, { where: query })`. So through the real dispatcher the
- * handler's own `where` becomes `{ where: { where: … } }`, no row has a
- * field called `where`, and the read comes back EMPTY — with no error. The
- * action then reports `{ created: 0 }` and a successful run.
- *
- * Pinned so the seam is visible rather than folklore. When #79 is fixed
- * this goes red: delete this describe block — do not adjust it — and
- * `handlerFacade` above becomes the only convention in the file.
- */
- it('finds nothing, creates nothing, and reports success', async () => {
- const position = 'apply_runtime_facade';
- await insertItem({ position_code: position, form: 'recurring', frequency: 'weekly' });
-
- // Same item, same params, the only difference being which facade.
- const viaHandlerConvention = await apply(handlerFacade(), {
- position_code: position,
- users: ['u_f1'],
- });
- expect(viaHandlerConvention.catalog_items).toBe(1);
- expect(viaHandlerConvention.created).toBe(1);
-
- const viaRuntime = await apply(runtimeFacade(), { position_code: position, users: ['u_f2'] });
- expect(viaRuntime.catalog_items).toBe(0);
- expect(viaRuntime.created).toBe(0);
- expect(await dutiesOf('u_f2')).toEqual([]);
- });
-});