fix(ngx): gate native operations against concurrent shutdown

Author: abc354402600

.github/workflows/just_build_no_signature.yml

@@ -133,7 +133,7 @@ jobs:
             & $env:ComSpec /d /c $command
             if ($LASTEXITCODE) { throw "Compatibility guard test failed: $name" }
         }
-        foreach ($script in @('test_shutdown_routing.py','test_provider_publication_routes.py','test_provider_dll_boundary.py','test_combo_release.py')) {
+          foreach ($script in @('test_shutdown_routing.py','test_provider_publication_routes.py','test_provider_dll_boundary.py','test_combo_release.py','test_native_operation_routes.py')) {
             $command = 'call "' + $vcvars + '" && python tests\' + $script + ' --compiler cl'
             & $env:ComSpec /d /c $command
             if ($LASTEXITCODE) { throw "Compatibility routing test failed: $script" }

OptiScaler/NVNGX_Parameter.h

@@ -275,7 +275,7 @@ bool TryDestroyNGXParameters(NVSDK_NGX_Parameter* InParameters, PFN_DestroyNGXPa
             LOG_INFO("Calling NVFree");
             result = NVFree(InParameters);
             LOG_INFO("Calling NVFree result: {0:X}", (UINT) result);
-            return true;
+            return result == NVSDK_NGX_Result_Success;
         }
         else
             return false;

OptiScaler/proxies/NVNGX_Proxy.h

@@ -847,51 +847,61 @@ class NVNGXProxy
 
     static PFN_D3D12_DestroyParameters D3D12_DestroyParameters()
     {
-        if (!IsDx12Inited())
-            return nullptr;
-
-        return _module.D3D12_DestroyParameters;
+        // Availability is stable; admission is checked when the pointer is called.
+        // This also protects pointers cached before a concurrent shutdown.
+        return _module.D3D12_DestroyParameters ? +[](NVSDK_NGX_Parameter* InParameters) -> NVSDK_NGX_Result
+        {
+            return _dx12Devices.RunOperation(NVSDK_NGX_Result_FAIL_NotInitialized,
+                [&] { return _module.D3D12_DestroyParameters(InParameters); });
+        } : nullptr;
     }
 
     static PFN_D3D12_CreateFeature D3D12_CreateFeature()
     {
-        if (!IsDx12Inited())
-            return nullptr;
-
-        return _module.D3D12_CreateFeature;
+        // Availability is stable; admission is checked when the pointer is called.
+        // This also protects pointers cached before a concurrent shutdown.
+        return _module.D3D12_CreateFeature ? +[](ID3D12GraphicsCommandList* InCmdList, NVSDK_NGX_Feature InFeatureID,
+                                                    NVSDK_NGX_Parameter* InParameters, NVSDK_NGX_Handle** OutHandle) -> NVSDK_NGX_Result
+        {
+            if (!OutHandle)
+                return NVSDK_NGX_Result_FAIL_InvalidParameter;
+            *OutHandle = nullptr;
+            return _dx12Devices.RunOperation(NVSDK_NGX_Result_FAIL_NotInitialized,
+                [&] { return _module.D3D12_CreateFeature(InCmdList, InFeatureID, InParameters, OutHandle); });
+        } : nullptr;
     }
 
     static PFN_D3D12_EvaluateFeature D3D12_EvaluateFeature()
     {
-        if (!IsDx12Inited())
-            return nullptr;
-
-        return _module.D3D12_EvaluateFeature;
+        // Availability is stable; admission is checked when the pointer is called.
+        // This also protects pointers cached before a concurrent shutdown.
+        return _module.D3D12_EvaluateFeature ? +[](ID3D12GraphicsCommandList* InCmdList,
+                                                      const NVSDK_NGX_Handle* InFeatureHandle,
+                                                      const NVSDK_NGX_Parameter* InParameters,
+                                                      PFN_NVSDK_NGX_ProgressCallback InCallback) -> NVSDK_NGX_Result
+        {
+            return _dx12Devices.RunOperation(NVSDK_NGX_Result_FAIL_NotInitialized,
+                [&] { return _module.D3D12_EvaluateFeature(InCmdList, InFeatureHandle, InParameters, InCallback); });
+        } : nullptr;
     }
 
     static PFN_D3D12_ReleaseFeature D3D12_ReleaseFeature()
     {
-        if (!IsDx12Inited())
-            return nullptr;
-
-        return _module.D3D12_ReleaseFeature;
+        // Availability is stable; admission is checked when the pointer is called.
+        // This also protects pointers cached before a concurrent shutdown.
+        return _module.D3D12_ReleaseFeature ? +[](NVSDK_NGX_Handle* InHandle) -> NVSDK_NGX_Result
+        {
+            return _dx12Devices.RunOperation(NVSDK_NGX_Result_FAIL_NotInitialized,
+                [&] { return _module.D3D12_ReleaseFeature(InHandle); });
+        } : nullptr;
     }
 
     static PFN_D3D12_Shutdown D3D12_Shutdown()
     {
-        if (!IsDx12Inited())
-            return nullptr;
-
-        return _module.D3D12_Shutdown;
+        return _module.D3D12_Shutdown ? +[]() { return ShutdownDx12(nullptr); } : nullptr;
     }
 
-    static PFN_D3D12_Shutdown1 D3D12_Shutdown1()
-    {
-        if (!IsDx12Inited())
-            return nullptr;
-
-        return _module.D3D12_Shutdown1;
-    }
+    static PFN_D3D12_Shutdown1 D3D12_Shutdown1() { return _module.D3D12_Shutdown1 ? &ShutdownDx12 : nullptr; }
 
     // Vulkan
     static bool InitVulkan(VkInstance InInstance, VkPhysicalDevice InPD, VkDevice InDevice,
@@ -994,59 +1004,77 @@ class NVNGXProxy
 
     static PFN_VULKAN_DestroyParameters VULKAN_DestroyParameters()
     {
-        if (!IsVulkanInited())
-            return nullptr;
-
-        return _module.VULKAN_DestroyParameters;
+        // Availability is stable; admission is checked when the pointer is called.
+        // This also protects pointers cached before a concurrent shutdown.
+        return _module.VULKAN_DestroyParameters ? +[](NVSDK_NGX_Parameter* InParameters) -> NVSDK_NGX_Result
+        {
+            return _vulkanDevices.RunOperation(NVSDK_NGX_Result_FAIL_NotInitialized,
+                [&] { return _module.VULKAN_DestroyParameters(InParameters); });
+        } : nullptr;
     }
 
     static PFN_VULKAN_CreateFeature VULKAN_CreateFeature()
     {
-        if (!IsVulkanInited())
-            return nullptr;
-
-        return _module.VULKAN_CreateFeature;
+        // Availability is stable; admission is checked when the pointer is called.
+        // This also protects pointers cached before a concurrent shutdown.
+        return _module.VULKAN_CreateFeature ? +[](VkCommandBuffer InCmdBuffer, NVSDK_NGX_Feature InFeatureID,
+                                                     NVSDK_NGX_Parameter* InParameters, NVSDK_NGX_Handle** OutHandle) -> NVSDK_NGX_Result
+        {
+            if (!OutHandle)
+                return NVSDK_NGX_Result_FAIL_InvalidParameter;
+            *OutHandle = nullptr;
+            return _vulkanDevices.RunOperation(NVSDK_NGX_Result_FAIL_NotInitialized,
+                [&] { return _module.VULKAN_CreateFeature(InCmdBuffer, InFeatureID, InParameters, OutHandle); });
+        } : nullptr;
     }
 
     static PFN_VULKAN_CreateFeature1 VULKAN_CreateFeature1()
     {
-        if (!IsVulkanInited())
-            return nullptr;
-
-        return _module.VULKAN_CreateFeature1;
+        // Availability is stable; admission is checked when the pointer is called.
+        // This also protects pointers cached before a concurrent shutdown.
+        return _module.VULKAN_CreateFeature1 ? +[](VkDevice InDevice, VkCommandBuffer InCmdList,
+                                                      NVSDK_NGX_Feature InFeatureID, NVSDK_NGX_Parameter* InParameters,
+                                                      NVSDK_NGX_Handle** OutHandle) -> NVSDK_NGX_Result
+        {
+            if (!OutHandle)
+                return NVSDK_NGX_Result_FAIL_InvalidParameter;
+            *OutHandle = nullptr;
+            return _vulkanDevices.RunOperation(NVSDK_NGX_Result_FAIL_NotInitialized,
+                [&] { return _module.VULKAN_CreateFeature1(InDevice, InCmdList, InFeatureID, InParameters, OutHandle); }, InDevice);
+        } : nullptr;
     }
 
     static PFN_VULKAN_EvaluateFeature VULKAN_EvaluateFeature()
     {
-        if (!IsVulkanInited())
-            return nullptr;
-
-        return _module.VULKAN_EvaluateFeature;
+        // Availability is stable; admission is checked when the pointer is called.
+        // This also protects pointers cached before a concurrent shutdown.
+        return _module.VULKAN_EvaluateFeature ? +[](VkCommandBuffer InCmdList,
+                                                       const NVSDK_NGX_Handle* InFeatureHandle,
+                                                       const NVSDK_NGX_Parameter* InParameters,
+                                                       PFN_NVSDK_NGX_ProgressCallback InCallback) -> NVSDK_NGX_Result
+        {
+            return _vulkanDevices.RunOperation(NVSDK_NGX_Result_FAIL_NotInitialized,
+                [&] { return _module.VULKAN_EvaluateFeature(InCmdList, InFeatureHandle, InParameters, InCallback); });
+        } : nullptr;
     }
 
     static PFN_VULKAN_ReleaseFeature VULKAN_ReleaseFeature()
     {
-        if (!IsVulkanInited())
-            return nullptr;
-
-        return _module.VULKAN_ReleaseFeature;
+        // Availability is stable; admission is checked when the pointer is called.
+        // This also protects pointers cached before a concurrent shutdown.
+        return _module.VULKAN_ReleaseFeature ? +[](NVSDK_NGX_Handle* InHandle) -> NVSDK_NGX_Result
+        {
+            return _vulkanDevices.RunOperation(NVSDK_NGX_Result_FAIL_NotInitialized,
+                [&] { return _module.VULKAN_ReleaseFeature(InHandle); });
+        } : nullptr;
     }
 
     static PFN_VULKAN_Shutdown VULKAN_Shutdown()
     {
-        if (!IsVulkanInited())
-            return nullptr;
-
-        return _module.VULKAN_Shutdown;
+        return _module.VULKAN_Shutdown ? +[]() { return ShutdownVulkan(nullptr); } : nullptr;
     }
 
-    static PFN_VULKAN_Shutdown1 VULKAN_Shutdown1()
-    {
-        if (!IsVulkanInited())
-            return nullptr;
-
-        return _module.VULKAN_Shutdown1;
-    }
+    static PFN_VULKAN_Shutdown1 VULKAN_Shutdown1() { return _module.VULKAN_Shutdown1 ? &ShutdownVulkan : nullptr; }
 
     static PFN_UpdateFeature UpdateFeature()
     {

OptiScaler/proxies/NativeDeviceLifecycle.h

@@ -7,12 +7,14 @@
 
 // Tracks native Init/Shutdown ownership per API. Callbacks run without the
 // metadata lock. Overlapping/reentrant transitions fail rather than waiting on
-// a native DLL or loader callback. This does not yet lease Evaluate/Create calls.
+// a native DLL or loader callback. Operation admission covers the API as a whole
+// because legacy native handles do not all expose a reliable device association.
 class NativeDeviceLifecycle
 {
     std::mutex _mutex;
     std::unordered_map<const void*, bool> _devices;
     bool _transition = false;
+    size_t _operations = 0;
     const void* _target = nullptr;
     std::atomic_size_t _usable { 0 };
 
@@ -57,6 +59,28 @@ class NativeDeviceLifecycle
         return entry != _devices.end() && entry->second && (!_transition || (_target && device != _target));
     }
 
+    template <typename Result, typename Callback>
+    Result RunOperation(Result unavailable, Callback&& callback, const void* device = nullptr)
+    {
+        {
+            std::scoped_lock lock(_mutex);
+            if (_transition || _devices.empty() || (device && !_devices.contains(device)))
+                return unavailable;
+            ++_operations;
+        }
+        // Native code runs without the metadata mutex, including callbacks.
+        struct Completion
+        {
+            NativeDeviceLifecycle& owner;
+            ~Completion()
+            {
+                std::scoped_lock lock(owner._mutex);
+                --owner._operations;
+            }
+        } completion { *this };
+        return std::forward<Callback>(callback)();
+    }
+
     template <typename Result, typename Callback>
     Result Initialize(const void* device, Result success, Result invalid, Result busy, Callback&& callback)
     {
@@ -68,6 +92,8 @@ class NativeDeviceLifecycle
                 return busy;
             if (_devices.contains(device))
                 return success;
+            if (_operations)
+                return busy;
             // Allocate bookkeeping before the native callback succeeds.
             _devices.emplace(device, false);
             _transition = true;
@@ -96,6 +122,8 @@ class NativeDeviceLifecycle
                 return busy;
             if (device ? !_devices.contains(device) : _devices.empty())
                 return success; // Nothing owned; do not call a native shutdown.
+            if (_operations)
+                return busy; // No waiting or deferred native teardown.
             _transition = true;
             _target = device; // nullptr means all devices in this API.
             UpdateUsable();

docs/CODEX_HANDOFF.md

@@ -36,3 +36,5 @@ The 2026-09-17 continuation fixes private provider construction/publication and
 The same continuation also initializes DLL-provider depth pointers, guards missing per-operation exports (69 extracted checks), and fixes Combo partial-release ownership/retry (44 checks). See the same publication audit for limitations; this does not establish native API/device shutdown safety or game compatibility.
 
 Latest validated code checkpoint: e737b087 (Windows build 35129887577 and format 35129887470 succeeded; 171 new publication/export/Combo checks passed). The publication audit records remaining native shutdown/device ownership findings, including the separate DLSSFeatureDx12 nested native-shutdown route; continue there rather than repeating these completed fixes.
+
+The next checkpoint `3df84993` fixes native D3D12/Vulkan device-specific Init/Shutdown and removes the nested DLSSFeatureDx12 native shutdown. Windows build `35188944901` and format `35188944895` succeeded; 37 device and 43 extracted shutdown checks passed. See [native lifecycle audit](NATIVE_DEVICE_LIFECYCLE_20260917.md), including the operation-admission follow-up, test counts and exact remaining boundaries. Do not restart this ownership work or rerun unrelated installer suites. The latest user explicitly permits aurora synchronization after code/review/build completion without waiting for game tests; remaining lifecycle boundaries must still be resolved or explicitly scoped before that gate is met.

docs/NATIVE_DEVICE_LIFECYCLE_20260917.md

@@ -24,3 +24,19 @@ This is an Init/Shutdown ownership checkpoint, not full concurrent operation adm
 Replacement FG providers have separate device/handle ownership and shutdown semantics, not covered by this native registry. Outer adapters still ignore their shutdown result. Global module loading, mutable shared depth/HUD resources and general State/Config ownership are not solved here. Aurora still has a single current-device cache; native multidevice bookkeeping does not make every renderer feature multidevice-safe. The process-exit skip intentionally leaves native bookkeeping until DLL teardown.
 
 The user has deferred real-game validation and authorized synchronization to aurora after code work/review/build completion. Remaining lifecycle work means that gate has not yet been reached. No main-branch merge or Release is performed by this checkpoint.
+
+## Init/Shutdown checkpoint validation
+
+Commit `3df849934112a115ef09fa280ffe810337b4042c` was pushed to Compatibility-fixes. [Windows DLL build, CPU checks and package](https://github.com/abc354402600/OptiScaler-Aurora/actions/runs/35188944901) and [incremental format](https://github.com/abc354402600/OptiScaler-Aurora/actions/runs/35188944895) succeeded. Job `105097010598` confirms 37 device checks and 43 shutdown checks passed. Artifact `OptiScaler_Aurora_v1.0_20260917_compat_3df84993.7z` was uploaded (ID `10484080454`, 234774490 bytes).
+
+## Native operation admission follow-up
+
+Nine D3D12/Vulkan Create/Evaluate/Release/DestroyParameters getters now return same-signature guarded entry points rather than raw native pointers. Export availability is stable after module initialization; readiness is checked at invocation, including when a caller cached a pointer before shutdown. Create outputs are cleared on rejected admission, and Vulkan CreateFeature1 additionally verifies its explicitly supplied device. Shutdown getters also route through the ownership helper so callers cannot bypass it.
+
+An operation briefly increments an API-local active count and releases the metadata mutex before foreign code. Init of a new device and owned-device/global Shutdown reject while that API has active guarded calls. During a transition new calls are rejected. Exceptions unwind the active count. There is no wait across a native callback and no deferred teardown. Calls on another API remain independent. This is conservatively API-wide because legacy native handle and command-buffer routes do not expose complete device/generation ownership; it does not pretend those associations have been solved.
+
+The changed Busy return exposed an existing bug in TryDestroyNGXParameters: it returned true even if native DestroyParameters failed. It now reports success only for native Success, preserving the existing internal-table deletion and unknown-table policy.
+
+Focused tests now contain **55 device/admission checks** (18 added) and **236 new extracted-operation/parameter-destruction checks** covering all nine actual getters, cached pointers before/during/after shutdown, callback reentry, output clearing, absent exports, explicit unknown Vulkan device, retries, both shutdown getters and native destroy failure. The existing 43 shutdown routing checks were rerun because the shared lifecycle header changed; they passed. Local checks use counted native stand-ins. Cumulative MSVC validation will be recorded after this follow-up is pushed.
+
+Still open: calls bypassing these getters, parameter acquisition/query routes, old native handles after a device generation closes/reopens, D3D11, replacement-provider lifecycle, and global module publication. Existing higher-level owners may discard resources after a failed release; no general ownership redesign is claimed. These checks do not establish in-game behavior or complete the main-branch merge gate.