hasMany shortcut association not recognised by include - "association not found" error

[chapmandu]

Describe the bug
Wheels v4. Using a hasMany shortcut with the name of an existing model, an "association not found" exception occurs.

To Reproduce

// models/Product.cfc
hasMany(name = "ProductCategories", shortcut = "Category");

// models/ProductCategory.cfc
belongsTo(name = "Product");
belongsTo(name = "Category");

// models/Category.cfc
hasMany(name = "ProductCategories");

// throws "association not found" exception
model("Product").findAll(include = "Category");

Expected behavior
The model findAll call should join to Category model through the ProductCategories "bridge" table/model.

Additional context
Apologies for pseudo-code.. I had to change branches for work and wanted to log the issue before I forgot the specifics.

[wheels-bot]

Wheels Bot — Triage

Classified as bug.

The report has a clear "what happened / what I expected": a hasMany(name="ProductCategories", shortcut="Category") declaration on Product, then model("Product").findAll(include="Category") throws Wheels.AssociationNotFound instead of joining through the ProductCategories bridge to Category.

Suspected layer

model — the include/through expansion logic. Canonical association patterns: .ai/wheels/views/query-association-patterns.md; association declaration lives in vendor/wheels/model/associations.cfc.

Fix sketch

The shortcut name (Category) is registered as a dynamic accessor method by hasMany's shortcut/through handling (associations.cfc:58-70), not as a first-class includable association — so Product has an association named ProductCategories, not Category. When include="Category" reaches $expandThroughAssociations / $expandedAssociations (vendor/wheels/model/sql.cfc:1185-1273), no Category association is found on Product and it falls through to the Wheels.AssociationNotFound throw at sql.cfc:1267-1273. The fix likely teaches include-expansion to resolve a hasMany shortcut name into its through chain (e.g. rewrite Category to ProductCategories(Category)) before the existence check.

Confidence: medium

Repro and layer are unambiguous, but the same through-rewrite code path was deliberately narrowed in #3109 to avoid expanding shortcut through-chains during include (the comment at sql.cfc:1207-1212 calls this out explicitly) — so re-enabling shortcut expansion without re-breaking #3109 is a genuine association-resolution design trade-off, not a mechanical one-liner.

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

[wheels-bot]

Wheels Bot — Fix proposed

Draft PR: #3209

Spec: vendor/wheels/tests/specs/model/hasManyShortcutSpec.cfc — a new issue #3208 block asserts a hasMany shortcut name expands to its nested bridge include (teams → memberTeams(team), squads → rosterSpots(squad)) and eager-loads the far side without throwing.
Implementation: vendor/wheels/model/sql.cfc — $expandThroughAssociations now resolves a shortcut name (not a this-model association) into <assocName>(<ListFirst(through)>). The issue #3109 narrowing is preserved.

Note on local validation: tools/test-local.sh could not be executed in the bot sandbox (the wheels CLI is not installed here, so the test server cannot start). The failing-spec → passing-spec cycle was reasoned through against the existing many-to-many fixtures rather than run locally. CI (bot-tdd-gate.yml + the cross-engine compat-matrix.yml) is the validating gate — a human must confirm the suite is green before merge.

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.