router: scope()/namespace() silently ignore callback= — routes in the callback never register and the unclosed scope swallows every subsequent route (documented in 5+ guides)

[bpamiri]

Summary

.scope() does not accept a callback parameter (vendor/wheels/mapper/scoping.cfc:17-29), and namespace()/package()/controller() just forward to it. Only group() (scoping.cfc:166-192, executes the callback then auto-end()s — inherited by api()/version()) and resources() consume callbacks. CFML happily accepts the extra named argument, so the documented callback forms fail twice, both silently:

1. The callback never executes — routes declared inside it simply don't exist (404 Wheels.RouteNotFound).
2. The scope is never closed, so every subsequent route (resources, wildcard, even root) inherits the scope's path prefix AND middleware. The misrouted URLs even respond (e.g. /admin/posts 200 because the outer .resources("posts") got swallowed into the open namespace), which makes the missing public routes very hard to diagnose.

This is the single most-repeated broken pattern found by the batch-2 guide audit — three independent verifiers hit it from three different guides.

Repro (develop @ 840274b, Lucee 7 — mapper logic is engine-independent)

Rate-limiting guide shape:

mapper()
    .scope(
        path="/limited",
        middleware=[new wheels.middleware.RateLimiter(maxRequests=2, windowSeconds=15)],
        callback=function(map) {
            map.get(name="limitedIndex", pattern="/", to="limited##index");
        }
    )
    .wildcard()
    .root(method="get")
.end();

Observed: limitedIndex never created; .wildcard()/.root() nested under /limited (GET /limited/probe → 200 via the nested wildcard, GET /probe → 404). The whole app's top-level routing silently breaks.

Routing-guide shape (.namespace(name="admin", callback=...) followed by an outer .resources("posts")): /admin/posts → 200 only because the open namespace swallowed the outer resources; public /posts → 404. The manual .namespace("admin")...end() form works correctly (both URL families 200). Framework specs only ever use the manual form (vendor/wheels/tests/specs/mapperSpec.cfc:165).

CORS-guide shape (.scope(path="/api", middleware=[Cors], callback=...)): identical — /api/ping 404, /plain-ping 404, /api/plain-ping 200 with the leaked scoped CORS headers.

Root cause

scope() declares no callback argument; the extra named arg lands in arguments, is prepended onto the scope stack (scoping.cfc:91), and is never invoked — and nothing pops the stack. scoping.cfc's own forwarding comments say options should "not be silently dropped"; callback currently is, and worse, dropping it changes the meaning of everything declared after it.

