@photostructure/fs-metadata 1.3.0 → 1.4.1

package/doc/C++_REVIEW_TODO.md

@@ -142,12 +142,10 @@ This document outlines a comprehensive review of all C++ files in the fs-metadat
 
 - [x] Review BlkidCache RAII wrapper - Already excellent
 - [x] Check blkid_get_tag_value free() calls - Correctly using free()
-- [x] Verify GIO integration memory management - Proper smart pointers
 - [x] Validate statvfs error handling - Already comprehensive
 - [x] **Added**: Input validation for empty mount points
 - **Platform APIs verified**:
   - libblkid API availability
-  - GIO optional dependency handling
   - statvfs behavior
 
 #### `src/linux/blkid_cache.cpp` ✅
@@ -159,38 +157,8 @@ This document outlines a comprehensive review of all C++ files in the fs-metadat
 - **Platform APIs verified**:
   - libblkid cache APIs - Proper use of blkid_get_cache/blkid_put_cache
 
-#### `src/linux/gio_utils.cpp` (if GIO enabled) ✅
-
-- [x] Review g_object_unref patterns - Already using GioResource RAII
-- [x] Check GError cleanup - Not used in this file (GError-free patterns)
-- [x] Verify GMount/GVolume reference counting - Proper ref/unref pairs
-- [x] **Added**: Exception handling in forEachMount callback
-- [x] **Added**: Null checks for root.get() before G_IS_FILE
-- [x] **Added**: const-correctness for GioResource and callback results
-- **Platform APIs verified**:
-  - GLib/GIO APIs (GNOME) - Proper memory management patterns
-  - GVfs mount integration
-
-#### `src/linux/gio_mount_points.cpp` (if GIO enabled) ✅
-
-- [x] Review g_volume_monitor lifecycle - Correct usage (singleton pattern)
-- [x] Check GList cleanup patterns - Using g_list_free_full correctly
-- [x] Verify string ownership - Proper GCharPtr smart pointers
-- [x] **Added**: const-correctness for local variables (GCharPtr, GFileInfoPtr, etc.)
-- **Platform APIs verified**:
-  - GVolumeMonitor APIs - Reference counting rules
-  - Mount enumeration
-
-#### `src/linux/gio_volume_metadata.cpp` (if GIO enabled) ✅
-
-- [x] Review g_drive object management - Using GObjectPtr smart pointers
-- [x] Check g_icon handling - No GIcon usage in this file
-- [x] Verify string ownership - Proper GCharPtr usage
-- [x] **Added**: Defensive null checks for GObjectPtr::get()
-- [x] **Added**: Null checks for string getters
-- [x] **Added**: const-correctness for all GCharPtr and GObjectPtr locals
-- **Platform APIs verified**:
-  - GDrive/GVolume metadata APIs - Ownership transfer rules
+> **Note**: GIO/GLib integration was removed in favor of `/proc/self/mounts`
+> parsing in TypeScript. See CHANGELOG.md for details.
 
 ## Testing Strategy
 
@@ -237,7 +205,7 @@ This document outlines a comprehensive review of all C++ files in the fs-metadat
    - ✅ WNetConnection: Handle ERROR_MORE_DATA with dynamic buffer resize
    - ✅ GetVolumeInformation: Use MAX_PATH+1 instead of BUFFER_SIZE
 3. ~~**High**: CoreFoundation reference counting in macOS code~~ ✅ Completed - CFReleaser RAII wrapper
