[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

[os-sales]

os-dev-report

{
  "issue": 14460,
  "status": "done",
  "branch": "claude/issue-14460-drop-dead-rowsof",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/14841",
  "premise_still_valid": true,
  "summary": "Deleted the local `rowsOf()` normalizer from examples/app-showcase/src/automation/jobs/sweep-project-health.ts and read the two `await ql.find(...)` results directly. Nothing else touched: 1 file, +12/-23. The ruling verified independently and holds on the tree — the `{ records }` limb is unreachable. Both call sites keep the exact static type they had (`Array` of `Record` of `string` to `unknown`) via an explicit annotation rather than letting the declared `any[]` propagate and silently weaken the downstream member reads. Applied the `skip-changeset` label: `@objectstack/example-showcase` is private, so the diff publishes nothing from any released package (AGENTS.md's stated criterion); the direct precedent is 253da34c4, the examples-only commit that created this handler, which carried no changeset either.",
  "tests": "All at commit e275b7b8 (final commit; nothing landed after these runs). BEFORE/AFTER on the covering suite examples/app-showcase/test/inert-wirings.test.ts, run under scripts/pm/os-verify-lock.sh, mutation and restore each confirmed on disk by blob hash before any reading: AFTER (rowsOf count 0) `Tests  36 passed (36)`; BEFORE (parent file restored, blob cd757ba8 == HEAD~1 blob, rowsOf count 3) `Tests  36 passed (36)`; RESTORE (blob 006c547c == HEAD blob, `git diff HEAD` empty, rowsOf count 0). Script carried `trap restore EXIT INT TERM` with absolute paths. No rebuild leg needed either way: example-showcase exports TypeScript source (main: ./objectstack.config.ts) and the suite imports the handler by relative source path, so no dist/ sits between the edit and the assertion — stated because an ablation normally owes a rebuild. Identical counts are the expected direction, not a miss: the suite's fake engine returns arrays on every path, so it never exercised the deleted limb — corroboration that it was dead and that no coverage was lost. WHOLE PACKAGE after: `Test Files  27 passed (27)`, `Tests  375 passed (375)`. Typecheck: pnpm --filter @objectstack/example-showcase run typecheck (tsc --noEmit) clean, and PROVEN to cover the edit — tsc --listFiles lists sweep-project-health.ts among the 1589 files in the program. GATES: dependency closure built first (pnpm --filter '@objectstack/example-showcase^...' build, VERDICT command-exit 0). Family re-derived from the real diff via `node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack` (it read 1 path vs merge base 2d40f914) — 17 commands, every exit code captured by redirect-then-read, never across a pipe. 15 green, including check:react-page-adapter-contract ('21 app-showcase page module(s) + 1 content/docs react-page sample(s) ... no find() result is tested for array-ness'). 2 exited 3 and are NOT MEASURED by their own verdict text, not red and not green: check-test-completeness ('Nothing was measured: this gate exited before parsing a single summary line') and check:dual-build-cjs-loads ('PREREQUISITE NOT MET — this gate reads built output, and some package has no dist/', self-test half passed, 93 cases). Also: pnpm check:nul-bytes green (8070 files, no raw control bytes) and the FULL repo-wide pnpm lint (eslint . --no-inline-config) exit 0 with no findings — the whole scan, not a declared narrowing. CI has not been waited on; per dispatch contract the report ships at draft-PR time.",
  "mcp_calls": "7 so far this run (create_pull_request, pull_request_read, issue_read/get_labels which failed to resolve a PR number, search_pull_requests for the label union read, issue_write for the label write, update_pull_request for the body repair, this comment), plus the read-backs that follow it. `gh` is absent in this container, so REST was unavailable and MCP was the only write channel — declared as a channel switch.",
  "open_questions": [],
  "out_of_scope_findings": [
    "NOT FILED — no dedupe channel available, handing to PM to file: a second instance of the same dead-normalizer shape lives at packages/cli/src/commands/secret/orphans.ts (its own local `rowsOf` at :438, used at :245 and :262 over `secretDriver.find(...)`). Same class as this card, different package and lane (domain:devx / CLI), so the ruling's 'Nothing else' keeps it out of this PR. I could not run the required pre-filing duplicate search: `gh` is absent, so the repo-scoped REST probe failed, and the prescribed fallback is one targeted MCP search_issues — I am reporting rather than filing so the search is not skipped. Worth noting the driver contract there is IDataDriver.find, declared as resolving to an array of row objects (packages/spec/src/contracts/data-driver.ts:155), so the same unreachability argument likely applies, but I did not verify which concrete driver `secretDriver` resolves to.",
    "OBSERVATION, not a defect: check:react-page-adapter-contract's population is app-showcase PAGE modules plus content/docs react-page samples. It structurally cannot see a job handler, which is why this instance survived a green gate. The triage ruling explicitly ruled widening that population out of scope and asked for it to be filed separately if the class should be closed. I did not touch the gate or its population. Flagging it so PM can decide whether to open that card in the domain:devx lane."
  ]
}

Generated by Claude Code

---

Generated by Claude Code