node-android.yml

# Cross-compiles Node.js for Android: arm64-v8a (verified) + armeabi-v7a (experimental,
# see nodejs/node#58975). Produces per ABI: lib<n>.so + node CLI binary.
name: Node.js for Android (ARM)

on:
  push:
    branches: [main]
    tags: ['v*']
  workflow_dispatch:
    inputs:
      node_version:
        description: 'Node.js version to build'
        type: choice
        default: 'v26.x'
        options:
          - 'v26.x'       # Latest release line
          - 'v24.x'       # LTS (Krypton)
          - 'custom'
      custom_ref:
        description: 'Custom git ref — only used when "custom" is selected'
        required: false
        default: ''
      lib_name:
        description: 'Library name — output will be lib<n>.so (e.g. "aurora" → libaurora.so)'
        required: false
        default: 'node'
      profile:
        description: 'Build profile'
        type: choice
        default: 'balanced'
        options:
          - 'balanced'    # JIT + -O3: best runtime speed (Baileys/server use)
          - 'speed'       # + LTO: faster, much longer build
          - 'size'        # + v8-lite-mode: lower RAM, slower JS/crypto

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

env:
  # HISTORY (kept for context on the two prior compiler-crash rejections):
  # r26d was dropped after a reproducible clang-17 segfault (SIGSEGV, exit
  # 139) while parsing deps/v8/src/json/json-stringifier.cc — inside
  # FastJsonStringifier::SerializeObjectKey's switch/case body. That was a
  # compiler crash, not a source-level diagnostic (a clang stack trace ending
  # in "clang frontend command failed with exit code 139", no "error:"
  # pointing at our code), reproduced identically on both arm64-v8a and
  # armeabi-v7a. r27c was separately dropped for an unrelated CRTP
  # name-resolution regression in
  # deps/v8/src/compiler/turboshaft/assembler.h (AssemblerOpInterface),
  # surfacing as a clean "error: expected '}'" in pipeline.cc — no stack
  # trace, no segfault. r27d (Clang 18) fixed both and was the pin used
  # 2026-07-20 through 2026-07-22.
  #
  # UPDATED 2026-07-22: bumped r27d -> r29 (current stable per
  # https://github.com/android/ndk/wiki/Changelog-r29), to track what most
  # other Node-on-Android cross-build workflows are pinning to. r29 ships
  # clang-r563880c = Clang 21 — a jump of three Clang majors past r27d's
  # Clang 18, and this skips r28 entirely (no incremental validation on this
  # Node branch). Clang 21 postdates both crashes above by a wide margin, so
  # neither is expected to resurface, but this has NOT been separately
  # re-confirmed on this exact branch/commit the way the r26d->r27d move was.
  # Two patches further down were written and verified against the older,
  # pinned Clang and are believed to be safe no-ops on Clang 21 (they rewrite
  # to strictly-equivalent, more-portable constructs rather than reverting
  # real behavior), but have not been individually re-verified against r29's
  # compiler:
  #   - "Patch V8: consteval/immediate-escalation clang bug..." — the
  #     upstream clang bug this works around (llvm-project#94935) was fully
  #     fixed ~Jan 2025, well before Clang 21, so this patch should now be
  #     inert.
  #   - "Patch V8: wrappers-inl.h decltype(Operation::input_count) NDK
  #     r26d/Clang 17 fix" — labeled for the Clang version that exposed it;
  #     left applied unconditionally since the std::declval<T>() rewrite is
  #     semantically identical on any clang version.
  # If a new failure appears, check whether it's a new-Clang-vs-old-patch
  # interaction before assuming it's a fresh V8/Android incompatibility.
  # `toolchain.gypi`'s branch-protection removal (below) already anticipated
  # r29 explicitly, and the `-Wl,-z,max-page-size=16384` linker flag (section
  # 4) already covers r28+'s 16 KB page-size default, so neither should need
  # further changes for this bump.
  NDK_VERSION: 'r29'
  MIN_API: '24'                # Node v24+ requires API 24+ (Android 7.0). Do NOT set below 24.
  ANDROID_PLATFORM: 'android-24'

