reverse-engineering-anything/docs/specs/native/windows-refs/plan.md

Windows ReFS Filesystem Authority Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Admit fixed local ReFS volumes through REA's existing Windows native authority while preserving NTFS behavior and every current security invariant.

Architecture: Extend the existing native admission owner instead of creating a ReFS backend. Record the observed filesystem on native File/Runtime owners and pass it through every identity projection, while the TypeScript contract accepts only the same two values. Prove the behavior with an independent Win32 volume observer and the existing full native and Ghidra verifiers on both filesystems.

Tech Stack: C++17 Win32/Node-API, TypeScript/Zod/Vitest, Node.js 24.22.1, WSL Ubuntu with MinGW-w64, real Windows NTFS/ReFS volumes and Ghidra 12.1.4.

Spec: spec.md

Global Constraints

• Accept only fixed local NTFS and ReFS volumes reporting FILE_PERSISTENT_ACLS; every other filesystem fails closed.
• Preserve native ABI version 1 and the existing identity fields; only the filesystem value domain expands.
• Do not weaken path, reparse, sharing, DACL, snapshot, cancellation, ownership or cleanup checks.
• Use Node.js 24.22.1; Windows and WSL have independent node_modules and work areas. Generated native artifacts remain uncommitted.
• Do not claim a check that did not run. Do not mark the PR ready for the human owner and do not merge it.

Review Focus

• Cross-volume snapshots: source and destination must retain different observed filesystem values rather than inheriting one global value; Task 2 asserts both.
• Less visible identity producers: native inspection, runtime_open and Cutter bridge verification must use the same owner-recorded value; Task 2 asserts each.
• Reparse and cleanup adversarial behavior on ReFS: Task 2 keeps the existing ancestor-conversion and cleanup-escape controls intact and runs them on both volumes.
• Unsupported values and stale consumers: Task 1 rejects an unknown filesystem at the schema boundary, Task 2 keeps the native allowlist/ACL predicates, and Task 3 pins user-facing NTFS/ReFS wording.
• Generated artifacts and package identity: Task 4 verifies the manifest, package contents, clean Git state and actual ReFS CLI scenario rather than relying on compilation alone.

---

Task 1: Filesystem identity contract

Files:

• Modify: src/windows/WindowsNativeLoader.ts
• Modify: src/windows/WindowsNativeLoader.test.ts

Interfaces:

• Consumes: the existing WindowsNativeLoadHost inspection fixture and loadWindowsNativeAuthority.

• Produces: windowsFileIdentitySchema.filesystem accepting exactly "NTFS" | "ReFS"; unsupported values produce failureStage: "inspection".

• Step 1: Prepare isolated toolchains and establish a clean baseline

Use nvm install 24.22.1 && nvm use 24.22.1, then npm ci and npm run check:fast in the Windows ReFS worktree and in a separate WSL clone. Do not share node_modules between them. Record any pre-existing failure instead of attributing it to this change.

• Step 2: Write the failing ReFS contract tests

Extend the test fixture's capability overrides with filesystem?: string, applied to its identity. Add:

it.each(["NTFS", "ReFS"])("admits %s filesystem identities", (filesystem) => {
  const result = loadWindowsNativeAuthority(fixture({ filesystem }).host);
  expect(result).toMatchObject({
    available: true,
    authority: { inspection: { filesystem: { filesystem } } },
  });
});

it("rejects an unsupported filesystem identity", () => {
  expect(
    loadWindowsNativeAuthority(fixture({ filesystem: "exFAT" }).host),
  ).toMatchObject({ available: false, failureStage: "inspection" });
});

• Step 3: Run the tests to verify the new ReFS case fails

Run: npm run test:focused -- src/windows/WindowsNativeLoader.test.ts Expected: the ReFS case fails because z.literal("NTFS") rejects it; NTFS and exFAT controls retain their expected outcomes.

• Step 4: Implement the minimal schema change

Change the field to z.enum(["NTFS", "ReFS"]) and update its identity comment to local NTFS/ReFS objects. Do not change the ABI constants or any other schema field.

• Step 5: Verify and commit

Run npm run test:focused -- src/windows/WindowsNativeLoader.test.ts and npm run check:fast; expect PASS. Commit:

git add src/windows/WindowsNativeLoader.ts src/windows/WindowsNativeLoader.test.ts
git commit -m "feat(native): admit ReFS filesystem identities"

Task 2: Native admission, owned identity and real-volume verification

Files:

• Modify: native/windows/src/authority.hpp
• Modify: native/windows/src/filesystem.cc
• Modify: native/windows/src/process.cc
• Modify: tests/fixtures/windows/processBoundary.cc
• Modify: scripts/verify-windows-native.mjs

Interfaces:

