architecture: move ALL implementation to internal/ (ADR-070) #329

Summary

Move ALL implementation to internal/ — keep thin public adapter packages for backward compatibility. Zero breaking changes for ecosystem repos.

Principle: if implementation CAN be hidden — it MUST be hidden.

Current problem

38 public packages on pkg.go.dev. 14,753 LOC of implementation in root package. Backend implementation details publicly importable.

Approach: Thin Adapters + Internal Implementation

NOT a "move everything and break consumers" migration. Public packages stay but become thin adapters. Implementation moves to internal/.

Public (thin, stays):               Internal (implementation):
wgpu/                                wgpu/internal/
├── *.go (~2-3K LOC thin)            ├── hal/vulkan/    ← actual 15K LOC
├── hal/                             ├── hal/dx12/      ← actual 12K LOC
│   ├── vulkan/init.go (registration)├── hal/metal/     ← actual 8K LOC
│   ├── metal/init.go                ├── hal/gles/      ← actual 10K LOC
│   ├── dx12/init.go                 ├── hal/software/  ← actual 8K LOC
│   ├── gles/init.go                 ├── core/          ← actual 13K LOC
│   └── allbackends/                 ├── device/        ← from root
├── core/ (thin re-exports)          └── ...
└── docs/

Who imports what (verified)

• gogpu: _ "github.com/gogpu/wgpu/hal/vulkan" — blank import for registration → init.go stays public, keeps working
• gg: import "github.com/gogpu/wgpu/core" — typed GPU operations → thin re-exports stay public, keeps working
• ui, g3d, naga: no hal/core imports

Migration plan (3 PRs)

Result

• pkg.go.dev: ~5 clean packages instead of 38
• Root package: ~2-3K LOC (types + delegation)
• Zero runtime overhead (Go inlines)
• Zero breaking changes for ecosystem

ADR

Architecture Decision Record: ADR-070