ENG2-P9-04: Console targets: experimental feature-gate, dedupe 3×323-line init copies, strategy record (#135)

[aram-devdocs]

Parent

• Program: ENG2 — GoudEngine v2 Rebuild (see the pinned master tracking issue)
• Phase / Milestone: Phase 9 — Authoring, Platforms, Examples & Polish (eng2-p9-authoring)
• Batch / Group: Batch 9.1 — Platforms & tooling (4 groups, parallel), Group C
• Runbook spec: docs/src/runbook/phases/phase-9.md (committed with the roadmap)

Summary

Turn the console (Vulkan/Xbox GDK) targets into an explicit experimental feature-gate, deduplicate the three byte-near-identical 323-line backend-init copies, and record the console-support strategy as a decision.

Architecture Context

Layer: Layer 2 (Libs) — libs/graphics/backend/ platform-init modules. (see tools/lint_layers.rs — downward-only deps).
Modules/types touched:

• goud_engine/src/libs/graphics/backend/switch_vulkan_platform.rs:52-57 — honest PoC stub; gate behind an explicit experimental-console feature.
• goud_engine/src/libs/graphics/backend/xbox_gdk_platform.rs:55-56 — honest PoC stub; same treatment.
• The three wgpu backend-init files (byte-near-identical, ~323 lines each) — extract shared init logic into one function/module the platform-specific files call into.

Boundary constraints (only those that apply):

• Raw GPU calls stay in libs/graphics/backend/ — no wgpu::/gl:: outside it.
• Console-specific code stays behind the new experimental-console feature gate; it must not be part of any default build.

Pattern to follow: Existing default-feature wgpu backend init (the non-console file in the same trio) is the canonical init sequence the shared-extraction targets; console files call into it plus their platform-specific delta.

Scope

• Extract the shared logic across the three ~323-line wgpu init files into one common function/module.
• Gate Switch/Vulkan and Xbox GDK platform code behind an explicit experimental-console Cargo feature (off by default).
• Add a CI typecheck-only lane for the experimental-console feature (build/typecheck, not full test, given no console hardware in CI).
• Record the console-support strategy decision (feature-gated/experimental, not first-class) in a decision doc (closes F20: Console Strategy #135).
• Tests: spec test at goud_engine/tests/spec/ + unit/isolation coverage for the new code paths.
• Docs/rules updates if this invalidates .agents/rules/* or docs/src/*.

Acceptance Criteria

• The three init files' shared logic is extracted to one location; each platform file's remaining unique code is the platform-specific delta only (grep/line-count-gated reduction from the current ~323×3 duplication).
• experimental-console feature exists, is off by default, and has a required CI typecheck lane.
• F20: Console Strategy #135 closed with a written strategy record referenced from the issue.
• cargo check && cargo fmt --all -- --check && cargo clippy -- -D warnings clean; cargo test green; ./codegen.sh && git diff --exit-code (drift gate)

Breaking Change & Throne Follow-up

None — console code is already non-functional PoC stubs; feature-gating and dedup do not change any shipped default-build behavior.

Blocked By

None.

Files Likely Touched

• New/Modified/Generated: goud_engine/src/libs/graphics/backend/switch_vulkan_platform.rs, goud_engine/src/libs/graphics/backend/xbox_gdk_platform.rs, the third wgpu backend-init file, Cargo.toml (new experimental-console feature), .github/workflows/*.yml (new typecheck lane), a strategy decision doc

Agent Notes

• Confirmed by direct read: switch_vulkan_platform.rs:52-57 and xbox_gdk_platform.rs:55-56 are honest PoC stubs — not disguised as working console support. The three wgpu backend-init files are byte-near-identical at ~323 lines each; this issue's dedup target is that shared block, not a rewrite of the init sequence itself.
• This issue is explicitly about honesty and maintainability (experimental-gate + dedup + a recorded decision), not about making console targets functionally complete — do not scope-creep into real console bring-up.

Verification

cargo check && cargo fmt --all -- --check && cargo clippy -- -D warnings
cargo test
./codegen.sh && git diff --exit-code