• Produces: File.filesystem: std::wstring and Runtime.filesystem: std::wstring, assigned at admission and inherited by handle-relative children.

• Produces: napi_value identity(napi_env env, HANDLE handle, const std::wstring& path, const std::wstring& filesystem).

• Produces: process-boundary.exe volume-semantics <volume-root> returning {"filesystem":"NTFS|ReFS|OTHER","persistentAcls":boolean} through an independent GetVolumeInformationByHandleW observation.

• Step 1: Add the independent observer and failing native assertions

Add the volume-semantics command to processBoundary.cc. In verify-windows-native.mjs, require persistentAcls === true and compare its filesystem string with the .filesystem property of sourceIdentity, native.inspection.filesystem, driveRootRuntime, snapshot.source, snapshot.snapshot, readback, snapshotOwner.observation and the Cutter bridge identity. Record the independently observed filesystem and an observedFilesystemIdentity control in the report when the boundary fixture is supplied.

• Step 2: Build the unmodified native artifact and verify the ReFS failure

Use WSL Node 24.22.1 for npm run build:windows-native, and compile the fixture with:

mkdir -p .cache/windows-process-boundary
x86_64-w64-mingw32-g++ -municode -std=c++17 -O2 -static -Wall -Wextra \
  -o .cache/windows-process-boundary/process-boundary.exe \
  tests/fixtures/windows/processBoundary.cc -ladvapi32

Run node scripts/verify-windows-native.mjs . .cache/windows-process-boundary/process-boundary.exe with TEMP and TMP set to an ignored directory on ReFS. Expected: FAIL before target analysis with the original Backing volume must be NTFS with persistent ACLs constraint, proving the old native admission still blocks ReFS.

• Step 3: Implement native admission and identity propagation

In openFile, split the two failures into Backing volume filesystem is outside the verified NTFS/ReFS profile and Backing volume does not support persistent ACLs, then store the observed name on File. Replace NTFS-only path wording with fixed-local wording while leaving all other checks unchanged.

Add filesystem to File and Runtime. Set Runtime.filesystem = parent->filesystem in createRuntime, propagate root.filesystem in runtimeDirectory, and update every identity caller in filesystem.cc and process.cc to pass the owning value: open, inspection, runtime creation/open, Cutter verification, snapshot source and snapshot destination. Update NTFS-specific comments to the verified NTFS/ReFS boundary without altering cleanup behavior.

• Step 4: Rebuild and verify ReFS, then NTFS

Rebuild the native artifact and boundary fixture in WSL. Run npm run verify:windows-native:artifact and the full native verifier on ReFS; expect all existing controls plus observedFilesystemIdentity to pass with filesystem: "ReFS".

Create a detached NTFS worktree at C:\Users\oi\AppData\Local\Temp\rea-windows-refs-ntfs for the same revision, install its Windows dependencies, and copy the same generated native artifact and boundary fixture into it. Run the full verifier there with TEMP/TMP on NTFS; expect filesystem: "NTFS" and no regression.

• Step 5: Commit native code and its regression coverage

git add native/windows/src/authority.hpp native/windows/src/filesystem.cc \
  native/windows/src/process.cc tests/fixtures/windows/processBoundary.cc \
  scripts/verify-windows-native.mjs
git commit -m "feat(native): support ReFS filesystem authority"

Task 3: Capability declarations, diagnostics and documentation

Files:

• Modify: src/windows/WindowsNativeLoader.ts
• Modify: src/windows/WindowsNativeLoader.test.ts
• Modify: src/ghidra/GhidraProviderCapabilities.ts
• Create: src/ghidra/GhidraProviderCapabilities.test.ts
• Modify: src/ghidra/GhidraDoctor.ts
• Modify: src/ghidra/GhidraDoctor.test.ts
• Modify: scripts/verify-real-ghidra-windows.mjs
• Modify: scripts/verify-windows-native-inspection.mjs
• Modify: native/windows/README.md
• Modify: docs/providers/windows-ghidra-p0.md
• Modify: docs/providers/ida-provider.md
• Modify: docs/getting-started/installation.md
• Modify: docs/guides/native/native-investigation.md
• Modify: docs/testing-lanes.md

Interfaces:

• Produces: user-facing capability and recovery text limited to fixed local NTFS/ReFS, with no remaining NTFS-only claim in the touched Windows native/Ghidra workflows.

• Produces: the real Ghidra verifier limitation windows-x64-local-ntfs-refs-only.

• Step 1: Add failing wording tests

Assert that the loader self-test remediation contains writable local NTFS/ReFS temporary directory, windowsP0Limitations contains local NTFS/ReFS targets and runtimes, and a passing doctor's native_authority detail contains local NTFS/ReFS only. Keep all existing diagnostic behavior assertions unchanged.

