[finding] app-showcase's job sweep still normalizes `{ records }` off an engine `find()` the contract types as an array

[os-musk]

Found while implementing #14257 (PR #14459), which is where the handler first became typed against the real engine contract. Out of that card's scope — a different defect class — so it is recorded rather than fixed there.

Measured

examples/app-showcase/src/automation/jobs/sweep-project-health.ts carries:

/** Normalize the engine's list shape (array, or `{ records }`). */
function rowsOf(result: unknown): Array... {
 if (Array.isArray(result)) return result as ...;
 const records = (result as { records?: unknown })?.records;
 return Array.isArray(records) ? (records as ...) : [];
}

Both of its read sites now pass await ql.find(...) where ql is IObjectQLEngine off JobHandlerContext. IDataEngine.find is declared

find(objectName: string, query?: EngineQueryOptions, options?: BaseEngineOptions): Promise...any[];

so the { records } limb is unreachable through the declared contract, and rowsOf is an identity on everything the engine can hand it. Before #14257 the handler's engine was a locally-declared JobHostEngine returning Promise of unknown, which is why the tolerance read as reasonable there and does not any more.

Why it is worth recording

This is the tolerant-consumer shape Prime Directive #12 rules out and that this same app has had deleted twice already — the ?? records aliases (#13705) and the unreachable Array.isArray limb beside them (#13706 / #13969), both at adapter.find() sites in src/ui/pages/. pnpm check:react-page-adapter-contract gates that class, but its population is *.page.ts / *.pages.ts plus the react-pages doc, so an automation job under src/automation/ is outside it and nothing reds today.

It also matters more here than the line count suggests: this is the repo's only shipped defineJob, so it is what an author copies when they write scheduled work.

Two things a fix has to decide, hence a finding and not a patch

1. Whether the engine find direction really is the mirror image of the adapter one. [finding] The Array.isArray(result) limb beside the retired ?? records alias is also unreachable — normalizeQueryResult() wraps a bare array, so find() never resolves to one #13706 concluded the OPPOSITE for the react-page adapter — normalizeQueryResult() wraps a bare array, so that find() never resolves to one. The two finds are different functions; the engine's declared return should be confirmed against ObjectQL's implementation, not inferred from the sibling card.
2. Whether the fix is local (delete rowsOf, read the array) or a gate widening, i.e. whether check:react-page-adapter-contract's no-array-ness detector should grow a population beyond page modules. The second is the one that closes the class rather than one instance.

Unassigned and untriaged.

Generated by Claude Code

[huangyiirene]

Triage — graded, finding cleared. Both of the card's two open questions are answerable from origin/main ed44512, and I answered them rather than passing them on, because they are what stood between this card and a one-line scope.

Question 1 — is the engine find really the mirror image of the adapter one? Yes.

The card was right to refuse to infer this from #13706. Measured directly, on both sides of the contract:

• Declared: packages/spec/src/contracts/data-engine.ts:251 — find(objectName: string, query?: EngineQueryOptions, options?: BaseEngineOptions): Promise<any[]>;
• Implemented: packages/objectql/src/engine.ts:8946 — async find(object: string, query?: EngineQueryOptions, options?: EngineReadOptions): Promise<any[]>

The implementation's own signature is the array type, so there is no gap between the declaration and what ObjectQL actually hands back. JobHandlerContext.ql (packages/runtime/src/job-handler-context.ts:80-81) is documented as "the live ObjectQL engine — the SAME handle defineStack({ onEnable }) receives as ctx.ql", so the handler is holding that engine and no other.

This is genuinely the opposite of #13706's react-page adapter, where normalizeQueryResult() wraps a bare array and so that find() never resolves to one. Two different functions, opposite answers, and the card was correct not to assume.

⇒ rowsOf's { records } limb is unreachable and the function is an identity on everything the engine can produce.

Question 2 — gate population. Card's claim confirmed, and it is out of scope here.

scripts/check-react-page-adapter-contract.mjs:70-71 defines "Population A — every page module under examples/app-showcase/src/** (*.page.ts / *.pages.ts)". src/automation/jobs/sweep-project-health.ts is neither, so nothing reds today. Confirmed.

But widening that population is a change to a gate under scripts/ (domain:devx), with its own self-test and its own false-positive surface — a different package, a different lane, and not something to ride in on an examples cleanup. File it separately if you want the class closed; this card is the instance.

Scope ruled

Delete rowsOf (examples/app-showcase/src/automation/jobs/sweep-project-health.ts:96) and read the two await ql.find(...) results at :148 and :162 as the arrays they are. Nothing else. This is the same deletion Prime Directive #12 has already forced twice in this app (#13705, #13706 / #13969) and the reasoning is now measured rather than transplanted.

Routing

domain:services — the fix lands in examples/app-showcase/src/automation/, and examples/* anchors to the subsystem it exercises (lane table); this is automation job-host code. priority:p3: dead code, no behavioural defect — it stays a real card because this is the repo's only shipped defineJob and therefore the copy-source for scheduled work, which is the card's argument and it holds. pm:queue.

---

Generated by Claude Code