[bpamiri]

Closes #4530

Problem

where= is parsed, not passed through. Each column <operator> literal is bound as a query parameter, and the column must belong to the model or an included model.

A literal compared with another table's column inside a subquery doesn't fit that rule. For example, in id IN (SELECT book_id FROM accesses WHERE user_id = 1), the literal was masked but never got a parameter, so the SQL builder failed with Array index [1] out of range, array size is [0] (sql.cfm). The error named neither the condition nor the cause. A condition with no column, such as where="1 = 0", failed with a Wheels.ColumnNotFound that didn't say why either.

Change

where= accepts model columns compared with values; literal-only predicates are not supported. This PR makes the errors say so.

• A value with no column to bind against:
  • $whereClause() now throws Wheels.UnbindableWhereValue naming the condition, with its quoted values hidden. A bound value shows as ? and any other quoted literal as '...'. Unquoted numbers in the developer's own where text are shown as written.
  • The error lists the alternatives: compare subquery columns only, use whereIn() with a value array, or run the subquery as its own query first.
• Wheels.ColumnNotFound from a where= now explains the rule in its detail:
  • for a number in the column's place (1 = 0), that a condition with no column isn't supported, and what to use instead;
  • for a clause with a subquery, the subquery alternatives above.
• Docs.
  • The query guide's "Which values are bound" section states the rule. It says where="1 = 0" isn't supported, and that for no rows you use whereIn() with an empty array and for every row you leave the condition out. It also covers the subquery case, with a two-step whereIn() example.
  • .ai/models.md and the app template's copy say the same. The consumer-docs check passes.
  • A changelog fragment (fixed) is included.

Tests

New whereUnboundLiteralSpec (model suite):

• where="1 = 0" throws Wheels.ColumnNotFound whose detail says it isn't supported and names whereIn() with an empty array;
• whereIn("id", []) returns no rows;
• a subquery literal throws Wheels.UnbindableWhereValue naming WHERE views=?;
• the error hides quoted values: with a quoted literal elsewhere in the subquery's SELECT and a quoted value in its WHERE, the message contains neither value, their hex encoding, the mask sentinel, nor Chr(2);
• a column-only subquery still runs;
• the subquery hint on ColumnNotFound.

Local results (production code as at bebed30; later commits change wording and a spec name only):

Engine	Suite	Databases	Result
Lucee 7	full core suite	SQLite	7294/0/0
Lucee 7	model	PostgreSQL, SQL Server, Oracle	all 0 fail
BoxLang	model	SQLite	0 fail
Adobe 2023	model	SQLite	0 fail
Adobe 2025	model	SQLite, SQL Server	all 0 fail
RustCFML (run-suite.sh, TZ=UTC)	full core suite	SQLite	exit 0, no new failures

The complexity and docblock gates pass. The guides site builds, and verify-docs on the query page passes 12/12.

🤖 Generated with Claude Code

[github-actions]

Wheels Test Results

37 230 tests   36 483 ✅  10m 40s ⏱️
 2 995 suites     747 💤
     5 files         0 ❌

Results for commit 433ae85.

♻️ This comment has been updated with latest results.

[bpamiri]

Source review approved at 433ae859b.

Unsupported literal-only predicates retain their existing error behavior, with clearer guidance. Independently verified quoted diagnostic redaction on Lucee 7/SQLite with ordinary text, doubled apostrophes and control-character data, under parameterize=true and false; the six PR regression specs also pass.

Final gate remains full matrix 37953211949, narrowed matrix 37954031094, and current-head PR CI.

[bpamiri]

Final approval — OK TO MERGE at 433ae859bc4d.

• Audited raw JSON for all 40 JVM legs across full run 37953211949 and narrowed run 37954031094: 599 bundles per leg, zero failures/errors. All six whereUnboundLiteralSpec cases executed and passed on every leg, with no skips.
• Current-head RustCFML: 7268 passed, zero failures/errors, 178 skipped. Both compatibility gates succeeded.
• Current-head PR CI: 29 passed, 2 skipped, none failed or pending.
• The delta from the full-matrix head changes wording only; production logic is unchanged. The independent Lucee 7 quoted-value redaction probe also passed, as recorded in the source review.