Release stamping clobbers PackageLoader's "@build.version@" sentinel — wheelsVersion constraint enforcement silently disabled on every released build

[bpamiri]

Problem

vendor/wheels/PackageLoader.cfc ($normalizeWheelsVersion(), develop line ~1369) guards against unstamped dev builds with a literal comparison:

if (local.raw == "@build.version@" || local.raw == "0.0.0-dev") {
    return "0.0.0";
}

tools/build/scripts/prepare-core.sh sed-substitutes @build.version@ across every .cfc in the artifact, so the shipped 4.0.3 ForgeBox/release artifact contains:

if (local.raw == "4.0.3" || local.raw == "0.0.0-dev") {
    return "0.0.0";
}

(verified by extracting the published wheels-core 4.0.3 zip). On a released build the real runtime version is exactly 4.0.3, so it normalizes to 0.0.0 and $isCompatibleVersion() then takes the "unstamped dev build → skip enforcement" branch for every package. Net effect: wheelsVersion constraints in package.json manifests are never enforced on any released Wheels build — a package declaring "wheelsVersion": ">=5.0" loads silently on 4.0.3. (The comment line above the guard gets stamped too, which is cosmetic but confirms the blast radius.)

Fix

Use a sed-safe structural check instead of the literal placeholder, mirroring what BuildInfo.cfc already does (its detection is left(v, 7) == "@build." && right(v, 1) == "@" precisely so global stamping can't break it — see the regression-guard spec in tests/specs/buildInfoSpec.cfc). E.g.:

if ((Left(local.raw, 7) == "@build." && Right(local.raw, 1) == "@") || local.raw == "0.0.0-dev") {
    return "0.0.0";
}

Also worth a build-time sanity check in prepare-core.sh (like the existing BuildInfo commitSubject check) asserting PackageLoader.cfc does not contain a stamped self-version sentinel.

Affected artifacts: at minimum 4.0.0–4.0.3 releases (4.0.3 verified directly).

🤖 Generated with Claude Code

[wheels-bot]

Wheels Bot — Triage

Classified as bug.

The report describes observable wrong behavior with a verified root cause: release stamping in tools/build/scripts/prepare-core.sh sed-substitutes @build.version@ across every .cfc, including the literal sentinel guard in PackageLoader.cfc::$normalizeWheelsVersion(). On a shipped build the guard becomes local.raw == "4.0.3", so the real runtime version normalizes to 0.0.0 and $isCompatibleVersion() then takes the dev-build skip branch — silently disabling wheelsVersion enforcement for every package on every released build (4.0.0–4.0.3, 4.0.3 verified by extracting the published artifact).

Suspected layer

config — package loading runs at app startup via PackageLoader.cfc. There is no dedicated package-system doc under .ai/wheels/; the package-system invariants live in the project CLAUDE.md "Package System" section.

Fix sketch

Two files. In vendor/wheels/PackageLoader.cfc ($normalizeWheelsVersion(), ~line 1369), replace the literal local.raw == "@build.version@" check with a sed-safe structural one, mirroring the structural detection in BuildInfo.cfc (Left(v, 7) == "@build." && Right(v, 1) == "@"), which is deliberately structural precisely so global stamping cannot break it. Second, add a build-time sanity assertion in prepare-core.sh — like the existing BuildInfo commitSubject check — that fails the build if PackageLoader.cfc contains a stamped self-version sentinel. A regression-guard spec analogous to tests/specs/buildInfoSpec.cfc would lock it in.

Confidence: high

The report has a clear what-happened/what-expected, the layer and target files are unambiguous, the fix shape is mechanical (one-line structural check plus a build-time guard), and there is direct prior art (BuildInfo.cfc) to copy; the structural check uses only Left/Right, so no cross-engine concern fires.

<!-- wheels-bot:triage:3178 -->
<!-- wheels-bot:triage-class:bug -->
<!-- wheels-bot:triage-confidence:high -->

[wheels-bot]

Wheels Bot — Fix proposed

Draft PR: #3189

Spec: vendor/wheels/tests/specs/packages/PackageLoaderVersionStampSpec.cfc — failing → passing (source-scan regression guard mirroring buildInfoSpec.cfc: PackageLoader.cfc held 2 @build.version@ literals before the fix, 0 after).
Implementation: vendor/wheels/PackageLoader.cfc (structural placeholder detection, mirroring BuildInfo.cfc::isDev()) + tools/build/scripts/prepare-core.sh (build-time sanity check that fails if a stamped self-version sentinel reappears).

Note: the HTTP TestBox harness could not run in the bot sandbox (the wheels CLI / Lucee runtime is not installed here, so tools/test-local.sh cannot start its server). The genuinely-failing assertion is a pure source scan, verified deterministically via the spec's own logic; CI runs the full suite across every engine × DB.

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.

[bpamiri]

Fixed on develop by #3194 (merged): the version sed in prepare-core.sh is narrowed to BuildInfo.cfc's version field only, so PackageLoader.cfc's @build.version@ sentinel comparison is no longer clobbered.