docs(web/guides): fix singleton cache keying and case-sensitive name claims in DI usage guide

[wheels-bot]

Two factual errors in the DI usage guide have been corrected. The singleton cache is keyed by binding name (not component path), and re-binding a name to a different path is what triggers cache invalidation — the guide had these backwards. The "binding names are case-sensitive" bullet was false: CFML struct keys are case-insensitive on Lucee, Adobe CF, and BoxLang, so service("EmailService") and service("emailService") resolve to the same binding; the bullet is replaced with the actual failure modes (typo in name, container wiped after a boot error).

Fixes #3117

Changes

• dependency-injection-usage.mdx line 67: reword singleton-swap explanation to state alias-keyed caching and different-path invalidation correctly.
• dependency-injection-usage.mdx line 244: replace the false case-sensitivity bullet with a correct note on CFML struct key case-insensitivity and real resolution failure modes.
• changelog.d/3117-di-guide-mechanics.fixed.md: fragment documenting the correction.

Screenshots needed

None.

[wheels-bot]

Wheels Bot — Reviewer

TL;DR: This PR corrects two factual errors in the DI usage guide (singleton cache keying and the false case-sensitivity claim), and both corrections check out against the actual Injector.cfc source. Verdict: comment — the substance is correct and well-evidenced; one minor docs nit about how the new text scopes issue #3061.

Verification performed

Both factual claims were verified against vendor/wheels/Injector.cfc rather than taken on faith:

1. Singleton cache keyed by binding name — confirmed. Injector.cfc:25-30 documents the cache as "mapping name → instance" and explicitly describes per-component-path keying as the old, fixed behavior. Injector.cfc:97-108 shows to() deleting the cached instance only when re-binding the alias to a different component path ("Re-binding an alias to a DIFFERENT component path invalidates any cached singleton instance for that alias"). The new guide sentence at dependency-injection-usage.mdx:67 matches this mechanism exactly, and the test-fake prescription (distinct fake path) remains correct because the different-path re-bind is precisely what triggers the invalidation. Behavioral pin exists at vendor/wheels/tests/specs/di/InjectorLifecycleSpec.cfc.

2. Case-insensitive binding names — confirmed. The mapping, singleton, and flag stores are plain CFML struct literals (Injector.cfc:23,30,33) resolved via structKeyExists (Injector.cfc:168,185,283,319). Default struct keys are case-insensitive on Lucee, Adobe CF, and BoxLang, so the old bullet ("service("EmailService") and service("emailService") are different keys") was false and actively misleading for debugging. The replacement is accurate.

Docs

• dependency-injection-usage.mdx:244 — the #3061 citation under-scopes the issue. The new bullet says "a thrown error during app start can wipe the container — see [#3061]". Issue #3061's actual scope is broader and arguably more relevant to a debugging checklist: onError() unconditionally re-creates the container on any uncaught error, and the issue's repro is a routine development-mode 404 (Wheels.RouteNotFound) after a successful boot wiping all services.cfm registrations. A reader whose services stopped resolving mid-session after a stray 404 won't connect that to "an error during app start." Suggested wording: "…or the container was wiped by an uncaught error — any error page, even a routine dev-mode 404, currently re-creates the container and discards services.cfm registrations (see [#3061]); reload after fixing." Non-blocking — the current text isn't false (boot errors are one instance of the bug), just narrower than the issue it cites.

Commits

Clean. Single commit docs(web/guides): fix singleton cache keying and case-sensitive name claims in DI usage guide — valid type, suggested monorepo scope, header under 100 chars, DCO sign-off matches the committing bot identity.

Changelog

Fragment present and correctly formed: changelog.d/3117-di-guide-mechanics.fixed.md uses the fixed type and contains a complete bullet line — no direct CHANGELOG.md edit.

No correctness, cross-engine, security, or test findings — this is a two-line prose change to a guide plus a changelog fragment, with no executable code touched. The only versioned guide tree is v4-0-0 (no snapshot copy exists to sync).

[bpamiri]

Superseded by #3130 (merged 7fae2a3) — same two dependency-injection-usage.mdx findings fixed there; issue #3117 closed with it.