-4. ~~**High**: GIO object lifecycle management~~ ✅ Completed - Using smart pointers throughout
+4. ~~**High**: GIO object lifecycle management~~ ✅ N/A - GIO integration removed entirely (see CHANGELOG)
 5. ~~**Medium**: Security - Add comprehensive path validation~~ ✅ Completed
    - ✅ Check for ".." in all platforms (Windows/Darwin have it, Linux doesn't have hidden file support)
    - Validate against null bytes and special characters (remaining)
@@ -358,6 +326,5 @@ The Darwin/macOS implementation demonstrates excellent resource management with
 ### Linux
 
 - libblkid: Use free() for blkid_get_tag_value results, blkid_put_cache() for cache
-- GLib/GIO: Use g_object_unref() or g_clear_object(), match allocation functions
 - Key Documentation: libblkid man pages, GNOME Developer Documentation
 - **Review Status**: ✅ All files properly reviewed and use smart pointers

package/doc/LINUX_API_REFERENCE.md

@@ -4,115 +4,10 @@ Reference for Linux APIs used in fs-metadata, with links to official documentati
 
 ## Table of Contents
 
-1. [GIO/GLib APIs](#gioglib-apis)
-2. [libblkid APIs](#libblkid-apis)
-3. [POSIX File System APIs](#posix-file-system-apis)
-4. [RAII Patterns](#raii-patterns)
-5. [References](#references)
-
-## GIO/GLib APIs
-
-### Thread Safety Overview
-
-**Critical**: GIO has different thread safety guarantees for different APIs:
-
-| API                      | Thread Safe? | Used? | Notes                                     |
-| ------------------------ | ------------ | ----- | ----------------------------------------- |
-| `g_unix_mounts_get()`    | Yes          | ✅    | Uses `getmntent_r()` or internal `G_LOCK` |
-| `g_unix_mount_get_*()`   | Yes          | ✅    | Safe on `GUnixMountEntry`                 |
-| `g_volume_monitor_get()` | **No**       | ❌    | Main thread only - **NOT USED**           |
-
-**GIO Threading Docs**: https://docs.gtk.org/gio/class.VolumeMonitor.html
-
-> "GVolumeMonitor is not thread-default-context aware and should not be used other than from the main thread."
-
-This codebase only uses thread-safe APIs (`g_unix_mounts_get()` and related functions)
-because all native code runs on `Napi::AsyncWorker` threads.
-
-### g_unix_mounts_get
-
-- **Docs**: https://docs.gtk.org/gio/func.unix_mounts_get.html
-- **Purpose**: Thread-safe enumeration of mounted filesystems
-- **Returns**: `GList*` of `GUnixMountEntry*` (caller owns both)
-- **Cleanup**: `g_list_free_full(list, (GDestroyNotify)g_unix_mount_free)`
-
-```cpp
-GList *mounts = g_unix_mounts_get(nullptr);
-for (GList *l = mounts; l != nullptr; l = l->next) {
-    GUnixMountEntry *entry = static_cast<GUnixMountEntry*>(l->data);
-    const char *path = g_unix_mount_get_mount_path(entry);
-    const char *fstype = g_unix_mount_get_fs_type(entry);
-}
-g_list_free_full(mounts, reinterpret_cast<GDestroyNotify>(g_unix_mount_free));
-```
-
-**Source**: https://gitlab.gnome.org/GNOME/glib/-/blob/main/gio/gunixmounts.c
-
-### GUnixMountEntry Functions
-
-- **Docs**: https://docs.gtk.org/gio-unix/struct.MountEntry.html
-- `g_unix_mount_get_mount_path()` - Returns `const char*` (borrowed)
-- `g_unix_mount_get_fs_type()` - Returns `const char*` (borrowed)
-- `g_unix_mount_get_device_path()` - Returns `const char*` (borrowed)
-- `g_unix_mount_free()` - Free a single entry
-
-**Note**: String returns are borrowed - do NOT `g_free()` them.
-
-### g_volume_monitor_get (NOT USED)
-
-> ⚠️ **NOT USED IN THIS CODEBASE**: GVolumeMonitor is NOT thread-safe and has been
-> removed from fs-metadata. This section is retained for reference only.
-
-- **Docs**: https://docs.gtk.org/gio/type_func.VolumeMonitor.get.html
-- **Purpose**: Get system volume monitor for rich metadata
-- **Returns**: Owned `GVolumeMonitor*` reference
-- **Cleanup**: **Must** call `g_object_unref()` when done
-
-**Why Not Used**: GVolumeMonitor can only be safely used from the main thread.
-Node.js native addons use `Napi::AsyncWorker` which runs on libuv thread pool
-worker threads. Using GVolumeMonitor from these threads causes race conditions:
-
-```
-GLib-GObject-CRITICAL: g_object_ref: assertion '!object_already_finalized' failed
-```
-
-The thread-safe `g_unix_mounts_get()` API provides sufficient metadata (fstype,
-mountFrom). Rich metadata (label, uri) is obtained from blkid instead.
-
-### g_volume_monitor_get_mounts (NOT USED)
-
-> ⚠️ **NOT USED**: See above - GVolumeMonitor is not thread-safe.
-
-- **Docs**: https://docs.gtk.org/gio/method.VolumeMonitor.get_mounts.html
-- **Returns**: `GList*` of `GMount*` (caller owns list and references)
-- **Cleanup**: `g_list_free_full(mounts, g_object_unref)`
-
-### GMount / GVolume / GFile Functions (NOT USED)
-
-> ⚠️ **NOT USED**: These require GVolumeMonitor which is not thread-safe.
-
-| Function                         | Returns    | Ownership           |
-| -------------------------------- | ---------- | ------------------- |
-| `g_mount_get_root()`             | `GFile*`   | Caller owns, unref  |
-| `g_mount_get_volume()`           | `GVolume*` | Caller owns, unref  |
-| `g_mount_get_name()`             | `char*`    | Caller owns, g_free |
-| `g_mount_get_default_location()` | `GFile*`   | Caller owns, unref  |
-| `g_file_get_path()`              | `char*`    | Caller owns, g_free |
-| `g_file_get_uri()`               | `char*`    | Caller owns, g_free |
-| `g_volume_get_name()`            | `char*`    | Caller owns, g_free |
-
-**Memory Management Docs**: https://docs.gtk.org/gobject/concepts.html#reference-counting
-
-### GLib Memory Functions
-
-| Function             | Purpose                               |
-| -------------------- | ------------------------------------- |
-| `g_object_unref()`   | Decrement GObject reference count     |
-| `g_free()`           | Free GLib-allocated memory            |
-| `g_list_free()`      | Free GList container only             |
-| `g_list_free_full()` | Free GList and elements with callback |
-
-**Docs**: https://docs.gtk.org/glib/func.free.html
+1. [libblkid APIs](#libblkid-apis)
+2. [POSIX File System APIs](#posix-file-system-apis)
+3. [RAII Patterns](#raii-patterns)
+4. [References](#references)
 
 ## libblkid APIs
 
@@ -221,32 +116,6 @@ if (fd < 0) {
 
 ## RAII Patterns
 
-### GIO Smart Pointers (gio_utils.h)
-
-```cpp
-// Custom deleters
-template <typename T> struct GObjectDeleter {
-    void operator()(T *ptr) const { if (ptr) g_object_unref(ptr); }
-};
-
-struct GFreeDeleter {
-    void operator()(void *ptr) const { if (ptr) g_free(ptr); }
-};
-
-// Smart pointer aliases
-template <typename T> using GObjectPtr = std::unique_ptr<T, GObjectDeleter<T>>;
-
-using GFilePtr = GObjectPtr<GFile>;
-using GMountPtr = GObjectPtr<GMount>;
-using GVolumePtr = GObjectPtr<GVolume>;
-using GVolumeMonitorPtr = GObjectPtr<GVolumeMonitor>;  // Not currently used
-using GCharPtr = std::unique_ptr<char, GFreeDeleter>;
-```
-
-> **Note**: `GVolumeMonitorPtr`, `GMountPtr`, `GVolumePtr`, and `GFilePtr` are
-> defined but not currently used because GVolumeMonitor is not thread-safe.
-> They are retained for potential future use if a main-thread-only API is added.
-
 ### BlkidCache RAII
 
 ```cpp
@@ -285,18 +154,6 @@ FdGuard guard{fd};
 
 ## References
 
-### GIO/GLib Official Documentation
-
-- [GIO Reference](https://docs.gtk.org/gio/)
-- [GLib Reference](https://docs.gtk.org/glib/)
-- [GObject Memory Management](https://docs.gtk.org/gobject/concepts.html#reference-counting)
-- [GVolumeMonitor](https://docs.gtk.org/gio/class.VolumeMonitor.html)
-- [Unix Mounts](https://docs.gtk.org/gio-unix/struct.MountEntry.html)
-
-### GLib Source Code
-
-- [gunixmounts.c](https://gitlab.gnome.org/GNOME/glib/-/blob/main/gio/gunixmounts.c) - Thread-safe mount enumeration implementation
-
 ### libblkid / util-linux
 
 - [libblkid(3) man page](https://man7.org/linux/man-pages/man3/libblkid.3.html)

package/doc/SECURITY_AUDIT_2026.md

@@ -5,6 +5,10 @@
 **Scope**: Complete codebase review including API verification against official documentation
 **Previous Audit**: October-December 2025 (see `doc/SECURITY_AUDIT_2025.md`)
 
+> **Post-audit note (April 2026):** The Linux GIO/GLib integration discussed in
+> re-verification findings #6 and #7 has since been removed entirely. See the
+> "Removed" section of `CHANGELOG.md` for the rationale.
+
 ## Executive Summary
 
 This audit covers all changes since the December 2025 re-audit, focusing on the new

package/doc/gotchas.md

@@ -133,6 +133,33 @@ FROM debian:bullseye
 RUN apt-get update && apt-get install -y nodejs npm
 ```
 
+#### Electron Consumers Need libblkid Headers
+
+**Problem**: Electron apps that bundle `@photostructure/fs-metadata` fail to build on Linux with:
+
+```
+fatal error: blkid/blkid.h: No such file or directory
+```
+
+…even though `npm install` reports that prebuilds were found.
+
+**Why it happens**: `@electron/rebuild` (invoked by `electron-forge`, `electron-builder`, and friends) **always recompiles native modules from source** against Electron's bundled Node ABI. The Node-ABI prebuilds shipped in `prebuilds/` are not Electron-compatible and are ignored. The fresh compile then needs the same system headers a from-source build needs.
+
+**Solution**: Install `libblkid-dev` (and friends) on the build machine before running `electron-rebuild` / `electron-forge package`:
+
+```bash
+# Debian/Ubuntu
+sudo apt-get install -y libblkid-dev
+
+# Fedora/RHEL
+sudo dnf install -y libblkid-devel
+
+# Alpine
+apk add blkid-dev
+```
+
+In CI, add this as a step before `npm install` / the Electron package step. The same applies to any consumer that compiles from source for an unsupported architecture or glibc version. See [CONTRIBUTING.md](../CONTRIBUTING.md#on-ubuntudebian) for the full development dependency list.
+
 #### System Volume Filtering
 
 Many mount points on Linux are system-only:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@photostructure/fs-metadata",
-  "version": "1.3.0",
+  "version": "1.4.1",
   "description": "Cross-platform native filesystem metadata retrieval for Node.js",
   "homepage": "https://photostructure.github.io/fs-metadata/",
   "types": "./dist/index.d.ts",
@@ -31,9 +31,8 @@
     "clean:gyp-cache": "del-cli --force build %USERPROFILE%/.node-gyp ~/.node-gyp",
     "clean:native": "node-gyp clean",
     "node-gyp-rebuild": "node-gyp rebuild",
-    "setup:native": "node scripts/setup-native.mjs",
-    "build": "run-s setup:native build:native build:dist",
-    "build:native": "npm run setup:native && tsx scripts/prebuildify-wrapper.ts",
+    "build": "run-s build:native build:dist",
+    "build:native": "tsx scripts/prebuildify-wrapper.ts",
     "build:linux-glibc": "bash scripts/prebuild-linux-glibc.sh",
     "build:dist": "tsup && node scripts/post-build.mjs",
     "docs": "typedoc",
@@ -96,28 +95,28 @@
   },
   "devDependencies": {
     "@types/jest": "^30.0.0",
-    "@types/node": "^25.5.0",
+    "@types/node": "^25.6.0",
     "@types/semver": "^7.7.1",
     "cross-env": "^10.1.0",
     "del-cli": "^7.0.0",
     "eslint": "9.39.1",
     "eslint-plugin-regexp": "^3.1.0",
     "eslint-plugin-security": "^4.0.0",
-    "globals": "^17.4.0",
+    "globals": "^17.5.0",
     "jest": "^30.3.0",
     "jest-environment-node": "^30.3.0",
     "jest-extended": "^7.0.0",
-    "node-gyp": "^12.2.0",
-    "npm-check-updates": "^19.6.6",
+    "node-gyp": "^12.3.0",
+    "npm-check-updates": "^22.0.1",
     "npm-run-all2": "8.0.4",
     "prebuildify": "^6.0.1",
-    "prettier": "^3.8.1",
+    "prettier": "^3.8.3",
     "prettier-plugin-organize-imports": "4.3.0",
-    "terser": "^5.46.1",
-    "ts-jest": "^29.4.6",
+    "terser": "^5.46.2",
+    "ts-jest": "^29.4.9",
     "tsup": "^8.5.1",
     "tsx": "^4.21.0",
-    "typedoc": "^0.28.18",
+    "typedoc": "^0.28.19",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.57.2"
   }

package/scripts/clang-tidy.ts

@@ -140,8 +140,6 @@ async function generateWindowsCompileCommands(): Promise<boolean> {
   console.log("Generating compile_commands.json for Windows...");
 
   try {
-    execSync("npm run setup:native", { stdio: "inherit" });
-
     const nodeVersion = process.version.slice(1);
 
     // Try multiple possible locations for node-gyp headers
@@ -293,7 +291,7 @@ async function generateUnixCompileCommands(): Promise<void> {
     process.exit(1);
   }
 
-  execSync("npm run setup:native && bear -- npm run node-gyp-rebuild", {
+  execSync("bear -- npm run node-gyp-rebuild", {
     stdio: "inherit",
   });
 

package/scripts/prebuild-linux-glibc.sh

@@ -88,7 +88,7 @@ docker cp . "$CONTAINER_NAME:/tmp/project"
 docker exec "$CONTAINER_NAME" sh -c "
   cd /tmp/project && \
   apt-get update -qq && \
-  apt-get install -y -qq build-essential python3 libglib2.0-dev libblkid-dev uuid-dev git && \
+  apt-get install -y -qq build-essential python3 libblkid-dev uuid-dev git && \
   # Verify versions
   echo 'Python version:' && python3 --version && \
   echo 'GCC version:' && gcc --version | head -1 && \
@@ -100,7 +100,6 @@ docker exec "$CONTAINER_NAME" sh -c "
 # Copy artifacts back
 docker cp "$CONTAINER_NAME:/tmp/project/prebuilds" . 2>/dev/null || true
 docker cp "$CONTAINER_NAME:/tmp/project/build" . 2>/dev/null || true
-docker cp "$CONTAINER_NAME:/tmp/project/config.gypi" . 2>/dev/null || true
 
 # Fix ownership (docker cp preserves container's root ownership)
 if [ -d prebuilds ]; then
@@ -109,9 +108,6 @@ fi
 if [ -d build ]; then
   chown -R "$(id -u):$(id -g)" build
 fi
-if [ -f config.gypi ]; then
-  chown "$(id -u):$(id -g)" config.gypi
-fi
 
 # Clean up container
 docker rm -f "$CONTAINER_NAME" >/dev/null

package/scripts/sanitizers-test.sh

@@ -76,7 +76,6 @@ fi
 
 # Build the native module
 echo "Building with AddressSanitizer..."
-npm run setup:native
 npm run clean:native
 npm run node-gyp-rebuild
 

package/src/binding.cpp

@@ -3,6 +3,7 @@
 #include <string>
 
 #include "common/debug_log.h"
+#include "common/shutdown.h"
 #if defined(_WIN32)
 #include "windows/fs_meta.h"
 #include "windows/hidden.h"
@@ -12,10 +13,6 @@
 #include "darwin/hidden.h"
 #elif defined(__linux__)
 #include "common/volume_metadata.h"
-#ifdef ENABLE_GIO
-#include "linux/gio_mount_points.h"
-#include "linux/gio_volume_metadata.h"
-#endif
 #endif
 
 namespace {
@@ -43,13 +40,6 @@ Napi::Value SetDebugPrefix(const Napi::CallbackInfo &info) {
   return env.Undefined();
 }
 
-#ifdef ENABLE_GIO
-Napi::Value GetGioMountPoints(const Napi::CallbackInfo &info) {
-  const Napi::Env env = info.Env();
-  return FSMeta::gio::GetMountPoints(env);
-}
-#endif
-
 #if defined(_WIN32) || defined(__APPLE__)
 // Fix: Remove extra parameter and use correct signature
 Napi::Value GetVolumeMountPoints(const Napi::CallbackInfo &info) {
@@ -78,6 +68,10 @@ Napi::Value SetHiddenAttribute(const Napi::CallbackInfo &info) {
 #endif
 
 Napi::Object Init(Napi::Env env, Napi::Object exports) {
+  // Register a cleanup hook so in-flight native workers can short-circuit
+  // during env teardown instead of racing FreeEnvironment.
+  FSMeta::EnsureShutdownHook(env);
+
   exports.Set("setDebugLogging", Napi::Function::New(env, SetDebugLogging));
   exports.Set("setDebugPrefix", Napi::Function::New(env, SetDebugPrefix));
 
@@ -92,10 +86,6 @@ Napi::Object Init(Napi::Env env, Napi::Object exports) {
   exports.Set("getMountPoint", Napi::Function::New(env, GetMountPointForPath));
 #endif
 
-#ifdef ENABLE_GIO
-  exports.Set("getGioMountPoints", Napi::Function::New(env, GetGioMountPoints));
-#endif
-
 #if defined(_WIN32) || defined(__APPLE__)
   exports.Set("isHidden", Napi::Function::New(env, GetHiddenAttribute));
   exports.Set("setHidden", Napi::Function::New(env, SetHiddenAttribute));

package/src/common/metadata_worker.h

@@ -1,11 +1,12 @@
 // src/common/metadata_worker.h
 #pragma once
+#include "./shutdown.h"
 #include "./volume_metadata.h"
 #include <napi.h>
 
 namespace FSMeta {
 
-class MetadataWorkerBase : public Napi::AsyncWorker {
+class MetadataWorkerBase : public SafeAsyncWorker {
 protected:
   std::string mountPoint;
   VolumeMetadata metadata;
@@ -13,17 +14,17 @@ protected:
 
   MetadataWorkerBase(const std::string &path,
                      const Napi::Promise::Deferred &deferred)
-      : Napi::AsyncWorker(deferred.Env()), mountPoint(path),
-        deferred_(deferred) {}
+      : SafeAsyncWorker(deferred.Env()), mountPoint(path), deferred_(deferred) {}
 
   void OnError(const Napi::Error &error) override {
-    deferred_.Reject(error.Value());
+    Napi::HandleScope scope(Env());
+    SafeReject(deferred_, error.Value());
   }
 
   void OnOK() override {
     Napi::HandleScope scope(Env());
-    deferred_.Resolve(metadata.ToObject(Env()));
+    SafeResolve(deferred_, metadata.ToObject(Env()));
   }
 }; // class MetadataWorkerBase
 
-} // namespace FSMeta
+} // namespace FSMeta

package/src/common/shutdown.h

@@ -0,0 +1,162 @@
+// src/common/shutdown.h
+// Shutdown-safety helpers: a per-env flag set during Node env teardown,
+// plus deferred Resolve/Reject wrappers that swallow C++ Napi errors so they
+// can never escape AsyncWorker callbacks.
+//
+// Why this exists: AsyncWorker::OnWorkComplete can run during
+// node::FreeEnvironment cleanup. If napi_resolve_deferred / napi_reject_deferred
+// fail at that point (env tearing down), node-addon-api throws a C++
+// Napi::Error. With NAPI_CPP_EXCEPTIONS the rethrow path inside
+// WrapVoidCallback then calls ThrowAsJavaScriptException, which can also fail,
+// letting the C++ exception escape into a libuv cleanup hook frame that has
+// no catch - terminate() / SIGABRT.
+//
+// The flag is stored as napi instance data so worker threads (each their own
+// env) don't poison the main env's flag when they tear down.
+//
+
+#pragma once
+
+#include <atomic>
+#include <memory>
+#include <napi.h>
+#include <string>
+
+namespace FSMeta {
+
+struct ShutdownState {
+  std::atomic<bool> shuttingDown{false};
+};
+
+struct ModuleInstanceData {
+  std::shared_ptr<ShutdownState> shutdownState =
+      std::make_shared<ShutdownState>();
+};
+
+inline ModuleInstanceData *GetInstanceData(napi_env env) {
+  void *raw = nullptr;
+  if (napi_get_instance_data(env, &raw) != napi_ok) {
+    return nullptr;
+  }
+  return static_cast<ModuleInstanceData *>(raw);
+}
+
+inline bool IsShuttingDown(napi_env env) {
+  if (auto *d = GetInstanceData(env)) {
+    return d->shutdownState->shuttingDown.load(std::memory_order_acquire);
+  }
+  // No instance data registered (test harness, etc.) - fail safe: not shutting.
+  return false;
+}
+
+inline std::shared_ptr<ShutdownState> GetShutdownState(napi_env env) {
+  if (auto *d = GetInstanceData(env)) {
+    return d->shutdownState;
+  }
+  return nullptr;
+}
+
+inline bool IsShuttingDown(const std::shared_ptr<ShutdownState> &state) {
+  return state != nullptr &&
+         state->shuttingDown.load(std::memory_order_acquire);
+}
+
+// Registers per-env shutdown state and a cleanup hook that flips the flag.
+// Idempotent per env: binding.cpp Init runs once per env load.
+inline void EnsureShutdownHook(napi_env env) {
+  if (GetInstanceData(env) != nullptr) {
+    return;
+  }
+  auto *data = new ModuleInstanceData();
+  auto *cleanupState = new std::shared_ptr<ShutdownState>(data->shutdownState);
+  napi_status status = napi_set_instance_data(
+      env, data,
+      [](napi_env /*env*/, void *raw, void * /*hint*/) {
+        delete static_cast<ModuleInstanceData *>(raw);
+      },
+      nullptr);
+  if (status != napi_ok) {
+    delete cleanupState;
+    delete data;
+    return;
+  }
+  status = napi_add_env_cleanup_hook(
+      env,
+      [](void *arg) {
+        auto *state = static_cast<std::shared_ptr<ShutdownState> *>(arg);
+        (*state)->shuttingDown.store(true, std::memory_order_release);
+        delete state;
+      },
+      cleanupState);
+  if (status != napi_ok) {
+    delete cleanupState;
+  }
+}
+
+// Wrap deferred.Resolve so a teardown-time napi failure cannot escape the
+// AsyncWorker callback as an uncaught C++ exception.
+inline void SafeResolve(const Napi::Promise::Deferred &deferred,
+                        napi_value value) {
+  try {
+    deferred.Resolve(value);
+  } catch (...) {
+    // Env is tearing down; the JS-side promise is unobservable anyway.
+  }
+}
+
+inline void SafeReject(const Napi::Promise::Deferred &deferred,
+                       napi_value value) {
+  try {
+    deferred.Reject(value);
+  } catch (...) {
+    // Env is tearing down; the JS-side promise is unobservable anyway.
+  }
+}
+
+class SafeAsyncWorker : public Napi::AsyncWorker {
+public:
+  void OnExecute(Napi::Env /*env*/) override {
+    try {
+      Execute();
+    } catch (const std::exception &e) {
+      SetError(e.what());
+    } catch (...) {
+      SetError("Unknown native error");
+    }
+  }
+
+  void OnWorkComplete(Napi::Env env, napi_status status) override {
+    if (status != napi_cancelled && !IsShuttingDown()) {
+      try {
+        Napi::HandleScope scope(env);
+        if (status != napi_ok) {
+          OnError(Napi::Error::New(env));
+        } else if (error_.empty()) {
+          OnOK();
+        } else {
+          OnError(Napi::Error::New(env, error_));
+        }
+      } catch (...) {
+        // Env teardown can make value construction, handle scopes, or deferred
+        // resolution fail. The JS promise is no longer observable then.
+      }
+    }
+    Destroy();
+  }
+
+protected:
+  explicit SafeAsyncWorker(Napi::Env env)
+      : Napi::AsyncWorker(env), shutdownState_(GetShutdownState(env)) {}
+
+  void SetError(const std::string &error) { error_ = error; }
+
+  bool IsShuttingDown() const {
+    return FSMeta::IsShuttingDown(shutdownState_);
+  }
+
+private:
+  std::shared_ptr<ShutdownState> shutdownState_;
+  std::string error_;
+};
+
+} // namespace FSMeta