dispatch: Wheels.ActionNotAllowed surfaces as HTTP 500, not the 404 promised by #2845 (and CLAUDE.md Anti-Pattern 8)

[bpamiri]

Summary

#2845 populated application.wheels.protectedControllerMethods so framework helpers (env, model, filterChain, ...) can't be invoked as actions. Its PR body states the intent: "Reaching one of these names now throws Wheels.ActionNotAllowed and falls through to the missing-action / 404 path, matching every other non-existent action." CLAUDE.md Anti-Pattern 8 repeats it ("→ 404").

The block itself works — the helper never dispatches, on every engine, and private methods are correctly unreachable (probed both directions). Only the status contract is broken: ActionNotAllowed surfaces as 500 while a plain missing action 404s.

Probe (develop @ 840274b, clean controller, wildcard route only)	Lucee 7 dev	Lucee 7 prod	Adobe 2023 dev	Adobe 2023 prod
GET /bare/env (helper name)	500 ActionNotAllowed	500	500 ActionNotAllowed	500 generic page
GET /bare/notreal (missing action)	404 ViewNotFound	404	404 ViewNotFound	404

A 500 miscategorizes probe traffic in monitoring and tells URL scanners they found something, where a 404 would not.

Root cause

• vendor/wheels/controller/processing.cfc:136-144 — $callAction() throws raw Wheels.ActionNotAllowed (verified at source: line 138 gate, line 140 throw).
• vendor/wheels/events/EventMethods.cfc:83-90 — only ^Wheels\.[A-Za-z]*NotFound$ maps to 404; everything else falls to the 500 branch.

Proposed direction (either)

1. Throw via $throwErrorOrShow404Page(type="Wheels.ActionNotAllowed", ...) in $callAction() (mirrors RecordNotFound handling, gives the production 404 page) — matches fix(controller): populate protectedControllerMethods so global helpers aren't URL-invokable #2845's wording most closely; or
2. Add ActionNotAllowed to the 404 mapping in EventMethods.cfc (ReFindNoCase("^Wheels\.([A-Za-z]*NotFound|ActionNotAllowed)$", ...)).

Update CLAUDE.md Anti-Pattern 8 whichever way this resolves (it currently states "→ 404", which is wrong today).

Acceptance

• Helper-named actions return 404 in dev and prod on Lucee + Adobe (protectedMethodsSpec.cfc extended to assert the HTTP status, not just the throw).
• CLAUDE.md Anti-Pattern 8 matches shipped behavior.

Reproducer caveat: make sure no .resources(name="posts") route precedes the wildcard, or /posts/env matches the resource show route with key="env" and you'll observe verifies/binding behavior instead.

Reported by the guide-behavioral-audit P1 batch 2 (work item p1-9-authz, claim authz-helper-named-action-blocked; live on Lucee 7 + Adobe 2023, dev + prod; root cause re-verified at source by the consolidator).

[wheels-bot]

Wheels Bot — Triage

Classified as bug.

The report describes observable wrong behavior (Wheels.ActionNotAllowed returns HTTP 500) that contradicts documented behavior — #2845's PR body and CLAUDE.md Anti-Pattern 8 both promise a 404. The probe table and root-cause analysis are concrete and verified at source.

Suspected layer

controller — see .ai/wheels/controllers/ for canonical patterns. The throw originates in the controller dispatch path ($callAction()); the status mapping lives in the events layer. Both confirmed at source:

• vendor/wheels/controller/processing.cfc:137-144 — $callAction() raises a raw Throw(type="Wheels.ActionNotAllowed", ...).
• vendor/wheels/events/EventMethods.cfc:83-90 — only ^Wheels\.[A-Za-z]*NotFound$ maps to 404; everything else (including ActionNotAllowed) falls through to the 500 branch.

Fix sketch

Either of the two directions in the issue body works and both are one-file mechanical changes:

1. In processing.cfc, route the protected-method case through $throwErrorOrShow404Page(type="Wheels.ActionNotAllowed", ...) instead of a raw Throw (mirrors RecordNotFound, yields the production 404 page); or
2. In EventMethods.cfc, widen the regex to include ActionNotAllowed: ReFindNoCase("^Wheels\.([A-Za-z]*NotFound|ActionNotAllowed)$", ...).

Whichever lands, update CLAUDE.md Anti-Pattern 8 (currently states "→ 404", which is wrong today) and extend protectedMethodsSpec.cfc to assert the HTTP status, not just the throw.

Confidence: medium

The report and root cause are exceptionally clear, but two factors hold this at medium: the fix has a genuine design trade-off (two distinct directions with different blast radius — production 404-page rendering vs. a narrow regex widen), and there's a cross-engine concern (the prod error-page rendering already differs between Adobe 2023 and Lucee 7 per the probe table), which the auto-downgrade rule caps at medium.

<!-- wheels-bot:triage:3075 -->
<!-- wheels-bot:triage-class:bug -->
<!-- wheels-bot:triage-confidence:medium -->

[wheels-bot]

Wheels Bot — Fix proposed

Draft PR: #3103

Spec: vendor/wheels/tests/specs/controller/protectedMethodsSpec.cfc (gate now asserts HTTP 404) and vendor/wheels/tests/specs/events/onerrorSpec.cfc (Wheels.ActionNotAllowed → 404 status-map contract) — failing → passing.
Implementation: vendor/wheels/controller/processing.cfc (routes the gate through $throwErrorOrShow404Page) and vendor/wheels/events/EventMethods.cfc (widens the 404 status map to include ActionNotAllowed).

Both proposed directions from the issue were applied together: direction 1 fixes the production path (404 page + committed 404 header at the throw site), direction 2 fixes the development path (the EventMethods status map). Local Lucee 7 + SQLite run is green with no regressions (controller 498, events 50, dispatch 109, security 288).

A human review is required before merge. The Reviewer will weigh in shortly. Doc updates (MDX guides, .ai/wheels/, CLAUDE.md) are handled separately by bot-update-docs.yml — note Anti-Pattern 8's "→ 404" wording is now accurate as shipped.