[S3-012] Honor native Vulkan image bounds and qualify Android surface lifecycle

Parent: https://github.com/craft-native/craft/issues/393 Related owned-emulator cancellation source: https://github.com/craft-native/craft/issues/434

Observable defect

The maintained public craft.vulkan_surface.Surface.resize(160,120) returns 256x192 after a real Android SurfaceView resize. The callback, View measured size, SurfaceHolder frame, retained ANativeWindow and freshly acquired current-Surface window all report 160x120, and the native window identity remains the same. The shared consumer then rejects the actual extent mismatch.

Craft selects every non-sentinel currentExtent as mandatory. Android WSI defines it as the consumer preferred size and permits image extents within the surface min/max image bounds. AOSP obtains currentExtent from cached default dimensions, while live native-window dimensions query the producer. A controlled diagnostic retained the original failure: one legitimate 256x192 presentation plus complete GPU readback refreshed that cache, and one subsequent observation returned 160x120. This diagnostic is not an acceptance recovery and will not be retained as a retry.

Primary contracts:

• Android WSI
• Swapchain extent bounds, VUID 07781
• AOSP cached default dimensions
• AOSP queue-cache refresh

Owning source change

Select requested swapchain pixel dimensions clamped to the driver's min/max image extents. Fixed desktop min=max bounds still force the native desktop extent. Preserve all buffer/image limits, exact error propagation, creating-thread ownership and 1000ms command timeout. No polling, reconnect workaround or test-only resize retry.

Add the missing maintained Android Activity/JNI/SurfaceHolder consumer of the unchanged public source package. Exercise actual Choreographer frames, native control input, real View resize, Home/background and foreground surface recreation, and two complete Activity sessions.

Acceptance

• Pure extent-policy regression fails before the repair; fixed desktop bounds, flexible/stale preferred extents and lower/upper clamping pass afterward.
• Actual Android software-Vulkan run draws at least 370 GPU-checked frames across at least 4 real native sessions, with two native pointer events and complete disposal.
• Five actual compositor captures match every shared-scene pixel and independent literal atlas/triangle/glyph/changed-frame/input anchors; blank rendering cannot pass.
• Preserve 256x192 then 160x120 View extents, 61-frame/30-second stage limits and 1000ms native command budgets.
• Rerun the same strict candidate on Android 35 Google APIs revision 9 and default revision 2; retain truthful separate outcomes. The original default image's external-fence wait worker completes promptly but outer driver wait often returns about 1 second later, and remains a separate compatibility/qualification gate.
• Maintain CI invocation/path filters/original artifacts, exact source/compiler/NDK/Gradle/emulator/image/APK/library/capture identities and owned process cleanup.
• Run owner checks and independent review. Release changed source through bun run release:patch, verify published artifacts and coordinate downstream adoption.

Retained initial evidence

Inspected baseline 31d8891; Android NDK 27.2.12479018, Gradle 8.11.1, pinned Zig 0.18.0-dev.146+35accc0, Android emulator 37.2.13 build 16740729, hardware CPU virtualization and software Vulkan llvmpipe LLVM 21.1.4.

Local original receipts: /tmp/craft-vulkan-android-acceptance/run-BvFcVv (all resize dimensions) and run-2uJmh0 (diagnostic queue/cache observation, deliberately failed). The canonical retained CI receipts and implementation/release SHAs will replace local-only evidence during delivery.

This issue is a narrow source/native-host slice. It does not establish physical GPU/device execution, full native game rendering, Gold fidelity or completion of parent #393.

The source repair and maintained Android host candidate now have actual local execution evidence. No observation-only retry/polling code remains.

• Pure extent policy: the Android preferred-extent and flexible-bound regressions failed before the repair; all 13 Vulkan ownership/extent tests pass afterward. Fixed desktop min=max bounds retain the native extent.
• Android 35 Google APIs arm64 revision 9 passed exactly 370 real GPU-checked frames, four native sessions, two native pointer events, two Activities and five full compositor captures. Independent literal atlas/triangle/glyph, changing-frame and touch/ring assertions passed. Native owners, emulator, workspace and every process group disposed successfully.
• The unchanged candidate on Android 35 default arm64 revision 2 failed its original initial stage at 31 frames/30 seconds, with approximately 984ms presentation latency. That separate open qualification gate is #437. No failed image row is hidden or admitted.
• Every consumed source-file hash and all decompressed public archive bytes match between rows. Tar SHA256: ad6fea1c71fbf8ca32702139506418f0d027bb0d67667a1deea730e71f1f6bc0. Original gzip archives/APKs/library/toolchain/image/captures remain retained separately.
• Public CLI preflight regressions reproduced invalid-image workspace leakage and unprotected workspace-allocation failure, then passed after owned setup moved inside protected cleanup.

Owner checks completed: SDK 836 passed/10 platform skips/0 failed; Android 207 passed/0 failed; release rehearsals 419 passed; focused CI/protocol/native-scope contracts 455 passed; package builds and all 43 publish-surface checks passed; full/focused type checks, pinned Zig format, fresh public archive consumer and pickier passed (0 errors, 26 existing warnings).

The maintained mobile workflow now selects and requires the Android Vulkan job for normal/all/android scopes and has a focused android-vulkan scope. It pins the NDK/compiler/Gradle contract, retains original artifacts and rejects failed/skipped selected native work. Local macOS arm64 evidence does not establish Linux x86 CI or physical-device qualification. Independent review, exact-source CI, source commits/publication and coordinated downstream adoption remain open delivery gates; this issue and parent #393 remain open.

Local original receipts: /tmp/craft-vulkan-android-acceptance/run-Wk0UjT and run-diL5If, with their full paired audit in /tmp/craft-vulkan-final-image-matrix.json. Canonical implementation/release/CI links will be added after delivery.

Pushed reviewed source normally to origin/main as Chris, without coauthors:

• cf8b31faeb521c635755f5c32a7aeabe6c974211: select requested Vulkan extents within the native image bounds.
• fd55fd116d709de4cf894a7becd1dd01bb0a0e92: maintained Android public-package consumer, Activity/JNI lifecycle, real input, GPU/compositor checks and required CI.

Actual macOS arm64 / Android 35 Google APIs revision 9 run passed exactly 370 GPU-checked frames, four native sessions, two real pointer events and five independently anchored complete compositor captures. All command groups, emulator and workspace were disposed. Root independently verified the 19 consumed source hashes against the final implementation and all original capture hashes/dimensions, and inspected the real input capture. The paired default revision 2 run used identical consumed source and decompressed public archive bytes but failed at 31 frames within the original 30-second limit. Its separate compatibility gate is #437. No retry, polling or budget increase was retained.

Owner checks passed: 836 SDK cases (10 explicit platform skips), 207 Android cases, 419 release tests, 455 CI/protocol contracts, full/focused types, package builds and 43 surface checks, fresh source consumer, pinned formatting and lint (zero errors, 26 existing warnings). Independent Spec and Standards review passed.

Exact-source CI 41399694295 and Mobile 41399694475 are pending. This is source/local native qualification, not published package or physical-device/game parity evidence. The issue remains open for hosted qualification, canonical patch release, artifact verification and downstream adoption.