• Step 2: Run focused tests and confirm the old wording fails

Run: npm run test:focused -- src/windows/WindowsNativeLoader.test.ts src/ghidra/GhidraProviderCapabilities.test.ts src/ghidra/GhidraDoctor.test.ts Expected: FAIL on the NTFS-only strings.

• Step 3: Update declarations and every owning document

Apply the exact NTFS/ReFS wording from Step 1, update the inspection script's host/error and retained-handle comments, and replace the Ghidra report limitation. Update the listed guides to describe the same fixed-local boundary and record the independent volume-semantics observer. Do not alter NTFS MFT/USN functionality or unrelated historical specifications.

• Step 4: Verify wording, discovery and static checks

Run the focused tests, npm run verify:test-discovery, npm run check:fast, and a scoped search for local NTFS, NTFS only, NTFS-only, fixed local NTFS and local-ntfs. Expect PASS with no stale claim except the approved historical statement in docs/specs/native/windows-refs/spec.md and unrelated formats.

• Step 5: Commit

git add src/windows/WindowsNativeLoader.ts src/windows/WindowsNativeLoader.test.ts \
  src/ghidra/GhidraProviderCapabilities.ts src/ghidra/GhidraProviderCapabilities.test.ts \
  src/ghidra/GhidraDoctor.ts src/ghidra/GhidraDoctor.test.ts \
  scripts/verify-real-ghidra-windows.mjs scripts/verify-windows-native-inspection.mjs \
  native/windows/README.md docs/providers/windows-ghidra-p0.md \
  docs/providers/ida-provider.md docs/getting-started/installation.md \
  docs/guides/native/native-investigation.md docs/testing-lanes.md
git commit -m "feat(native): advertise ReFS Windows support"

Task 4: Final verification and Draft PR

Files:

• Modify: docs/specs/native/windows-refs/tasks.md
• Create locally, never commit: .cache/windows-refs-pr.md and verification reports under .cache/.

Interfaces:

• Produces: one reviewed feature branch, a linked Draft PR, and reproducible NTFS/ReFS verification evidence. No generated binaries enter Git.

• Step 1: Run source, documentation and package checks on the final revision

In the independent WSL clone run npm run check, npm run docs:check, and npm run verify:package. On Windows run npm run verify:test-discovery, npm run verify:windows-native:artifact, npm run verify:package:windows, and npm pack --dry-run. Record actual results; investigate failures rather than weakening checks.

• Step 2: Repeat all real Windows lanes on both filesystems at the final commit

Build .cache/windows-native-inspection-fixture through WSL, then run node scripts/verify-windows-native-inspection.mjs with TEMP/TMP on each filesystem. Repeat the full verify:windows-native matrix with the independent boundary fixture.

Run npm run verify:ghidra:windows in each worktree with GHIDRA_INSTALL_DIR=D:\工具\ghidra_12.1.4_PUBLIC, JAVA_HOME=C:\Program Files\Zulu\zulu-25, and TEMP/TMP on the corresponding filesystem. Expect complete operation coverage, cleanup completion and windows-x64-local-ntfs-refs-only.

• Step 3: Exercise the original ReFS user scenario through the source CLI

In the ReFS worktree run node scripts/rea.mjs analyze D:\项目\逆向分析\魔塔\TSW.exe with REA_ANALYSIS_PROVIDER=ghidra, the Ghidra/Java settings above, and ReFS TEMP/TMP. Expect the original target SHA-256 41cb9844d9bdcf2641a34d4b152d6fbbb0455077abe0e9d7bfed77761a4d2779, a completed overview, and no snapshot-admission failure. Close the session and confirm owned runtime paths are removed.

• Step 4: Review the final diff and synchronize upstream

Run git diff --check, git status --short, git diff upstream/main...HEAD, and a generated-file sweep. Fetch upstream/main; if it moved, rebase this branch and rerun every affected real-world check. Update tasks.md to mark only completed items and commit it as docs(native): record ReFS verification tasks.

• Step 5: Push and create the Draft PR

Push feat/windows-refs-support to QianNangong/rea. Create a Draft PR to morluto/rea:main titled feat(native): support ReFS filesystem authority, linking #289 and summarizing the baseline failure, design, exact checks and remaining gaps. Use .cache/windows-refs-pr.md for the body and leave every human Author readiness declaration unchecked for the owner.

• Step 6: Hand off for human ownership

Ask the human owner to review the final diff and verification evidence, complete the readiness declarations themselves, and decide whether to mark the PR ready. Do not merge or represent maintainer approval as obtained.

References

• Windows ReFS specification
• REA #289: handle-based reparse-safe filesystem authority
• Windows native build and verification guide