Enterprise API Audit — Public API Cleanup

[kolkov]

Enterprise API Audit — wgpu Public API Cleanup

Tracking issue for wgpu public API improvements identified during enterprise audit (Flutter embedding scenario, @lkmavi) and cross-validation (3 research agents).

HAL Leaks in Public API

These force users to import wgpu/hal or wgpu/core — breaking the abstraction that consumers only need root wgpu package.

• Surface.HAL() returns hal.Surface (surface_native.go:245) — replace with specific methods or unexport
• Surface.SetPrepareFrame() takes core.PrepareFrameFunc (surface_native.go:182) — define callback type in root package

Missing Public API Methods

HAL implementations exist but public wrappers don't — consumers must drop to device.HalDevice().

• Device.CreateQuerySet — HAL ready on all 6 backends (Vulkan, DX12, Metal, GLES, Software, Noop)
• Device.CreateRenderBundleEncoder — HAL partially ready (Vulkan)
• Device.GetTextureFormatFeatures — per-format capability query (filterable, blendable, MSAA)

Type Cleanup

• MaxBindGroups = 8 — added MinBindGroups = 4 (v0.30.0)
• StencilOperation = hal.StencilOperation alias — moved to gputypes.StencilOperation (v0.30.0, BREAKING)

v1.0 Planning: Type Aliases

31 type X = gputypes.X aliases + 46 const re-exports + hal/core aliases in types.go/error.go/descriptor.go. Per Go proposal #18130: type aliases are for gradual code repair during migration, not permanent re-export. go doc shows type TextureFormat = gputypes.TextureFormat — confuses users about canonical import path.

46 const re-exports (BufferUsageVertex = gputypes.BufferUsageVertex etc.) also inflate the API surface. No Go style guide recommends or condemns this pattern — it's a grey area. For enterprise quality: users should import gputypes directly for all shared types and constants, wgpu only for wgpu-specific types (Device, Queue, Buffer, etc.).

Proposal for v1.0: remove all type aliases AND const re-exports. Canonical import path: gputypes for shared types/constants, wgpu only for wgpu-specific resources (Device, Queue, Buffer, etc.). Breaking change — migration guide needed.

@lkmavi — you raised this in the enterprise audit. Do you agree with removing both type aliases and const re-exports for v1.0, or do you see cases where const re-exports should stay?

Thread Safety

Audit of concurrent access patterns:

• Device.released → atomic.Bool (v0.30.0)
• Surface has no synchronization — Configure/GetCurrentTexture/Present must be called from single goroutine. Document this constraint explicitly
• GLES Linux lacks AdapterContext (tracked separately as FEAT-GLES-003) — no mutex, no LockOSThread on Device/Queue. Windows GLES has proper AdapterContext pattern

Queue, Buffer.Release, DestroyQueue, CommandEncoder — all properly synchronized.

Cross-repo coordination (related to wgpu API decisions)

These live in other repos but are directly affected by wgpu API changes:

• gogpu Context.SurfaceView() returns *wgpu.TextureView (gogpu/context.go:178) — forces gogpu consumers to import wgpu. Should return gpucontext.TextureView (opaque handle). Blocked until wgpu API is stabilized.
• gogpu DeviceProvider returns *wgpu.Device (gogpu/device_provider.go:14) — duplicate of gpucontext.DeviceProvider. Should be deprecated. Consumers use provider.Device().(*wgpu.Device) type assertion when HAL access needed.
• gpucontext.AdapterInfo (2 fields) vs gputypes.AdapterInfo (8 fields) — triple definition (gputypes original, wgpu alias, gpucontext subset). Consumers must convert manually. Unify or document canonical source.
• gg type-asserts provider.Device().(*wgpu.Device) (gg/accelerator.go:137, gg/gpu/gpu.go:46) — if wgpu removes type aliases or changes Device type, gg breaks. Migration guide must cover gg/ui/Born ML.

References

• @lkmavi enterprise API audit (Flutter embedding scenario)
• Internal ADR-018 (opaque handle design)

[kolkov]

v0.30.0 Progress Update

The following items from this audit are now resolved in v0.30.0:

Completed

• ✅ StencilOperation — moved from hal.StencilOperation (uint8, 0-based) to gputypes.StencilOperation (uint32, webgpu.h spec values). Both native and browser now use canonical gputypes definition. BREAKING: numeric values changed.
• ✅ MaxBindGroups — added MinBindGroups = 4 (WebGPU spec guaranteed minimum) alongside existing MaxBindGroups = 8 (HAL hard cap).
• ✅ Device.released data race — changed from plain bool to atomic.Bool. Matches Buffer.released pattern.
• ✅ API unification (ADR-047) — 6 divergences between native/browser fixed:
  • Browser fence stubs (DestroyFence, ResetFence, GetFenceStatus, WaitForFence)
  • Native CopyBufferToTexture + ClearBuffer (WebGPU spec methods)
  • Browser ComputePipelineDescriptor missing fields (Constants, ZeroInitializeWorkgroupMemory)
  • gpucontext sentinel methods on type token interfaces (gpucontext v0.20.0)

Remaining

• Surface.HAL() returns hal.Surface — remove or unexport
• Surface.SetPrepareFrame() takes core.PrepareFrameFunc — define callback type in root package
• Device.CreateQuerySet public wrapper
• Device.CreateRenderBundleEncoder public wrapper
• Device.GetTextureFormatFeatures public wrapper
• Type aliases (31 type + 46 const) — v1.0 planning
• Surface single-thread requirement documentation
• Cross-repo coordination items (gogpu SurfaceView, DeviceProvider, AdapterInfo)