Documented call sites teaching the broken form (all shipped since the v4 guides rewrite #2169)

• web/sites/guides/src/content/docs/v4-0-0/digging-deeper/rate-limiting.mdx lines 183-201
• web/sites/guides/src/content/docs/v4-0-0/digging-deeper/cors.mdx lines 94-114
• web/sites/guides/src/content/docs/v4-0-0/digging-deeper/multi-tenancy.mdx line 271
• web/sites/guides/src/content/docs/v4-0-0/digging-deeper/route-model-binding.mdx line 118
• web/sites/guides/src/content/docs/v4-0-0/basics/routing.mdx "Namespaced sections" (.namespace(name="admin", callback=...))
• repo CLAUDE.md Route Model Binding section (.scope(path="/api", binding=true) is fine, but check for callback forms)

Proposed direction

Preferred: implement callback= in scope() mirroring group() — exclude callback from the scope-stack entry, execute arguments.callback(this) after the prepend, then auto-end() (~6 lines, scoping.cfc:185-189 is the template). That makes namespace(), package(), and controller() consistent with group()/resources() and fixes every guide example as written.

Fallback: throw Wheels.InvalidArgument in development when scope() receives an unconsumed callback, and rewrite the five guide call sites to the explicit .end() (or .group()) form. Either way, silent acceptance is the worst of the three options.

Also worth fixing alongside: namespaced controllers under app/controllers/admin/ need extends="app.controllers.Controller" — bare extends="Controller" throws "invalid component definition" on Lucee from the subfolder; no guide mentions this.

Acceptance

• .scope(path="/x", callback=function(map){ map.get(...); }) registers the callback routes and auto-closes the scope (or throws loudly in development), with specs covering scope/namespace/package callback forms and the no-swallow guarantee for routes declared after.
• The five guide examples above work as written (or are rewritten in the same PR if the throw option is chosen).

Reported by the guide-behavioral-audit P1 batch 2 (work items p1-10-routing claims R11/R12, p1-11-ratelimit claim rl-22, p1-12-cors claim cors-17 — three independent live repros, develop @ 840274b).

[wheels-bot]

Wheels Bot — Triage

Classified as bug.

The report describes observable wrong behavior with a root cause and repro: .scope(... callback=function(map){...}) silently drops the callback so its routes "never execute" (404 Wheels.RouteNotFound) and "the scope is never closed, so every subsequent route ... inherits the scope's path prefix AND middleware." Confirmed in source: scope() (vendor/wheels/mapper/scoping.cfc:33-44) declares no callback argument, while group() (scoping.cfc:166-192) does and handles it correctly.

Suspected layer

router — the fix lives in the mapper/scoping layer (vendor/wheels/mapper/scoping.cfc). No dedicated .ai/wheels/router/ doc exists; ground reasoning in scoping.cfc itself and vendor/wheels/tests/specs/mapperSpec.cfc.

Fix sketch

Add any callback to scope() in vendor/wheels/mapper/scoping.cfc and mirror the group() template (scoping.cfc:185-189): exclude callback from the scope-stack entry, then after the prepend run arguments.callback(this) and auto-end(). This makes namespace()/package()/controller() (which forward to scope()) consistent with group()/resources() and fixes every documented guide example. New specs should cover scope/namespace/package callback forms plus the no-swallow guarantee for routes declared after. The five guide call sites listed in the issue (rate-limiting, cors, multi-tenancy, route-model-binding, routing) become correct as written. The reporter also offers a fallback (throw Wheels.InvalidArgument on an unconsumed callback + rewrite the guides), which is a design choice for propose-fix to weigh.

Confidence: medium

The layer is unambiguous and the preferred fix has a working in-repo template, but there's a genuine design trade-off (implement callback= vs throw-and-rewrite-guides) plus a scope-stack/middleware-leak interaction to get right, so it's not purely mechanical.

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

[wheels-bot]

Wheels Bot — Fix proposed

Draft PR: #3100

Spec: vendor/wheels/tests/specs/mapper/MapperRobustnessSpec.cfc — failing → passing (a new scope()/namespace()/package() callback form block: callback routes register under the scope path, the scope auto-closes so routes declared after are not swallowed, and scope middleware does not leak onto later routes)
Implementation: vendor/wheels/mapper/scoping.cfc — scope() now consumes callback= the way group() does (runs callback(this), then auto-end()s), so namespace()/package()/controller() inherit it too

Implements the issue's preferred direction. Verified on Lucee 7 + SQLite: the 5 new specs failed first on the exact bug ([pattern] does not exist, Expected [/public-index] but received [/limited/public-index], [middleware] does not exist), then pass after the fix; full core suite stays green at 4444 specs, 0 fail, 0 error. Adobe/BoxLang are validated by the PR's compat-matrix CI (the change adds no engine-specific path — it mirrors group(), which already passes everywhere).

Opened as Refs #3072 rather than Closes because the five guide MDX call sites (rate-limiting, cors, multi-tenancy, route-model-binding, routing) and the CLAUDE.md note are handled separately by bot-update-docs.yml, which runs after this PR opens.

A human review is required before merge. The Reviewer will weigh in shortly.

[bpamiri]

Fixed by PR #3100 (merged 957bab9): scope()/namespace() now honor callback= and auto-end the scope. The guide examples were aligned in the merged docs train (#3092 routing, #3095 rate-limiting/CORS) — the documented callback form now works as written.