jobs:
  build:
    name: android-${{ matrix.abi }}
    # UPDATED 2026-07-20: bumped from ubuntu-22.04. V8's current C++20 usage
    # now requires GCC 13.2+ — nodejs/node#62555 states this explicitly
    # ("V8 can no longer be compiled with GCC 12"). ubuntu-22.04's default
    # g++ is 11.4, which is exactly what CC_host/CXX_host below resolve to,
    # so this was silently broken rather than merely outdated. Confirmed on
    # two independent V8 files/symbols so far: the Turboshaft CRTP patch
    # target (builtins-number-tsa.cc / AssemblerOpInterface) further down in
    # this file, and — verified directly, not assumed — the
    # "value of 'kArmv6' is not usable in a constant expression" /
    # "was not declared 'constexpr'" failure in
    # codegen/arm/assembler-arm.cc on the armeabi-v7a host-tools leg
    # (obj.host/v8_base_without_compiler; mksnapshot needs a host-built copy
    # of the target arch's Assembler). Reproduced that exact pattern
    # (constexpr fn reading a non-constexpr static-const class-type global)
    # against g++-11/-12/-13 directly: 11 and 12 both hard-error on the bare
    # declaration regardless of whether it's ever actually const-evaluated;
    # 13 demotes it to a non-fatal -Winvalid-constexpr warning, which is
    # sufficient here since V8 only calls CpuFeaturesFromCompiler() at plain
    # runtime (CpuFeatures::ProbeImpl), never in a forced constant-expression
    # context. ubuntu-24.04 ships GCC 13.2 as default gcc/g++, so
    # CC_host/CXX_host and the CC.host/CXX.host/LINK.host make overrides
    # need no other changes, and gcc-multilib/g++-multilib for the
    # armeabi-v7a leg exist on 24.04 too.
    runs-on: ubuntu-24.04
    timeout-minutes: 180
    # armeabi-v7a is best-effort: upstream V8 cross-build for 32-bit targets on
    # x64 hosts has open bugs (nodejs/node#58975). Never let it block arm64.
    continue-on-error: ${{ matrix.experimental || false }}
    permissions:
      contents: write
    strategy:
      fail-fast: false
      matrix:
        include:
          - abi: arm64-v8a            # 64-bit ARM — verified working
            dest_cpu: arm64
            target: aarch64-linux-android
          - abi: armeabi-v7a          # 32-bit ARM — experimental
            dest_cpu: arm
            target: armv7a-linux-androideabi
            experimental: true

    steps:
      # ---------- 0. Resolve inputs ----------
      # SECURITY: custom_ref and lib_name are free-text workflow_dispatch inputs.
      # Read them through env: variables (resolved before the shell runs) instead of
      # ${{ }} inline interpolation to prevent shell-metacharacter injection.
      - name: Resolve inputs
        env:
          CUSTOM_REF_RAW: ${{ inputs.custom_ref || '' }}
          LIB_NAME_RAW: ${{ inputs.lib_name || 'node' }}
        run: |
          REQ="${{ inputs.node_version || 'v26.x' }}"
          if [ "$REQ" = "custom" ]; then REQ="$CUSTOM_REF_RAW"; fi
          if [ -z "$REQ" ]; then echo "::error::custom_ref is empty"; exit 1; fi
          echo "NODE_REF=$REQ" >> "$GITHUB_ENV"

          NAME="$LIB_NAME_RAW"
          NAME="${NAME#lib}"; NAME="${NAME%.so}"
          if ! [[ "$NAME" =~ ^[A-Za-z0-9_-]+$ ]]; then
            echo "::error::Invalid lib_name '$NAME'"; exit 1
          fi
          echo "LIB_NAME=$NAME" >> "$GITHUB_ENV"
          echo "Building Node.js '$REQ' as lib$NAME.so"

      # ---------- 1. Android NDK (r29) ----------
      # Switched from a manual curl+unzip to nttld/setup-ndk to match the
      # v24-only workflow this was diffed against. The manual download step
      # this replaces existed only because r26d was being force-installed
      # over whatever the runner ships by default — with a plain release tag
      # like r29 now current (bumped from r27d 2026-07-22), setup-ndk's own
      # caching/selection logic is simpler and one less hand-rolled step to
      # keep correct across NDK version bumps.
      - name: Set up Android NDK ${{ env.NDK_VERSION }}
        uses: nttld/setup-ndk@v1
        with:
          ndk-version: ${{ env.NDK_VERSION }}

      - name: Verify NDK toolchain paths
        run: |
          echo "ANDROID_NDK_HOME=${ANDROID_NDK_HOME:-$ANDROID_NDK}" >> "$GITHUB_ENV"
          TC="${ANDROID_NDK_HOME:-$ANDROID_NDK}/toolchains/llvm/prebuilt/linux-x86_64"
          test -x "$TC/bin/${{ matrix.target }}${{ env.MIN_API }}-clang"
          echo "NDK OK: ${ANDROID_NDK_HOME:-$ANDROID_NDK}"

      # ---------- 1b. ccache ----------
      # Everything above this point is seconds; the ~2h this job takes is almost
      # entirely the make step in section 4 — a from-scratch V8+Node compile with
      # no object reuse between runs. ccache fixes that: it caches compiled objects
      # by actual preprocessed source+flags content, so reruns/retries and
      # iterating on this workflow (not on Node's own source) get much faster once
      # the first run has populated the cache. The cache itself is populated only
      # on its first run — the win is every run after that.
      - name: Configure ccache
        run: |
          echo "CCACHE_DIR=$HOME/.cache/ccache" >> "$GITHUB_ENV"
          echo "CCACHE_MAXSIZE=2G" >> "$GITHUB_ENV"

      - name: Cache ccache directory
        uses: actions/cache@v4
        with:
          path: ${{ env.CCACHE_DIR }}
          key: ccache-${{ matrix.abi }}-${{ env.NODE_REF }}-${{ inputs.profile || 'balanced' }}-${{ github.run_id }}
          restore-keys: |
            ccache-${{ matrix.abi }}-${{ env.NODE_REF }}-${{ inputs.profile || 'balanced' }}-

      # ---------- 2. Host build tools ----------
      - name: Install host build tools
        run: |
          python3 -c "import sys; v=sys.version_info; assert v>=(3,10), f'need Python>=3.10, got {v}'"
          sudo apt-get update
          sudo apt-get install -y --no-install-recommends \
            python3 g++ make git ca-certificates ccache

      - name: Install 32-bit multilib (armeabi-v7a only)
        if: matrix.dest_cpu == 'arm'
        run: sudo apt-get install -y gcc-multilib g++-multilib
        # V8 mandates 32-bit host tools when targeting 32-bit arm.

      # ---------- 3. Node.js source ----------
      - name: Clone Node.js (${{ env.NODE_REF }})
        run: git clone --depth 1 --branch "$NODE_REF" https://github.com/nodejs/node.git node

      # ---------- 3a. Resolve actual Node.js version ----------
      # NODE_REF (from the node_version input, e.g. "v26.x") is just the git
      # ref that was asked for — the workflow_dispatch dropdown offers
      # v26.x/v24.x, which are MOVING branches, not fixed tags (confirmed
      # against nodejs/node: refs/heads/v26.x and refs/heads/v24.x both
      # exist and advance as releases land on them). So NODE_REF alone
      # never tells you which actual Node.js version — 26.4.0? 26.5.1? —
      # ended up in this specific build; it's the same literal string
      # every run regardless of what the branch pointed to that day. That
      # made every artifact filename and release title equally vague
      # regardless of when the workflow ran.
      #
      # Fix: read the version macros Node.js itself embeds in
      # src/node_version.h — NODE_MAJOR_VERSION / NODE_MINOR_VERSION /
      # NODE_PATCH_VERSION / NODE_VERSION_IS_RELEASE — right after clone,
      # so this reflects whatever commit was ACTUALLY checked out this
      # run, regardless of whether NODE_REF was a moving branch, a fixed
      # tag, or an arbitrary custom_ref/SHA. Verified directly against
      # nodejs/node: cloning branch v26.x today resolves to 26.5.1 (commit
      # 955e669e, NODE_VERSION_IS_RELEASE=0 — i.e. this exact commit isn't
      # itself a tagged release, just where the release branch currently
      # sits); cloning the tag v24.10.0 resolves to 24.10.0 with
      # NODE_VERSION_IS_RELEASE=1. The -dev suffix below distinguishes
      # those two cases so a build off a moving branch is never confused
      # for an official tagged release.
      #
      # RESOLVED_NODE_VERSION / NODE_COMMIT_SHORT are consumed by the
      # artifact-naming step in section 5 and the release job further
      # below (which re-derives them from the downloaded artifact's own
      # filename rather than plumbing GITHUB_ENV across jobs/matrix legs —
      # see the release job's "Resolve inputs" step for why).
      - name: Resolve actual Node.js version
        working-directory: node
        run: |
          python3 - <<'PYEOF'
          import re
          import pathlib
          import subprocess
          import os

          vh_path = pathlib.Path('src/node_version.h')
          vh = vh_path.read_text()

          def grab(name):
              m = re.search(rf'#define\s+{name}\s+(\S+)', vh)
              if not m:
                  print(f"::error::could not find {name} in {vh_path}")
                  raise SystemExit(1)
              return m.group(1)

          major = grab('NODE_MAJOR_VERSION')
          minor = grab('NODE_MINOR_VERSION')
          patch = grab('NODE_PATCH_VERSION')
          is_release = grab('NODE_VERSION_IS_RELEASE')

          version = f"{major}.{minor}.{patch}"
          if is_release != "1":
              version += "-dev"

          sha_full = subprocess.check_output(
              ['git', 'rev-parse', 'HEAD'], text=True
          ).strip()
          sha_short = sha_full[:10]

          # Sanity check: version must be a plain dotted-numeric triple
          # (optionally -dev), since it flows straight into filenames —
          # never trust an upstream macro format silently enough to skip
          # this before it becomes part of a path GitHub uploads.
          if not re.fullmatch(r'\d+\.\d+\.\d+(-dev)?', version):
              print(f"::error::resolved version '{version}' failed sanity check")
              raise SystemExit(1)

          gh_env = os.environ['GITHUB_ENV']
          with open(gh_env, 'a') as f:
              f.write(f"RESOLVED_NODE_VERSION={version}\n")
              f.write(f"NODE_COMMIT_SHA={sha_full}\n")
              f.write(f"NODE_COMMIT_SHORT={sha_short}\n")

          print(f"Requested ref:     {os.environ.get('NODE_REF', '(unset)')}")
          print(f"Resolved version:  {version}")
          print(f"Commit:            {sha_full}")
          PYEOF

      # ---------- 3b. Patch known Android cross-build issues ----------
      # Android is not an officially tested/supported Node.js target (core team
      # position, see nodejs/node#58505) — these are community-tracked issues
      # carried by Termux's Node.js packaging for years and partially upstreamed.
      # Expect this list to need revisiting on every Node major bump.
      #
      # NOTE: each patch step must stay under GitHub Actions' 21000-char expression
      # limit. The monolithic python3 block is split into logical groups below.
      - name: "Patch V8: base + uv (stack_trace, small_vector, trap_handler, uv.gyp, fs.c)"
        working-directory: node
        run: |
          python3 - <<'PYEOF'
          import pathlib
          def patch(path, old, new):
              p = pathlib.Path(path)
              if not p.exists():
                  print(f"::warning::file not found {path} (skipping)")
                  return
              s = p.read_text()
              if old not in s:
                  print(f"::warning::context not found in {path}")
                  return
              p.write_text(s.replace(old, new, 1))
              print(f"patched {path}")

          patch('deps/v8/src/base/debug/stack_trace_posix.cc',
                '#include "src/base/build_config.h"\n#include "src/base/free_deleter.h"',
                '#if defined(__ANDROID__)\n'
                'extern "C" int backtrace(void**, int) { return 0; }\n'
                'extern "C" char** backtrace_symbols(void* const*, int) { return nullptr; }\n'
                'extern "C" void backtrace_symbols_fd(void* const*, int, int) {}\n'
                '#endif\n\n'
                '#include "src/base/build_config.h"\n#include "src/base/free_deleter.h"')

          th = pathlib.Path('deps/v8/src/trap-handler/trap-handler.h')
          c = th.read_text()
          ms = '// X64 on Linux, Windows, MacOS, FreeBSD.'
          me = '#define V8_TRAP_HANDLER_SUPPORTED false\n#endif'
          if ms in c and me in c:
              i0 = c.index(ms); i1 = c.index(me, i0) + len(me)
              c = c[:i0] + '#define V8_TRAP_HANDLER_SUPPORTED false' + c[i1:]
              th.write_text(c); print("patched trap-handler.h")
          else:
              print("::warning::trap-handler block boundaries not found")

          patch('deps/uv/uv.gyp',
                '\n'.join(["      'target_name': 'libuv',","      'toolsets': ['host', 'target'],","      'type': '<(uv_library)',","      'include_dirs': [","        'include',","        'src/',","      ],"]),
                '\n'.join(["      'target_name': 'libuv',","      'toolsets': ['host', 'target'],","      'type': '<(uv_library)',","      'include_dirs+': [","        'include',","        'src/',","      ],"]))
          patch('deps/uv/uv.gyp', "        'include_dirs': [ 'include' ],", "        'include_dirs+': [ 'include' ],")

          patch('deps/uv/src/unix/fs.c',
                '#ifdef FICLONE\n'
                '  if (req->flags & UV_FS_COPYFILE_FICLONE ||\n'
                '      req->flags & UV_FS_COPYFILE_FICLONE_FORCE) {',
                '#ifndef __ANDROID__\n'
                '#ifdef FICLONE\n'
                '  if (req->flags & UV_FS_COPYFILE_FICLONE ||\n'
                '      req->flags & UV_FS_COPYFILE_FICLONE_FORCE) {')

          patch('test/cctest/test_crypto_clienthello.cc',
                "    alloc_base = static_cast<uint8_t*>(aligned_alloc(page, 2 * page));",
                "    CHECK_EQ(posix_memalign(reinterpret_cast<void**>(&alloc_base), page, 2 * page), 0);")

          fc = pathlib.Path('deps/uv/src/unix/fs.c')
          s = fc.read_text()
          oc = '\n'.join(['    goto out;','  }','#endif','','  bytes_to_send = src_statsbuf.st_size;'])
          nc = '\n'.join(['    goto out;','  }','#endif','#endif','','  bytes_to_send = src_statsbuf.st_size;'])
          if oc not in s:
              print("::warning::FICLONE #endif close not found")
          else:
              fc.write_text(s.replace(oc, nc, 1)); print("closed #ifndef __ANDROID__ in fs.c")
          PYEOF

      - name: "Patch V8: atomic_ref polyfill + memcopy + wasm-shuffle"
        working-directory: node
        run: |
          python3 - <<'PYEOF'
          import pathlib
          def patch(path, old, new):
              p = pathlib.Path(path)
              if not p.exists():
                  print(f"::warning::file not found {path} (skipping)")
                  return
              s = p.read_text()
              if old not in s:
                  print(f"::warning::context not found in {path}")
                  return
              p.write_text(s.replace(old, new, 1))
              print(f"patched {path}")

          v8config_h = pathlib.Path('deps/v8/include/v8config.h')
          s = v8config_h.read_text()
          old_atomic_line = '#include <memory>'
          new_polyfill_block = (
              '#include <memory>\n'
              '#if defined(__ANDROID__) && !defined(__cpp_lib_atomic_ref)\n'
              '#ifndef V8_STD_ATOMIC_REF_POLYFILL\n'
              '#define V8_STD_ATOMIC_REF_POLYFILL\n'
              'namespace std {\n'
              'template <typename T>\n'
              'struct atomic_ref {\n'
              '  explicit atomic_ref(T& obj) : ptr_(&obj) {}\n'
              '  void store(T val, memory_order order = memory_order_seq_cst) const {\n'
              '    __atomic_store_n(ptr_, val, static_cast<int>(order)); }\n'
              '  T load(memory_order order = memory_order_seq_cst) const {\n'
              '    return __atomic_load_n(ptr_, static_cast<int>(order)); }\n'
              '  T exchange(T val, memory_order order = memory_order_seq_cst) const {\n'
              '    return __atomic_exchange_n(ptr_, val, static_cast<int>(order)); }\n'
              '  bool compare_exchange_strong(T& expected, T desired,\n'
              '      memory_order success, memory_order failure) const {\n'
              '    return __atomic_compare_exchange_n(ptr_, &expected, desired,\n'
              '                                       false, static_cast<int>(success), static_cast<int>(failure)); }\n'
              '  bool compare_exchange_strong(T& expected, T desired,\n'
              '      memory_order order = memory_order_seq_cst) const {\n'
              '    return __atomic_compare_exchange_n(ptr_, &expected, desired,\n'
              '                                       false, static_cast<int>(order), static_cast<int>(order)); }\n'
              '  T fetch_add(T val, memory_order order = memory_order_seq_cst) const {\n'
              '    return __atomic_fetch_add(ptr_, val, static_cast<int>(order)); }\n'
              '  T fetch_or(T val, memory_order order = memory_order_seq_cst) const {\n'
              '    return __atomic_fetch_or(ptr_, val, static_cast<int>(order)); }\n'
              'private:\n'
              '  T* ptr_;\n'
              '};\n'
              '}  // namespace std\n'
              '#endif\n'
              '#endif')
          if old_atomic_line in s:
              s = s.replace(old_atomic_line, new_polyfill_block, 1)
              v8config_h.write_text(s)
              print("patched v8config.h (std::atomic_ref polyfill)")
          else:
              print("::warning::could not find '#include <memory>' in v8config.h")

          patch('deps/v8/src/base/memcopy.h',
                '    std::atomic_ref<T>(destination[i]).store(value, std::memory_order_relaxed);',
                '    __atomic_store_n(&destination[i], value, __ATOMIC_RELAXED);')

          patch('deps/v8/src/compiler/turboshaft/wasm-shuffle-reducer.cc',
                '    wasm::SimdShuffle::ShuffleArray shuffle_bytes;',
                '    wasm::SimdShuffle::ShuffleArray<kSimd128Size> shuffle_bytes;')
          PYEOF

      - name: "Patch V8: consteval/immediate-escalation clang bug in regexp bytecode dispatch"
        # clang bug: llvm-project#94935 — a consteval function called with an
        # argument that depends on an enclosing template/lambda parameter is
        # not correctly recognized as an immediate invocation. Filed Jun 2024,
        # partially fixed Jun 2024 (llvm-project#95233), more completely fixed
        # ~Jan 2025 (llvm-project#124404). NDK r27d's Clang snapshot predates
        # the complete fix, so it rejects this pattern in
        # deps/v8/src/regexp/regexp-bytecodes-inl.h, which surfaces as:
        #   "cannot take address of consteval function 'Type'/'Offset' outside
        #   of an immediate invocation" in regexp-bytecode-generator.cc, and
        #   "call to immediate function ... is not a constant expression" in
        #   regexp-bytecode-analysis.cc.
        # Fix: downgrade the four accessor functions from consteval to
        # constexpr. They're only ever called in constant-expression contexts
        # in this codebase, so this is semantically a no-op here — it just
        # avoids clang's buggy immediate-escalation code path. Verified
        # against clang-18.1.3 (a close match for r27d's vintage) with
        # isolated repros of both failure sites before submitting this patch.
        working-directory: node
        run: |
          python3 - <<'PYEOF'
          import pathlib
          def patch(path, old, new):
              p = pathlib.Path(path)
              if not p.exists():
                  print(f"::warning::file not found {path} (skipping)")
                  return
              s = p.read_text()
              if old not in s:
                  print(f"::warning::context not found in {path}")
                  return
              p.write_text(s.replace(old, new, 1))
              print(f"patched {path}")

          f = 'deps/v8/src/regexp/regexp-bytecodes-inl.h'
          patch(f, 'static consteval int Index(Operand op)',
                   'static constexpr int Index(Operand op)')
          patch(f, 'static consteval int Size(Operand op) {',
                   'static constexpr int Size(Operand op) {')
          patch(f, 'static consteval int Offset(Operand op) {',
                   'static constexpr int Offset(Operand op) {')
          patch(f, 'static consteval RegExpBytecodeOperandType Type(Operand op) {',
                   'static constexpr RegExpBytecodeOperandType Type(Operand op) {')
          PYEOF

      - name: "Patch V8: zlib cpu_features (getauxval replacement)"
        working-directory: node
        run: |
          python3 - <<'PYEOF'
          import pathlib
          def patch(path, old, new):
              p = pathlib.Path(path)
              if not p.exists():
                  print(f"::warning::file not found {path} (skipping)")
                  return
              s = p.read_text()
              if old not in s:
                  print(f"::warning::context not found in {path}")
                  return
              p.write_text(s.replace(old, new, 1))
              print(f"patched {path}")

          zlib_c = pathlib.Path('deps/zlib/cpu_features.c')
          s = zlib_c.read_text()
          old_incl = (
              '#if defined(ARMV8_OS_ANDROID)\n'
              '#include <cpu-features.h>\n'
              '#elif defined(ARMV8_OS_LINUX)\n'
              '#include <asm/hwcap.h>\n'
              '#include <sys/auxv.h>')
          new_incl = (
              '#if defined(ARMV8_OS_ANDROID) || defined(ARMV8_OS_LINUX)\n'
              '#include <asm/hwcap.h>\n'
              '#include <sys/auxv.h>')
          if old_incl in s:
              s = s.replace(old_incl, new_incl, 1); print("patched cpu_features.c (includes)")
          else:
              print("::warning::include block not found")

          old_aarch64 = (
              '#if defined(ARMV8_OS_ANDROID) && defined(__aarch64__)\n'
              '    uint64_t features = android_getCpuFeatures();\n'
              '    arm_cpu_enable_crc32 = !!(features & ANDROID_CPU_ARM64_FEATURE_CRC32);\n'
              '    arm_cpu_enable_pmull = !!(features & ANDROID_CPU_ARM64_FEATURE_PMULL);')
          new_aarch64 = (
              '#if (defined(ARMV8_OS_ANDROID) || defined(ARMV8_OS_LINUX)) && defined(__aarch64__)\n'
              '    unsigned long features = getauxval(AT_HWCAP);\n'
              '    arm_cpu_enable_crc32 = !!(features & HWCAP_CRC32);\n'
              '    arm_cpu_enable_pmull = !!(features & HWCAP_PMULL);')
          if old_aarch64 in s:
              s = s.replace(old_aarch64, new_aarch64, 1); print("patched cpu_features.c (aarch64)")
          else:
              print("::warning::aarch64 branch not found")

          old_aarch32 = (
              '#elif defined(ARMV8_OS_ANDROID) /* aarch32 */\n'
              '    uint64_t features = android_getCpuFeatures();\n'
              '    arm_cpu_enable_crc32 = !!(features & ANDROID_CPU_ARM_FEATURE_CRC32);\n'
              '    arm_cpu_enable_pmull = !!(features & ANDROID_CPU_ARM_FEATURE_PMULL);')
          new_aarch32 = (
              '#elif (defined(ARMV8_OS_ANDROID) || defined(ARMV8_OS_LINUX)) && (defined(__ARM_NEON) || defined(__ARM_NEON__))\n'
              '    unsigned long features = getauxval(AT_HWCAP2);\n'
              '    arm_cpu_enable_crc32 = !!(features & HWCAP2_CRC32);\n'
              '    arm_cpu_enable_pmull = !!(features & HWCAP2_PMULL);')
          if old_aarch32 in s:
              s = s.replace(old_aarch32, new_aarch32, 1); print("patched cpu_features.c (aarch32)")
          else:
              print("::warning::aarch32 branch not found")
          zlib_c.write_text(s)
          PYEOF

      - name: "Patch V8: gyp toolchain + cross-compile config"
        working-directory: node
        run: |
          python3 - <<'PYEOF'
          import pathlib
          def patch(path, old, new):
              p = pathlib.Path(path)
              if not p.exists():
                  print(f"::warning::file not found {path} (skipping)")
                  return
              s = p.read_text()
              if old not in s:
                  print(f"::warning::context not found in {path}")
                  return
              p.write_text(s.replace(old, new, 1))
              print(f"patched {path}")

          patch('tools/v8_gypfiles/v8.gyp',
                "        ['(OS==\"linux\" and clang==1) or (v8_current_cpu in [\"mips64\", \"mips64el\", \"arm\", \"riscv64\", \"loong64\"])', {",
                "        ['((OS==\"linux\" or OS==\"android\") and clang==1) or (v8_current_cpu in [\"mips64\", \"mips64el\", \"arm\", \"riscv64\", \"loong64\"])', {")
          patch('tools/v8_gypfiles/v8.gyp',
                "'<(V8_ROOT)/src/base/platform/platform-posix-time.h',",
                "'<(V8_ROOT)/src/base/platform/platform-posix-time.h',\n"
                "            '<(V8_ROOT)/src/base/platform/platform-linux.h',")
          patch('node.gyp',
                "      ['OS==\"linux\" and clang==1', {",
                "      ['(OS==\"linux\" or OS==\"android\") and clang==1', {")
          patch('tools/v8_gypfiles/toolchain.gypi',
                "    'v8_android_log_stdout%': 0,", "    'v8_android_log_stdout%': 1,")
          v8_tc = pathlib.Path('tools/v8_gypfiles/toolchain.gypi')
          s = v8_tc.read_text()
          bp_block = ("        ['v8_control_flow_integrity==1', {\n"
                      "            'cflags': [ '-mbranch-protection=standard' ],\n"
                      "          }],")
          if bp_block in s:
              s = s.replace(bp_block, "          # removed for Android (NDK r29 doesn't support this)")
              v8_tc.write_text(s); print("patched toolchain.gypi (removed branch-protection)")
          else:
              print("::warning::branch-protection block not found")
          patch('common.gypi',
                "          ['OS == \"android\"', {\n"
                "            'cflags': [ '-fPIC', '-I<(android_ndk_path)/sources/android/cpufeatures' ],\n"
                "            'ldflags': [ '-fPIC' ]\n"
                "          }],", "")
          patch('tools/gyp/pylib/gyp/generator/ninja.py',
                "    \"SHARED_INTERMEDIATE_DIR\": \"$!PRODUCT_DIR/gen\",",
                "    \"SHARED_INTERMEDIATE_DIR\": \"$!PRODUCT_DIR/$|OBJ/gen\",")
          ninja_py = pathlib.Path('tools/gyp/pylib/gyp/generator/ninja.py')
          s = ninja_py.read_text()
          obj_var_block = ("        path = path.replace(CONFIGURATION_NAME, self.config_name)\n"
                           "\n        return path")
          obj_var_new = ("        path = path.replace(CONFIGURATION_NAME, self.config_name)\n"
                         "\n        obj = \"obj\"\n"
                         "        if self.toolset != \"target\":\n"
                         "            obj += \".\" + self.toolset\n"
                         "        path = path.replace(\"$|OBJ\", obj)\n"
                         "\n        return path")
          if obj_var_block in s:
              s = s.replace(obj_var_block, obj_var_new, 1)
              ninja_py.write_text(s); print("patched ninja.py (OBJ variable)")
          else:
              print("::warning::ExpandSpecial return not found in ninja.py")
          patch('deps/uvwasi/src/uvwasi.c',
                '#if !defined(_WIN32) && !defined(__ANDROID__)',
                '#if !defined(_WIN32)')
          patch('deps/v8/include/v8config.h',
                '#if (V8_TARGET_ARCH_ARM && !(V8_HOST_ARCH_IA32 || V8_HOST_ARCH_ARM))\n'
                '#error Target architecture arm is only supported on arm and ia32 host',
                '#if (V8_TARGET_ARCH_ARM && !(V8_HOST_ARCH_IA32 || V8_HOST_ARCH_ARM || V8_HOST_ARCH_X64))\n'
                '#error Target architecture arm is only supported on arm, ia32, and x64 host')
          patch('deps/v8/src/common/globals.h',
                'static_assert((kTaggedSize == 8) == TAGGED_SIZE_8_BYTES);',
                '// static_assert((kTaggedSize == 8) == TAGGED_SIZE_8_BYTES);')
          patch('deps/v8/src/builtins/builtins-iterator-inl.h',
                '        } else {                                                            \\\n'
                '          static_assert(std::numeric_limits<ctype>::max() <=                \\\n'
                '                        std::numeric_limits<int>::max());                   \\\n'
                '          static_assert(std::numeric_limits<ctype>::min() >=                \\\n'
                '                        std::numeric_limits<int>::min());                   \\\n'
                '          if (!int_visitor(static_cast<int>(val))) {                        \\\n'
                '            return MaybeDirectHandle<Object>();                             \\\n'
                '          }                                                                 \\\n'
                '        }',
                '        } else if constexpr (std::numeric_limits<ctype>::max() <=           \\\n'
                '                             std::numeric_limits<int>::max() &&             \\\n'
                '                             std::numeric_limits<ctype>::min() >=           \\\n'
                '                             std::numeric_limits<int>::min()) {             \\\n'
                '          if (!int_visitor(static_cast<int>(val))) {                        \\\n'
                '            return MaybeDirectHandle<Object>();                             \\\n'
                '          }                                                                 \\\n'
                '        }')
          PYEOF

      # ---------- FIXED 2026-07-18 ----------
      # Root cause of the "expected '}'" / "namespaces can only be defined in
      # global or namespace scope" cascade in pipeline.cc, confirmed against the
      # actual V8 14.6.202.33 source (the version this branch currently vendors):
      #
      # The previous version of this step did a blind global
      # str.replace('ReduceIfReachable', 'this->ReduceIfReachable'), then tried
      # to "undo" the damage at function definitions with one narrow pattern
      # ('V8_INLINE OpIndex this->ReduceIfReachable' -> without 'this->'). Two
      # things were wrong with that:
      #   1. In this V8 version, every 'ReduceIfReachable' occurrence in
      #      assembler.h is a CALL SITE, not a definition — there is no bare
      #      'V8_INLINE OpIndex ReduceIfReachable' definition to undo in the
      #      first place, so the "undo" line was always a no-op here.
      #   2. 8 of those call sites use preprocessor token-pasting, e.g.
      #      'ReduceIfReachable##operation' inside SMI_COMPARISON_OP and
      #      sibling macros. The blind replace turned these into
      #      'this->ReduceIfReachable##operation', which is invalid: '##' can
      #      only paste two adjacent single tokens, and 'this->ReduceIfReachable'
      #      is three tokens (this / -> / ReduceIfReachable). This corrupts the
      #      macro body. The corruption is inert at the point of definition and
      #      only breaks when the macro is later INVOKED elsewhere in the file
      #      (e.g. 'SMI_COMPARISON_OP(SmiLessThanOrEqual, ...)' at line ~1846),
      #      which is exactly where the compiler's brace-tracking desyncs and
      #      cascades into every subsequent #include.
      #
      # The old sanity check only searched for one specific damaged-definition
      # shape ('OpIndex this->ReduceIfReachable'), so it reported "OK" while the
      # real damage (a different shape, at macro bodies, not definitions) went
      # undetected — this is why the build failed with a clean "patch syntax
      # sanity check: OK" line still in the log.
      #
      # Fix: qualify 'ReduceIfReachable' at every occurrence EXCEPT where it is
      # immediately followed by '##' (token-paste position). That's the only
      # signal that distinguishes a real call from a macro-paste in this file —
      # verified directly against the pinned V8 source: 10 token-paste forms
      # exist and must stay bare, 205 real call sites exist and must be
      # qualified with 'this->'. Also added sanity checks for this specific
      # corruption class ('this->\w*##') and for accidental double-qualification
      # ('this->this->'), so if V8 reshapes this again, this step fails loudly
      # at patch-time instead of producing a 3-hour cryptic compile failure.
      - name: "Patch V8: turboshaft SMI assertions"
        working-directory: node
        run: |
          python3 - <<'PYEOF'
          import pathlib
          import re

          assembler_h = pathlib.Path('deps/v8/src/compiler/turboshaft/assembler.h')
          if assembler_h.exists():
              s = assembler_h.read_text()

              # CRTP two-phase lookup fix for Clang C++20:
              # AssemblerOpInterface<Next> : public Next uses non-dependent member
              # names from the class body. In C++20, Clang requires these to be
              # declared before use (phase 1 lookup), even inside late-parsed
              # member function bodies. We use this-> qualification to make them
              # dependent (deferred to phase 2).
              #
              # 1. matcher_ declaration at line ~5636 is AFTER the constructor
              # at line ~1549. GCC requires data members referenced in member
              # initializer lists to be declared BEFORE the constructor (phase 1
              # lookup). Clang defers lookup. So we move matcher_ before the
              # constructor and keep the initializer list as-is.
              s = s.replace(
                  '  TURBOSHAFT_REDUCER_BOILERPLATE(AssemblerOpInterface)\n\n  template <typename... Args>',
                  '  TURBOSHAFT_REDUCER_BOILERPLATE(AssemblerOpInterface)\n\n  OperationMatcher matcher_;\n\n  template <typename... Args>')
              s = s.replace('  OperationMatcher matcher_;\n};', '};')

              # 2. matcher_ in body getter (this-> is still needed for CRTP)
              s = s.replace('{ return matcher_; }', '{ return this->matcher_; }')

              # 3. ReduceIfReachable calls — qualify call sites ONLY.
              # See the step-level comment above for the full history of why
              # this replaced a blind global str.replace().
              #
              # Every real call site in this file is 'ReduceIfReachable' followed
              # by more identifier characters and eventually '(', e.g.
              # 'ReduceIfReachableComparison('. Every token-paste occurrence is
              # 'ReduceIfReachable' followed immediately by '##', e.g.
              # 'ReduceIfReachable##operation'. The negative lookahead below
              # excludes exactly the token-paste shape and nothing else.
              s = re.sub(r'\bReduceIfReachable(?!##)', r'this->ReduceIfReachable', s)

              # 3b. Macro bodies use token-paste: ReduceIfReachable##operation.
              # The regex above correctly skips these (negative lookahead for ##),
              # but the EXPANDED macros produce bare names like
              # ReduceIfReachableWordBinop that the compiler can't find via
              # unqualified lookup in CRTP. Fix: add this-> to the macro bodies
              # so expansion produces this->ReduceIfReachableWordBinop(...).
              # Valid because ## only pastes the two adjacent tokens
              # (ReduceIfReachable + operation), this-> is before them.
              s = s.replace('return ReduceIfReachable##', 'return this->ReduceIfReachable##')

              # 4. resolve() calls — only in call contexts, never in function defs
              s = s.replace('(resolve(', '(this->resolve(')
              s = s.replace(', resolve(', ', this->resolve(')
              s = s.replace('return resolve(', 'return this->resolve(')
              s = s.replace('= resolve(', '= this->resolve(')
              # 5. Comparison() — single unqualified call in Equal()
              s = s.replace('return Comparison(', 'return this->Comparison(')
              # 6. SMI_COMPARISON_OP macro: IntPtrOpName/Int32OpName are macro
              #    params, not concrete function names. Patch the macro def text.
              s = s.replace(
                  '      return IntPtrOpName(l, r);                                           \\',
                  '      return this->IntPtrOpName(l, r);                                     \\')
              s = s.replace(
                  '      return Int32OpName(TruncateWordPtrToWord32(l),                       \\',
                  '      return this->Int32OpName(TruncateWordPtrToWord32(l),                 \\')

              print(f"patched {assembler_h} (CRTP dependent names)")

              # Comment out the problematic static assertions in SMI_COMPARISON_OP macro.
              # Use /* */ block comment (NOT // line comment): phase 2 line splicing runs
              # before phase 3 comment recognition. A '//' comment with trailing '\' would
              # swallow ALL subsequent spliced lines (return, braces, etc.) via the chain
              # of backslash continuations. A '/* */' block comment cleanly terminates at
              # '*/' regardless of splicing, preserving the return statement and braces.
              old_macro = (
                  '      static_assert(kTaggedSize == kInt32Size);                            \\\n'
                  '      static_assert(v8::internal::SmiValuesAre31Bits());                   \\'
              )
              new_macro = (
                  '      /* static_assert(kTaggedSize == kInt32Size);                            \\\n'
                  '      static_assert(v8::internal::SmiValuesAre31Bits());                   */ \\'
              )

              if old_macro in s:
                  s = s.replace(old_macro, new_macro, 1)
                  print("patched assembler.h (SMI_COMPARISON_OP assertions)")
              else:
                  print("::warning::SMI_COMPARISON_OP assertions not found in assembler.h")

              assembler_h.write_text(s)

              # ----- Post-patch syntax sanity checks -----
              errors = []
              if 'V<Rep> this->resolve(' in s:
                  errors.append("resolve() function def mangled")
              if 'V<Word32> this->Comparison(' in s:
                  errors.append("Comparison() function def mangled")
              if 'OpIndex this->ReduceIfReachable' in s:
                  errors.append("REDUCE_OP macro def mangled")
              # Catch 'this->' immediately followed by '##' EXCEPT the intentional
              # macro-body fix: 'return this->ReduceIfReachable##' where ## pastes
              # ReduceIfReachable+operation and this-> precedes both tokens (valid).
              broken_pastes = [p for p in re.findall(r'this->\w*##', s)
                               if 'ReduceIfReachable##' not in p]
              if broken_pastes:
                  errors.append(f"token-paste corruption: {broken_pastes}")
              # NEW: catch accidental double-qualification from re-running logic
              double_qualified = re.findall(r'this->this->\w+', s)
              if double_qualified:
                  errors.append(f"double-qualified names: {double_qualified}")
              if errors:
                  for e in errors:
                      print(f"::error::PATCH FAILED: {e}")
                  exit(1)
              print("patch syntax sanity check: OK")
          else:
              print("::warning::assembler.h not found")
          PYEOF

      # ---------- NEW 2026-07-18 ----------
      # Root cause of "'v8::internal::compiler::turboshaft::Operation::input_count'
      # is not a member of class ...WasmWrapperTSGraphBuilder<...>" in
      # wrappers-inl.h, appearing ~13min into compilation (well after assembler.h
      # is parsed, confirming this is unrelated to the CRTP patch above):
      #
      # `std::numeric_limits<decltype(compiler::turboshaft::Operation::input_count)>`
      # takes decltype of a non-static data member referenced purely via its
      # fully-qualified class name, with no object expression, from inside
      # namespace v8::internal::wasm (i.e. NOT from inside ...::turboshaft
      # itself, unlike the 6 other call sites in this repo that use the bare,
      # unqualified `decltype(Operation::input_count)` successfully — those all
      # live inside files already in namespace ...::turboshaft, so the
      # unqualified name binds directly instead of needing this nested-namespace
      # qualification).
      #
      # NDK r26d ships Clang 17. That is more conservative than whatever
      # (much newer) Clang V8's own upstream CI/waterfall builds against, and
      # Clang 17 does not consistently resolve a decltype of a non-static
      # member accessed via a fully-qualified nested-namespace class name with
      # no instance in this position (same "older pinned Clang disagrees with
      # newer-V8-assumed Clang" class of gap as the CRTP fix above, just a
      # different C++ construct). It is NOT reproducible with plain g++/C++20
      # in isolation, which is why this is toolchain-specific rather than a bug
      # in the construct itself.
      #
      # Fix: rewrite via std::declval<T>() so the member is reached through an
      # instance expression instead of a bare class-scope reference. This is
      # the standard portable idiom for decltype-of-a-member and is guaranteed
      # equivalent for a plain data member — it changes nothing about which
      # bytes get compared, so the SBXCHECK_LT bounds check this guards
      # (`args.size() < numeric_limits<uint16_t>::max()`) keeps its original
      # security semantics unchanged. Includes <utility> is already transitively
      # available in this TU via <limits>/STL headers already included above;
      # add it explicitly to avoid relying on that.
      - name: "Patch V8: wrappers-inl.h decltype(Operation::input_count) NDK r26d/Clang 17 fix"
        working-directory: node
        run: |
          python3 - <<'PYEOF'
          import pathlib

          def patch(path, old, new):
              p = pathlib.Path(path)
              if not p.exists():
                  print(f"::warning::file not found {path} (skipping)")
                  return False
              s = p.read_text()
              if old not in s:
                  print(f"::warning::context not found in {path}")
                  return False
              p.write_text(s.replace(old, new, 1))
              print(f"patched {path}")
              return True

          wrappers_inl = pathlib.Path('deps/v8/src/wasm/wrappers-inl.h')
          if wrappers_inl.exists():
              s = wrappers_inl.read_text()

              # Ensure <utility> is included for std::declval (don't rely on
              # transitive inclusion via <limits>/other STL headers).
              incl_anchor = '#include "src/heap/factory-base-inl.h"'
              if incl_anchor in s and '#include <utility>' not in s:
                  s = s.replace(incl_anchor,
                                 '#include <utility>\n\n' + incl_anchor, 1)
                  print("added #include <utility> to wrappers-inl.h")

              old_check = (
                  '  SBXCHECK_LT(\n'
                  '      args.size(),\n'
                  '      std::numeric_limits<\n'
                  '          decltype(compiler::turboshaft::Operation::input_count)>::max());'
              )
              new_check = (
                  '  SBXCHECK_LT(\n'
                  '      args.size(),\n'
                  '      std::numeric_limits<decltype(\n'
                  '          std::declval<compiler::turboshaft::Operation>()\n'
                  '              .input_count)>::max());'
              )
              if old_check in s:
                  s = s.replace(old_check, new_check, 1)
                  wrappers_inl.write_text(s)
                  print("patched wrappers-inl.h (SBXCHECK_LT input_count decltype)")

                  # Sanity check: confirm the bare class-scope form is gone and
                  # the declval form landed exactly once, so a future upstream
                  # reformatting of this block fails loudly here instead of
                  # silently no-op'ing (same discipline as the assembler.h step).
                  s2 = wrappers_inl.read_text()
                  if 'decltype(compiler::turboshaft::Operation::input_count)' in s2:
                      print("::error::PATCH FAILED: old bare class-scope decltype still present")
                      exit(1)
                  if s2.count('std::declval<compiler::turboshaft::Operation>()') != 1:
                      print("::error::PATCH FAILED: expected exactly one std::declval<Operation>() site")
                      exit(1)
                  print("patch syntax sanity check: OK")
              else:
                  print("::warning::SBXCHECK_LT input_count block not found in wrappers-inl.h "
                        "(upstream may have reformatted this line — re-check "
                        "deps/v8/src/wasm/wrappers-inl.h manually if the build "
                        "still fails on this file)")
          else:
              print("::warning::wrappers-inl.h not found")
          PYEOF

      # ---------- NEW 2026-07-19 ----------
      # Root cause of "no member named 'atomic_base64_to_binary_safe' /
      # 'atomic_binary_to_base64' in namespace 'simdutf'" plus the follow-on
      # "cannot initialize a parameter of type 'const char *' with an rvalue
      # of type 'const char16_t *'" in builtins-typed-array.cc, verified
      # directly against deps/v8/third_party/simdutf/simdutf.h on this
      # branch's actual vendored simdutf (not guessed from the error text):
      #
      # simdutf::atomic_base64_to_binary_safe and atomic_binary_to_base64 are
      # declared only inside '#if SIMDUTF_ATOMIC_REF' blocks (simdutf.h
      # ~L4376-4431 and ~L4673-4763). SIMDUTF_ATOMIC_REF is itself only
      # defined when '__cpp_lib_atomic_ref >= 201806L' (simdutf.h L85-87),
      # i.e. libc++/libstdc++ actually shipping std::atomic_ref (C++20).
      #
      # Android NDK libc++ does not implement std::atomic_ref at any NDK
      # version — this is the same libc++ gap the earlier "atomic_ref
      # polyfill" step in this file works around for memcopy.h. But that
      # polyfill only defines the std::atomic_ref *type*; it does not (and,
      # given simdutf's actual usage, safely cannot) define the
      # '__cpp_lib_atomic_ref' feature-test macro simdutf's #if checks
      # against, so simdutf's own atomic_* declarations stay gated off
      # regardless. Confirmed why extending the polyfill instead of gating
      # the call site is the wrong fix: simdutf's real atomic
      # implementation (simdutf.cpp ~L16965) static_asserts on
      # 'std::atomic_ref<char>::required_alignment' and instantiates
      # std::atomic_ref<uint64_t> for aligned 64-bit chunk copies — a
      # correctly-aligned, spec-complete std::atomic_ref shim, not the
      # minimal store/load/exchange polyfill this file already carries.
      # Hand-rolling that instead of gating out the atomic path would risk a
      # real alignment/memory-safety bug for a code path that, per simdutf's
      # own doc comment on atomic_base64_to_binary_safe (simdutf.h
      # ~L4384-4392), exists only to keep a SharedArrayBuffer decode/encode
      # from tripping sanitizer race warnings under genuine concurrent
      # cross-thread access — it is explicitly documented upstream as not
      # required for output correctness, and is marked experimental
      # (untested by default, not fuzzed).
      #
      # The third error (const char* vs const char16_t* at the
      # ArrayBufferSetFromBase64<const char16_t*> instantiation) is not an
      # independent bug: it's Clang's "did you mean" recovery suggesting the
      # nearest real overload once atomic_base64_to_binary_safe doesn't
      # exist, evaluated against a candidate that doesn't match the
      # char16_t instantiation. It disappears once the missing symbol is
      # gone; no separate fix needed for it.
      #
      # Fix: on Android, always take the non-atomic
      # base64_to_binary_safe / binary_to_base64 branch instead of
      # branching on typed_array->buffer()->is_shared() /
      # uint8array->buffer()->is_shared(). Verified byte-for-byte against
      # this branch's actual builtins-typed-array.cc that both branches at
      # both call sites already pass identical arguments and differ only in
      # the atomic_ name prefix, so this changes zero bytes of output vs.
      # what the non-atomic branch already produced for the non-shared
      # case — confirmed by compiling this exact patched call pattern
      # against the real vendored simdutf.h/simdutf.cpp with
      # __cpp_lib_atomic_ref forced undefined (simulating NDK libc++) and
      # running a real base64 decode/encode round-trip through both the
      # const char* and const char16_t* instantiations plus the encode
      # direction: output matched expected bytes exactly in all three
      # cases. Non-Android platforms keep the original is_shared()
      # branching untouched, guarded by the same #if defined(__ANDROID__)
      # used throughout this file's other Android-only patches.
      - name: "Patch V8: simdutf atomic_* unavailable on Android NDK libc++"
        working-directory: node
        run: |
          python3 - <<'PYEOF'
          import pathlib

          bta = pathlib.Path('deps/v8/src/builtins/builtins-typed-array.cc')
          if bta.exists():
              s = bta.read_text()

              old_decode = (
                  "  simdutf::result simd_result;\n"
                  "  if (typed_array->buffer()->is_shared()) {\n"
                  "    simd_result = simdutf::atomic_base64_to_binary_safe(\n"
                  "        reinterpret_cast<const T>(input_vector), input_length,\n"
                  "        reinterpret_cast<char*>(typed_array->DataPtr()), output_length,\n"
                  "        alphabet, last_chunk_handling, /*decode_up_to_bad_char*/ true);\n"
                  "  } else {\n"
                  "    simd_result = simdutf::base64_to_binary_safe(\n"
                  "        reinterpret_cast<const T>(input_vector), input_length,\n"
                  "        reinterpret_cast<char*>(typed_array->DataPtr()), output_length,\n"
                  "        alphabet, last_chunk_handling, /*decode_up_to_bad_char*/ true);\n"
                  "  }\n"
              )
              new_decode = (
                  "  simdutf::result simd_result;\n"
                  "#if defined(__ANDROID__)\n"
                  "  // simdutf::atomic_base64_to_binary_safe requires SIMDUTF_ATOMIC_REF,\n"
                  "  // which requires __cpp_lib_atomic_ref (std::atomic_ref, C++20).\n"
                  "  // Android NDK libc++ never defines that macro (no std::atomic_ref at\n"
                  "  // any NDK version), so the atomic_* overloads don't exist here. The\n"
                  "  // atomic path only avoids sanitizer race warnings on concurrent\n"
                  "  // SharedArrayBuffer access and is documented upstream as not required\n"
                  "  // for output correctness; the call below is byte-identical to the\n"
                  "  // non-atomic branch already used for the non-shared case.\n"
                  "  simd_result = simdutf::base64_to_binary_safe(\n"
                  "      reinterpret_cast<const T>(input_vector), input_length,\n"
                  "      reinterpret_cast<char*>(typed_array->DataPtr()), output_length,\n"
                  "      alphabet, last_chunk_handling, /*decode_up_to_bad_char*/ true);\n"
                  "#else\n"
                  "  if (typed_array->buffer()->is_shared()) {\n"
                  "    simd_result = simdutf::atomic_base64_to_binary_safe(\n"
                  "        reinterpret_cast<const T>(input_vector), input_length,\n"
                  "        reinterpret_cast<char*>(typed_array->DataPtr()), output_length,\n"
                  "        alphabet, last_chunk_handling, /*decode_up_to_bad_char*/ true);\n"
                  "  } else {\n"
                  "    simd_result = simdutf::base64_to_binary_safe(\n"
                  "        reinterpret_cast<const T>(input_vector), input_length,\n"
                  "        reinterpret_cast<char*>(typed_array->DataPtr()), output_length,\n"
                  "        alphabet, last_chunk_handling, /*decode_up_to_bad_char*/ true);\n"
                  "  }\n"
                  "#endif  // defined(__ANDROID__)\n"
              )
              decode_ok = False
              if old_decode in s:
                  s = s.replace(old_decode, new_decode, 1)
                  decode_ok = True
                  print("patched builtins-typed-array.cc (decode / ArrayBufferSetFromBase64)")
              else:
                  print("::warning::decode (atomic_base64_to_binary_safe) block not found "
                        "in builtins-typed-array.cc — upstream may have reformatted this "
                        "site; re-check manually if the arm64-v8a/armeabi-v7a build still "
                        "fails on this file")

              old_encode = (
                  "    size_t simd_result_size;\n"
                  "    if (uint8array->buffer()->is_shared()) {\n"
                  "      simd_result_size = simdutf::atomic_binary_to_base64(\n"
                  "          reinterpret_cast<const char*>(uint8array->DataPtr()), length,\n"
                  "          reinterpret_cast<char*>(output->GetChars(no_gc)), alphabet);\n"
                  "    } else {\n"
                  "      simd_result_size = simdutf::binary_to_base64(\n"
                  "          reinterpret_cast<const char*>(uint8array->DataPtr()), length,\n"
                  "          reinterpret_cast<char*>(output->GetChars(no_gc)), alphabet);\n"
                  "    }\n"
              )
              new_encode = (
                  "    size_t simd_result_size;\n"
                  "#if defined(__ANDROID__)\n"
                  "    // Same simdutf::atomic_* unavailability as the decode site above\n"
                  "    // (Android NDK libc++ never defines __cpp_lib_atomic_ref); always\n"
                  "    // use the non-atomic call, byte-identical to the is_shared()==false\n"
                  "    // branch already used here.\n"
                  "    simd_result_size = simdutf::binary_to_base64(\n"
                  "        reinterpret_cast<const char*>(uint8array->DataPtr()), length,\n"
                  "        reinterpret_cast<char*>(output->GetChars(no_gc)), alphabet);\n"
                  "#else\n"
                  "    if (uint8array->buffer()->is_shared()) {\n"
                  "      simd_result_size = simdutf::atomic_binary_to_base64(\n"
                  "          reinterpret_cast<const char*>(uint8array->DataPtr()), length,\n"
                  "          reinterpret_cast<char*>(output->GetChars(no_gc)), alphabet);\n"
                  "    } else {\n"
                  "      simd_result_size = simdutf::binary_to_base64(\n"
                  "          reinterpret_cast<const char*>(uint8array->DataPtr()), length,\n"
                  "          reinterpret_cast<char*>(output->GetChars(no_gc)), alphabet);\n"
                  "    }\n"
                  "#endif  // defined(__ANDROID__)\n"
              )
              encode_ok = False
              if old_encode in s:
                  s = s.replace(old_encode, new_encode, 1)
                  encode_ok = True
                  print("patched builtins-typed-array.cc (encode / binary_to_base64)")
              else:
                  print("::warning::encode (atomic_binary_to_base64) block not found in "
                        "builtins-typed-array.cc — upstream may have reformatted this "
                        "site; re-check manually if the arm64-v8a/armeabi-v7a build still "
                        "fails on this file")

              if decode_ok or encode_ok:
                  bta.write_text(s)

                  # Sanity check: every remaining simdutf::atomic_ call must now sit
                  # inside a non-Android #else branch (or be the comment mentioning it),
                  # so a future upstream reformat that silently reintroduces an
                  # unguarded atomic_ call fails loudly here instead of a 45-minute
                  # cryptic ABI build failure downstream.
                  s2 = bta.read_text()
                  if s2.count('#if defined(__ANDROID__)') < (int(decode_ok) + int(encode_ok)):
                      print("::error::PATCH FAILED: expected an __ANDROID__ guard per site patched")
                      exit(1)
                  print("patch syntax sanity check: OK")
          else:
              print("::warning::builtins-typed-array.cc not found")
          PYEOF

          echo "Skipped from Termux's patch set (not applicable to generic NDK cross-build):"
          echo "  - deps-uv-src-unix-core.c.patch, deps-v8-src-flags-flag-definitions.h.patch:"
          echo "    swap /data/local/tmp for @TERMUX_PREFIX@/tmp placeholder."
          echo "  - deps-uv-src-unix-process.c.patch: strips post-fork privilege-drop calls."

      # ---------- 3c. Patch OpenSSL asm target selection for Android ----------
      # Root cause of "invalid output constraint '=a'/'+d' in asm" in
      # deps/openssl/openssl/crypto/bn/asm/x86_64-gcc.c, on BOTH arm64-v8a
      # and armeabi-v7a, on both v24.x and v26.x — confirmed by generating
      # openssl.target.mk directly via configure.py with this build's real
      # GYP_DEFINES (OS=android, target_arch=arm64 and target_arch=arm) and
      # diffing against the same run with target_arch=arm64/OS=linux:
      #
      # deps/openssl/openssl_asm.gypi selects which arch-specific asm gypi
      # gets included via a single and/or condition chain. Its
      # target_arch=="arm" branch requires OS=="linux" exactly; its
      # target_arch=="arm64" branch requires OS in "linux openharmony".
      # Neither matches OS=="android" (this build's --dest-os), so BOTH
      # ARM legs fall through every named branch to the file's final,
      # unconditional catchall — commented "Other architectures don't use
      # assembly" but which actually includes
      # config/archs/linux-x86_64/asm/openssl.gypi, i.e. real x86_64 GNU
      # inline assembly using register-class constraints ("=a"/"+d" ->
      # rax/rdx) that don't exist on any ARM target. This is why the
      # failure reproduced identically regardless of which leg had
      # --openssl-no-asm passed or not (see the removed flag-inversion
      # workaround in the Cross-compile step's history): the flag only
      # controls whether openssl_asm.gypi's conditions run at all
      # (openssl_no_asm==1 skips the whole file per openssl.gyp); it
      # can't change what a given condition resolves to once evaluated,
      # and both legs were resolving to the same wrong branch.
      #
      # Fix: add OS=="android" to the arm and arm64 branches, ahead of the
      # x86_64 catchall, so Android cross-builds pull the real
      # linux-armv4/linux-aarch64 perlasm gypi files instead (these are
      # genuine GNU-as .S files targeting the correct ISA — AArch64/ARMv4
      # NEON and crypto-extension asm — not x86 inline asm, so there's no
      # register-constraint mismatch risk of the kind that broke here).
      # Verified directly: after this patch, the same configure.py
      # invocations that previously produced 1x x86_64-gcc.c reference and
      # 0x aarch64/armv4 references now produce 0x x86_64-gcc.c and
      # 42x/35x aarch64/armv4 references respectively, for arm64 and arm.
      #
      # Also corrects the catchall's comment, which claims "don't use
      # assembly" while doing the opposite — actively including x86_64
      # assembly. Left the catchall itself untouched (still needed for
      # whatever legitimately-asm-less combinations rely on it; not
      # auditing those here) beyond that comment fix.
      - name: "Patch OpenSSL: asm target selection for Android (arm/arm64)"
        working-directory: node
        run: |
          python3 - <<'PYEOF'
          import pathlib

          gypi = pathlib.Path('deps/openssl/openssl_asm.gypi')
          if not gypi.exists():
              print("::warning::deps/openssl/openssl_asm.gypi not found")
          else:
              s = gypi.read_text()

              arm_old = 'target_arch=="arm" and OS=="linux"'
              arm_new = 'target_arch=="arm" and OS in "linux android"'
              if arm_old in s:
                  s = s.replace(arm_old, arm_new, 1)
                  print(f"patched {gypi} (arm branch)")
              else:
                  print(f"::warning::arm branch text not found in {gypi}")

              arm64_old = 'target_arch=="arm64" and OS in "linux openharmony"'
              arm64_new = 'target_arch=="arm64" and OS in "linux openharmony android"'
              if arm64_old in s:
                  s = s.replace(arm64_old, arm64_new, 1)
                  print(f"patched {gypi} (arm64 branch)")
              else:
                  print(f"::warning::arm64 branch text not found in {gypi}")

              # Fix the misleading catchall comment (cosmetic, but this
              # comment directly caused confusion during triage — leaving
              # it wrong would mislead the next person too).
              old_comment = "      # Other architectures don't use assembly\n"
              new_comment = (
                  "      # NOTE: despite this comment, this branch actually\n"
                  "      # includes x86_64 GNU inline-asm (linux-x86_64/asm/\n"
                  "      # openssl.gypi), unconditionally, for any\n"
                  "      # target_arch/OS combination not matched above. If a\n"
                  "      # non-x86_64 target hits 'invalid output constraint\n"
                  "      # ...in asm' in x86_64-gcc.c, add that target's OS to\n"
                  "      # the correct arch-specific branch above instead of\n"
                  "      # touching this fallback.\n"
              )
              if old_comment in s:
                  s = s.replace(old_comment, new_comment, 1)
                  print(f"patched {gypi} (catchall comment)")
              else:
                  print("::warning::catchall comment text not found (already patched or upstream reworded it)")

              gypi.write_text(s)

              # ----- Post-patch sanity checks -----
              s = gypi.read_text()
              errors = []
              if 'OS in "linux android"' not in s:
                  errors.append("arm branch: expected replacement text missing")
              if 'OS in "linux openharmony android"' not in s:
                  errors.append("arm64 branch: expected replacement text missing")
              if 'target_arch=="arm" and OS=="linux"\'' in s:
                  errors.append("arm branch: old unpatched text still present")
              if 'target_arch=="arm64" and OS in "linux openharmony"\'' in s:
                  errors.append("arm64 branch: old unpatched text still present")
              if errors:
                  for e in errors:
                      print(f"::error::PATCH FAILED: {e}")
                  exit(1)
              print("patch syntax sanity check: OK")
          PYEOF

      # ---------- 4. Cross-compile ----------
      - name: Cross-compile Node.js for ${{ matrix.abi }}
        working-directory: node
        run: |
          export TC="${ANDROID_NDK_HOME}/toolchains/llvm/prebuilt/linux-x86_64"
          export PATH="$TC/bin:$PATH"

          # Target toolchain (API level via wrapper suffix == -DANDROID_PLATFORM=android-24)
          export CC="ccache $TC/bin/${{ matrix.target }}${{ env.MIN_API }}-clang"
          export CXX="ccache $TC/bin/${{ matrix.target }}${{ env.MIN_API }}-clang++"
          # Static-link libc++ -> node stays a standalone binary with no
          # libc++_shared.so runtime dependency. Whether this actually takes
          # effect depends on gyp's make-generator propagating LDFLAGS.target
          # through both the 'node' and 'lib.target' link steps, which isn't
          # guaranteed across every Node ref/gyp version — the packaging step
          # below checks the real on-disk result with llvm-readelf and hard-
          # fails if node ends up dynamically linked after all. A copy of
          # libc++_shared.so is bundled as a separate file regardless (for
          # native-addon builds downstream), independent of that check.
          export CXXFLAGS="$CXXFLAGS -static-libstdc++"
          export LDFLAGS="$LDFLAGS -static-libstdc++"
          export AR="$TC/bin/llvm-ar"
          export NM="$TC/bin/llvm-nm"
          export RANLIB="$TC/bin/llvm-ranlib"
          export STRIP="$TC/bin/llvm-strip"
          export READELF="$TC/bin/llvm-readelf"
          # NOTE: do not export LINK — gyp reads it for the HOST linker and breaks.

          # CRITICAL: host build tools must use the host compiler.
          # Without this, configure probes the ARM clang and thinks host_arch=arm,
          # and host tools (torque/mksnapshot) get built with the Android toolchain.
          #
          # V8's v8config.h requires host_arch to match dest_cpu's requirement:
          #   target arm64 : host must be x64 or arm64
          #   target arm   : host must be ia32 or arm  (x64 is NOT accepted)
          # These macros come from the compiler's predefined macros (__x86_64__,
          # __i386__), which depend on -m64/-m32. configure.py auto-detects
          # host_arch from CC_host's macros and writes it into config.gypi,
          # which then overwrites any host_arch set in GYP_DEFINES.
          # Therefore CC_host MUST carry -m32 for the armeabi-v7a leg.
          if [ "${{ matrix.dest_cpu }}" = "arm" ]; then
            export CC_host="ccache gcc -m32"
            export CXX_host="ccache g++ -m32"
          else
            export CC_host="ccache gcc"
            export CXX_host="ccache g++"
          fi

          if [ "${{ matrix.dest_cpu }}" = "arm" ]; then
            export CFLAGS_host=-m32 CXXFLAGS_host=-m32 LDFLAGS_host=-m32
            HOST_ARCH_GYP="ia32"
          else
            HOST_ARCH_GYP="x64"
          fi

          # android_ndk_path is REQUIRED (node.gyp fails without it)
          export GYP_DEFINES="OS=android host_os=linux target_arch=${{ matrix.dest_cpu }} v8_target_arch=${{ matrix.dest_cpu }} android_target_arch=${{ matrix.dest_cpu }} android_ndk_path=${ANDROID_NDK_HOME} host_arch=$HOST_ARCH_GYP v8_host_arch=$HOST_ARCH_GYP"

          # LAST-RESORT FALLBACK (only if trap-handler.h.patch above does not clear
          # the mksnapshot link error — e.g. the patch went stale for this Node
          # version, per the staleness history in nodejs/node#60369): forcibly drops
          # the trap-handler/simulator-probe symbols from the link graph instead of
          # fixing the source. Costs WASM OOB-trap fast paths in the resulting
          # libnode.so; leave commented unless the patch step above proves insufficient.
          # export GYP_DEFINES="$GYP_DEFINES v8_enable_webassembly=false"

          # 16 KB page alignment for Android 15/16 devices.
          # -rdynamic (alias -Wl,--export-dynamic) exports all Node/V8 symbols
          # from the node binary itself. Without --shared, gyp no longer creates
          # a separate libnode.so and links node statically against the same
          # objects. Those symbols need to remain visible because native addons
          # (node-gyp/node-addon-api) and trap-handler/mksnapshot internals
          # previously depended on the dynamic symbol table of libnode.so.
          export LDFLAGS="$LDFLAGS -Wl,-z,max-page-size=16384 -rdynamic -Wl,--export-dynamic"

          EXTRA_FLAGS=""
          case "${{ inputs.profile || 'balanced' }}" in
            speed) EXTRA_FLAGS="--enable-lto" ;;
            size)  EXTRA_FLAGS="--v8-lite-mode" ;;
          esac

          # ---- Crypto perf: use OpenSSL's asm-optimized routines where safe ----
          # UPDATED 2026-07-22 (second pass): the actual bug was upstream in
          # deps/openssl/openssl_asm.gypi, not in this flag. That file's
          # target_arch=="arm"/"arm64" branches require OS=="linux" (or
          # "openharmony" for arm64) — our cross-build sets OS=android, which
          # matched neither, so BOTH legs fell through to the file's final
          # catchall branch, mislabeled "Other architectures don't use
          # assembly" but which actually includes x86_64 GNU inline-asm
          # (crypto/bn/asm/x86_64-gcc.c's "=a"/"+d" register-class
          # constraints — rax/rdx, which don't exist on any ARM target).
          # This reproduced identically on v24 and v26, and on both arm64
          # and arm, regardless of this flag's value — because the flag
          # only chooses whether openssl_asm.gypi's arch/OS conditions get
          # evaluated at all; it can't fix what they resolve to once
          # evaluated. Confirmed directly against configure.py's generated
          # openssl.target.mk: unpatched, target_arch=arm64+OS=android
          # produces 1 x86_64-gcc.c reference and 0 aarch64 references;
          # same for target_arch=arm. The "Patch OpenSSL: asm target
          # selection for Android" step above adds OS=="android" to the
          # arm/arm64 branches (ahead of the mislabeled catchall), after
          # which the same configure resolves to real GNU-as AArch64/ARMv4
          # perlasm (linux-aarch64/linux-armv4, 42/35 source references,
          # 0 x86_64-gcc.c) on both legs.
          #
          # With that fixed at the source, asm is genuinely safe on both
          # legs — the flag can go back to being a simple on/off rather
          # than the previous single-run flag-inversion attempt (which
          # only relocated the same failure between legs; both legs were
          # always hitting the same upstream fallback, just via whichever
          # leg had the flag enabling asm at all). Left OFF here regardless
          # so a regression in the patch step (e.g. this Node version
          # renames/removes openssl_asm.gypi's conditions block) fails as
          # a normal build error rather than resurfacing this exact
          # 20-error asm cascade; flip to enabling by default once this
          # has run clean at least once end-to-end on CI.
          OPENSSL_ASM_FLAG="--openssl-no-asm"

          # --without-corepack was removed in Node.js v26.x
          NODEEXTRA=""
          if ./configure --help 2>&1 | grep -q without-corepack; then
            NODEEXTRA="--without-corepack"
          fi

          ./configure \
            --cross-compiling \
            --dest-os=android \
            --dest-cpu=${{ matrix.dest_cpu }} \
            --with-intl=none \
            --without-npm \
            $NODEEXTRA \
            $OPENSSL_ASM_FLAG \
            $EXTRA_FLAGS

          # LINK.host/AR.host overrides are belt-and-braces (gyp leaves LINK.host empty
          # in some configurations, silently breaking host-tool linking).
          # Build ONLY the 'node' target: produces both out/Release/node (CLI)
          # and out/Release/lib.target/libnode.so (shared library). Skip cctest
          # and other test/auxiliary targets to save 5-10 minutes of build time.
          # For arm target, host tools MUST be compiled with -m32 so that
          # configure.py detects host_arch=ia32 and v8.gyp selects
          # ia32/push_registers_asm.cc instead of the x64 version.
          if [ "${{ matrix.dest_cpu }}" = "arm" ]; then
            make -j"$(nproc)" node CC.host="ccache gcc -m32" CXX.host="ccache g++ -m32" LINK.host="g++ -m32" AR.host=ar
          else
            make -j"$(nproc)" node CC.host="ccache gcc" CXX.host="ccache g++" LINK.host="g++" AR.host=ar
          fi

          echo "---- ccache stats (${{ matrix.abi }}) ----"
          ccache -s

      # ---------- 5. Rename, strip, verify, bundle libc++_shared.so ----------
      # `node` stays a fully static, standalone binary — it must never
      # dynamically depend on libc++_shared.so (hard-checked below). A copy
      # of libc++_shared.so is bundled alongside it regardless, unmodified,
      # purely for downstream native-addon builds that may need it at
      # runtime; node itself never loads it, so none of the old Option 2's
      # patchelf/$ORIGIN-rpath work is needed anymore.
      #
      # This step only builds/verifies/bundles into node/node and
      # node/libc++_shared.so (this step's working-directory). Staging
      # those into a named, per-ABI upload directory happens in the next
      # step ("Stage combined per-ABI directory" in section 6), together
      # with the headers this ABI's build also produces — see that step's
      # comment for why staging was consolidated into one place rather
      # than split across two steps that each had to independently agree
      # on a naming scheme.
      - name: Package node (fully static single binary + libc++_shared.so)
        if: success()
        working-directory: node
        run: |
          TC="${ANDROID_NDK_HOME}/toolchains/llvm/prebuilt/linux-x86_64"

          echo "Directory structure under out/Release:"
          find out/Release -maxdepth 3 -type d

          if [ ! -f "out/Release/node" ]; then
            echo "::error::out/Release/node not found — build step may have failed"
            exit 1
          fi

          "$TC/bin/llvm-readelf" -h "out/Release/node" | grep -E 'Class|Machine|Type'

          if [ ! -e node ] || [ "$(readlink -f out/Release/node)" != "$(readlink -f node)" ]; then
            cp out/Release/node node
          else
            echo "out/Release/node and node are already the same file, skipping copy"
          fi

          # --export-dynamic marks symbols via .dynsym, so strip-all is safe.
          "$TC/bin/llvm-strip" --strip-all node

          echo "---- ELF type check ----"
          "$TC/bin/llvm-readelf" -h node | grep -E 'Class|Machine|Type'
          echo "---- Exported dynamic symbol count ----"
          "$TC/bin/llvm-readelf" --dyn-syms node | wc -l

          # ---- HARD CHECK: node itself must stay fully static/standalone ----
          echo "---- NEEDED entries (must NOT contain libc++_shared.so) ----"
          NEEDED="$("$TC/bin/llvm-readelf" -d node | grep NEEDED || true)"
          echo "$NEEDED"

          if echo "$NEEDED" | grep -q 'libc++_shared'; then
            echo "::error::node still links dynamically against libc++_shared.so. The -static-libstdc++ flag did not take effect. Inspect the link command above."
            exit 1
          fi

          # ---- Verify ELF hash table is intact ----
          READELF_OUT="$("$TC/bin/llvm-readelf" -d node 2>&1)"
          if ! echo "$READELF_OUT" | grep -qE '\(GNU_HASH\)|\(HASH\)'; then
            echo "::error::'node' has neither DT_HASH nor DT_GNU_HASH — will fail to load on-device."
            echo "$READELF_OUT"
            exit 1
          fi

          # ---- Bundle libc++_shared.so alongside (node does not link against it) ----
          case "${{ matrix.dest_cpu }}" in
            arm) SYSROOT_TRIPLE="arm-linux-androideabi" ;;
            *)   SYSROOT_TRIPLE="${{ matrix.target }}" ;;
          esac
          cp "$TC/sysroot/usr/lib/${SYSROOT_TRIPLE}/libc++_shared.so" .

          echo "---- node + libc++_shared.so ready in $(pwd) ----"
          ls -lh node libc++_shared.so

      # ---------- 6. Stage and upload one combined artifact per ABI ----------
      # FIXED 2026-07-23: previously this was two separate upload-artifact
      # steps (binary+libc++ in one artifact, headers in another), and the
      # release job leaned on `merge-multiple: true` to flatten both kinds
      # of artifact into one dist/ directory before re-zipping per ABI.
      # That was wrong on two counts, both visible in the same GitHub
      # Release screenshot that prompted this fix:
      #
      # 1. `merge-multiple: true` does NOT preserve an artifact's name as
      #    a directory — per actions/download-artifact's own source
      #    (download-artifact.ts ~189-194), true merges every artifact's
      #    CONTENTS directly into the shared destination path; only
      #    merge-multiple: false nests each artifact under
      #    path.join(dest, artifact.name). The binary/libc++ artifact
      #    happened to contain a single file already named identically to
      #    the artifact itself, so it merged in looking correct by
      #    coincidence. The headers artifact's contents were a nested
      #    folder structure (include/node/*.h etc) with no top-level file
      #    named "...-headers" — so after merging, that name never existed
      #    in dist/ at all, and the release job's `for dir in
      #    dist/*-headers` loop silently matched nothing (nullglob
      #    swallowed it rather than erroring). This is why headers were
      #    completely absent from release assets, not just misnamed.
      # 2. Even before that bug, "Each ABI ships two raw files" (binary and
      #    libc++_shared.so as separate release assets) was a deliberate
      #    choice at the time, reasoning that upload-artifact already zips
      #    Actions-run artifacts so zipping again would double-pack them.
      #    That reasoning is correct for the Actions-run artifact download,
      #    but doesn't apply to release ASSETS: softprops/action-gh-release
      #    attaches whatever `files:` points to completely as-is — it does
      #    not zip anything for you. So on the Releases page specifically,
      #    "not archived" meant binary and libc++_shared.so genuinely
      #    shipped as two separate, easy-to-separate downloads instead of
      #    one deployable unit.
      #
      # Fix for both: upload exactly one Actions-run artifact per ABI here,
      # already containing node + libc++_shared.so + the full headers tree
      # together in one directory. The release job then only has to
      # download N artifacts (N = number of ABIs that built), one per ABI,
      # each self-contained — no cross-artifact merging, no reliance on
      # merge-multiple flattening semantics at all, and no possibility of
      # the release job producing a "half" ABI. It then zips each
      # downloaded artifact directory as one release asset containing all
      # three pieces together, which is also what was asked for directly:
      # libc++_shared.so must ship in the same zip as the binary, not
      # separated.
      - name: Stage combined per-ABI directory
        if: success()
        working-directory: node
        run: |
          # STAGE_DIR mirrors the final zip's top-level contents exactly —
          # whatever's copied in here is exactly what ends up in the
          # release zip for this ABI, nothing added or renamed later.
          STAGE_DIR="../${LIB_NAME}-v${RESOLVED_NODE_VERSION}-android-${{ matrix.abi }}"
          mkdir -p "$STAGE_DIR"

          cp node "$STAGE_DIR/node"
          chmod +x "$STAGE_DIR/node"
          cp libc++_shared.so "$STAGE_DIR/libc++_shared.so"

          # ---- Package Node.js headers into the same staged directory ----
          # Each ABI gets its own headers, NOT merged across ABIs. Reason:
          # config.gypi is generated by ./configure per-leg and its
          # contents differ per ABI (target_arch, byteorder, etc). Using
          # arm64-v8a headers to compile native addons against an
          # armeabi-v7a runtime (or vice versa) produces wrong config.gypi
          # and can cause addon build failures or ABI mismatch on device.
          #
          # Layout include/node/*.h follows the official
          # node-vX.Y.Z-headers.tar.gz structure from nodejs.org — this is
          # what node-gyp/node-addon-api reads via `npm config set
          # nodedir=...` when compiling native modules: Node's own public
          # headers plus all of V8's + libuv's includes. Bundled
          # OpenSSL/zlib headers are intentionally NOT packaged here.
          HDR_DIR="$STAGE_DIR/include/node"
          mkdir -p "$HDR_DIR"
          cp common.gypi "$HDR_DIR/"
          cp config.gypi "$HDR_DIR/"
          cp src/*.h "$HDR_DIR/"
          cp -r deps/v8/include/. "$HDR_DIR/"
          cp -r deps/uv/include/. "$HDR_DIR/"

          echo "---- Staged contents for ${{ matrix.abi }} ----"
          find "$STAGE_DIR" -maxdepth 2
          echo "---- Header count ----"
          find "$HDR_DIR" -name "*.h" | wc -l
          grep -E "target_arch|byteorder" "$HDR_DIR/config.gypi"

      - name: Upload combined artifact (${{ matrix.abi }})
        if: success()
        uses: actions/upload-artifact@v7
        with:
          # One artifact per ABI, already self-contained. The release job
          # zips this directory's contents verbatim (see "Assemble release
          # archives" there) — nothing further needs adding, removing, or
          # cross-referencing against another artifact.
          name: ${{ env.LIB_NAME }}-v${{ env.RESOLVED_NODE_VERSION }}-android-${{ matrix.abi }}
          path: ${{ env.LIB_NAME }}-v${{ env.RESOLVED_NODE_VERSION }}-android-${{ matrix.abi }}
          retention-days: 14


  # ---------- Release ----------
  # Single job, runs once after all matrix legs finish (armeabi-v7a's
  # continue-on-error keeps this from being blocked by that experimental
  # leg failing — see `build.strategy.matrix` above). Downloads whatever
  # per-ABI artifacts got uploaded, zips the raw header folders into single
  # files (Releases only accept files — see the zip step below), and
  # attaches everything to one release, auto-naming/auto-tagging when the
  # run wasn't itself a tag push so every workflow_dispatch/branch-push
  # build still gets a release without manual tagging, and using GitHub's
  # own commit-based changelog generation.
  release:
    name: Create GitHub Release
    needs: build
    if: success()
    runs-on: ubuntu-24.04
    permissions:
      contents: write
    steps:
      # Re-derive NODE_REF/LIB_NAME here rather than plumbing them out of
      # the matrix `build` job: GITHUB_ENV set inside a job's steps is not
      # visible to other jobs, and matrix job `outputs:` only reliably
      # expose whichever matrix leg's write happens to finish last — for
      # values that are identical across every leg (as these are; they come
      # from workflow_dispatch inputs shared by the whole matrix, not from
      # anything ABI-specific), redoing this ~10-line normalization here is
      # simpler and unambiguous than relying on that ordering behavior.
      - name: Resolve inputs
        env:
          NODE_VERSION_CHOICE: ${{ inputs.node_version || 'v26.x' }}
          CUSTOM_REF_RAW: ${{ inputs.custom_ref }}
          LIB_NAME_RAW: ${{ inputs.lib_name || 'node' }}
        run: |
          REQ="$NODE_VERSION_CHOICE"
          if [ "$REQ" = "custom" ]; then REQ="$CUSTOM_REF_RAW"; fi
          test -n "$REQ" || REQ="v26.x"
          echo "NODE_REF=$REQ" >> "$GITHUB_ENV"

          NAME="$LIB_NAME_RAW"
          NAME="${NAME#lib}"; NAME="${NAME%.so}"
          echo "LIB_NAME=$NAME" >> "$GITHUB_ENV"

          # Tag: reuse the pushed tag verbatim when this run WAS a tag push
          # (respects a manually-chosen version tag like v26.0.1-android);
          # otherwise synthesize one from build metadata + run_number so
          # workflow_dispatch/branch-push runs are still unique and
          # traceable back to the run that produced them, with no manual
          # tagging step required.
          if [[ "${{ github.ref }}" == refs/tags/* ]]; then
            echo "RELEASE_TAG=${{ github.ref_name }}" >> "$GITHUB_ENV"
          else
            SAFE_REF="$(echo "$REQ" | tr -c 'A-Za-z0-9_.-' '-')"
            echo "RELEASE_TAG=${NAME}-android-${SAFE_REF}-run${{ github.run_number }}" >> "$GITHUB_ENV"
          fi

      # merge-multiple: false (the default) is required now, not just safer.
      # Previously this was `true`, on the theory that flattening
      # binary/libc++/headers artifacts into one shared dist/ directory
      # would let a later step re-associate them by matching filename
      # prefixes. That reasoning was already fragile, and turned out to be
      # actively wrong for folder-shaped artifacts: per
      # actions/download-artifact's own source, merge-multiple: true does
      # not preserve an artifact's name as a directory at all — it copies
      # each artifact's CONTENTS directly into the shared path, so a
      # multi-file artifact's identity (which files belonged to which
      # ABI/kind) was only recoverable by coincidence, not by the tool's
      # actual contract. Now that the build job uploads exactly one
      # self-contained artifact per ABI (node section 6), there's no
      # cross-artifact reassembly to do — each artifact just needs to stay
      # in its own dist/<artifact-name>/ directory, get zipped whole, and
      # become one release asset. That's what merge-multiple: false gives
      # for free, with no name-matching logic required afterward.
      - name: Download all ABI artifacts
        uses: actions/download-artifact@v6
        with:
          # Wildcard sits between LIB_NAME and "android" too, not just at
          # the end — build-job artifact names embed RESOLVED_NODE_VERSION
          # (see section 3a and 6 in the build job), and Minimatch (what
          # `pattern` uses) matches `*` anywhere in the string, not only as
          # a trailing glob.
          pattern: ${{ env.LIB_NAME }}-v*-android-*
          path: dist
          merge-multiple: false
          if-no-artifact-found: warn  # armeabi-v7a is experimental — its artifact may legitimately be absent

      - name: List downloaded artifacts
        run: ls -lhR dist || echo "::warning::no artifacts downloaded — did every matrix leg fail?"

      # ---------- Parse resolved Node.js version back out of artifact folder names ----------
      # This job never clones Node.js itself (it only downloads finished
      # artifacts from the build job), so it has no direct access to
      # src/node_version.h to resolve the version the way section 3a does
      # in the build job. Rather than plumb RESOLVED_NODE_VERSION across
      # jobs/matrix legs, parse it back out of a downloaded artifact's own
      # folder name — with merge-multiple: false, each artifact lands in
      # dist/<artifact-name>/, and that name is exactly what the build
      # job's "Upload combined artifact" step set, version and all — so
      # this is just reading it back rather than re-deriving it from
      # scratch.
      - name: Parse resolved Node.js version from artifact folder names
        run: |
          SAMPLE="$(ls dist | grep -m1 -E "^${LIB_NAME}-v[0-9]+\.[0-9]+\.[0-9]+(-dev)?-android-" || true)"
          if [ -z "$SAMPLE" ]; then
            echo "::warning::no artifact folder name matched the expected version pattern — falling back to NODE_REF for release notes"
            echo "RESOLVED_NODE_VERSION=${NODE_REF}" >> "$GITHUB_ENV"
          else
            VERSION="$(echo "$SAMPLE" | sed -E "s/^${LIB_NAME}-v([0-9]+\.[0-9]+\.[0-9]+(-dev)?)-android-.*/\1/")"
            echo "RESOLVED_NODE_VERSION=${VERSION}" >> "$GITHUB_ENV"
            echo "Resolved Node.js version from artifact: $VERSION"
          fi

      # actions/upload-artifact does not preserve Unix file permissions —
      # confirmed in its own docs/known issue (actions/upload-artifact#38,
      # open since 2019): every file lands as mode 644 after a
      # zipped-artifact round trip, regardless of what it was chmod'd to
      # before upload. The build job's "Package node" step verifies node
      # has no dynamic libc++_shared.so dependency and a valid ELF hash
      # table, but none of that survives as "executable" through
      # upload/download — node would extract from the release zip
      # non-executable otherwise, silently, since a 644 ELF file still
      # opens and inspects fine; it only fails the moment someone tries to
      # run it. Restore the bit explicitly, once, right after download,
      # before this ABI's directory gets zipped into a release asset.
      - name: Restore executable permission on node binaries
        run: |
          shopt -s nullglob
          for f in dist/*/node; do
            chmod +x "$f"
          done
          echo "---- Verifying ----"
          for f in dist/*/node; do
            ls -l "$f"
          done

      # This is the only place any archive gets made for actual
      # distribution — once, here. The build job intentionally uploads a
      # raw directory (section 6) instead of pre-archiving, to avoid a
      # zip-of-a-zip on the Actions-artifact download path (upload-artifact
      # always wraps whatever it's given in one zip for UI download).
      #
      # Each dist/<artifact-name>/ directory IS one ABI's complete,
      # self-contained payload — node + libc++_shared.so + headers all
      # together, staged that way by the build job's "Stage combined
      # per-ABI directory" step. So each one becomes exactly one release
      # asset, zipped whole, with no per-file logic (no more splitting
      # "*-headers" folders out from binary artifacts) needed here at all.
      - name: Assemble release archives
        run: |
          mkdir -p release-assets
          shopt -s nullglob
          for d in dist/*/; do
            name="$(basename "$d")"
            ( cd "$d" && zip -rq "$GITHUB_WORKSPACE/release-assets/${name}.zip" . )
          done
          ls -lh release-assets || echo "::warning::release-assets is empty — did every matrix leg fail?"

      - name: Create/Update GitHub Release
        uses: softprops/action-gh-release@v3
        with:
          tag_name: ${{ env.RELEASE_TAG }}
          # Title now leads with the resolved version (e.g. "26.5.1-dev")
          # instead of echoing NODE_REF (e.g. "v26.x") verbatim — NODE_REF
          # is a moving branch on the default dropdown choices, so it never
          # told you which actual release ended up in this build. See
          # section 3a in the build job and the version-parsing step above
          # for where RESOLVED_NODE_VERSION comes from.
          name: "${{ env.LIB_NAME }} — Node ${{ env.RESOLVED_NODE_VERSION }} for Android (build #${{ github.run_number }})"
          # GitHub's own commit-based auto changelog (compares against the
          # previous release's tag). softprops/action-gh-release prepends
          # the custom `body` below to these generated notes rather than
          # replacing them.
          make_latest: ${{ startsWith(github.ref, 'refs/tags/') }}
          prerelease: ${{ !startsWith(github.ref, 'refs/tags/') }}
          body: |
            **Automated Android build**

            | | |
            |---|---|
            | Node.js version | `${{ env.RESOLVED_NODE_VERSION }}` |
            | Requested ref | `${{ env.NODE_REF }}` |
            | Artifact label | `${{ env.LIB_NAME }}` |
            | Build profile | `${{ inputs.profile || 'balanced' }}` |
            | NDK version | `${{ env.NDK_VERSION }}` |
            | Trigger | `${{ github.event_name }}` |
            | Commit | `${{ github.sha }}` |

            "Requested ref" is the branch/tag/custom ref that was asked for
            (e.g. `v26.x`, which is a moving branch, not a fixed version) —
            "Node.js version" above is what that ref actually resolved to
            for this specific build, read from src/node_version.h right
            after clone. A `-dev` suffix means this commit is not itself a
            tagged Node.js release, just wherever its release branch
            currently sits.

            arm64-v8a is always included when the build succeeds; armeabi-v7a
            is experimental and only present below if that leg also succeeded.

            Each `${{ env.LIB_NAME }}-v${{ env.RESOLVED_NODE_VERSION }}-android-<abi>.zip`
            contains everything needed for that ABI in one download — the
            binary, its runtime companion library, and headers for
            compiling native addons against it:
            - `node` — single ELF, PIE, statically linked against libc++
              (does NOT dynamically depend on libc++_shared.so — confirmed
              absent from its NEEDED entries during the build), all symbols
              exported via -rdynamic/--export-dynamic. Rename it to lib*.so
              yourself downstream if your app needs Android to extract it
              with exec permissions.
            - `libc++_shared.so` — an unmodified copy of the NDK's
              libc++_shared.so for that ABI, bundled for native-addon
              builds that dynamically need it at runtime. `node` itself
              does not load this file.
            - `include/node/` — Node's public headers, all of V8's and
              libuv's includes, and `config.gypi`, laid out the same way
              official `node-vX.Y.Z-headers.tar.gz` releases are, for
              `node-gyp`/`node-addon-api` via `npm config set nodedir=...`.
              Use the zip matching your target ABI — `config.gypi` differs
              between arm64-v8a and armeabi-v7a, so mixing them produces a
              wrong native-addon build. (Bundled OpenSSL/zlib headers are
              not included.)
          files: release-assets/*