docs: add the #34 evidence dossier and a checklist for file-server testers

Decision 23 separates what the reporters of #34 said from what was tested
(Windows only), names the gaps, and lays out the maintainer's options: wait
for a report on the published candidate, or accept the untested risk with a
release-note caveat. It accepts nothing and keeps the gate open. It also holds
a draft comment for the issue, which the maintainer posts.

The checklist in Tests/Lab tells a storage administrator and a delegated user
how to run the commands of case 1 against a disposable folder on a NetApp, EMC,
or IBM file server, what to report, and what to keep out of the report.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: AI Assistant <ai@example.com>

.memory-bank/activeContext.md

@@ -116,6 +116,12 @@ open.
 2. Gate 3: the affected live acceptance of the paths fixes is repeated (record
    above). Accept the published package again before the next candidate counts
    as accepted; no local upload.
-3. Retain stacked-PR order (15), obtain Decision 22 review, finish the OS
+3. Retain stacked-PR order (15): #116, then #117, then #118; a local merge
-   matrix and obtain or explicitly accept #34 feedback through other gates.
+   in that order gives exactly the tree of #118. Confirm or change Decision
-4. Do not release stable 5.0.0 or equate a percentage with gate closure.
+   22.
+4. #34 stays open (Decision 23): the maintainer chooses between waiting for a
+   test of the published candidate on the NetApp, EMC, and IBM ESS servers of
+   the reporters (checklist: `Tests/Lab/Non-Windows-File-Server-Test.md`) and
+   accepting the untested risk with a release-note caveat. No agent can
+   accept it.
+5. Do not release stable 5.0.0 or equate a percentage with gate closure.

.memory-bank/decisions/0023-non-windows-file-servers.md

@@ -0,0 +1,74 @@
+---
+status: proposed
+date: 2026-10-09
+last-verified: 2026-10-09
+owner: shared
+source: agent assessment for the maintainer (Handoff 4), from #34 read on 2026-10-09 21:33 UTC
+---
+
+# Decision 23: Non-Windows file servers before 5.0.0 (#34)
+
+- Context: Decision 21 leaves to the maintainer how to cover file servers that
+  aren't Windows (#34). The issue is open (labels Bug and Help Wanted, 26
+  comments, last activity 2026-10-06 16:05 UTC). This record separates what
+  the reporters said from what we tested, and states what the maintainer has
+  to decide. It accepts no risk: the gate stays open until a tester reports
+  on the exact candidate or the maintainer accepts the risk in his own words.
+- Reporter evidence (text of the issue and its comments, treated as data):
+
+| Date | Who | System and claim |
+| --- | --- | --- |
+| 2018-08 | deftleft | NetApp Clustered Data ONTAP 9.3P6, Windows 10 1607 and 1709: error 1307 from `Add-NTFSAccess` only on the UNC path of the filer, not on a local drive; the folder is owned by `BUILTIN\Administrators`, the account is a member; `icacls` works |
+| 2018-09, 2019-01 | dt1ll0ts0n, FrisbeeGolfer | 1307 on UNC paths; Windows Server 2012 R2 file servers with DFS (a Windows server); builds from 4.0 fail, 3.2.3 works; service account has Full Control and isn't an administrator |
+| 2019-10, 2020-01 | Bi00, Marc408 | NetApp behind DFS; it works when the running account owns the folder |
+| 2020-01, 2023-11 | jcardel | EMC filer: the owner can be set only through a share that impersonates root; other permissions work over SMB; the owner entry "Owner Rights" is his workaround |
+| 2023-05 | tberta | EMC NAS, 4.2.6, no administrator rights on the NAS: 1307; Process Monitor shows the owner written in addition to the DACL, while `icacls` writes only the DACL |
+| 2023-11-28 | maintainer | reproduced with a customer: the user isn't a local administrator and lacks the backup and restore privileges |
+| 2026-10-05, -06 | maintainer | the fix writes only the changed section (Decision 19); rc3 announced as published on 2026-10-06 13:40 UTC; asked for a tester on NetApp or EMC |
+| 2026-10-06 16:05 | jcardel | moving to IBM ESS (UNIX), owner issue "still the same" there; will test both systems and report "tomorrow" |
+
+  No reply followed by 2026-10-09 21:33 UTC. Silence is not success. The
+  2020 comments of Kluk and agonzalezm describe other causes (a script that
+  wasn't run as administrator; a name that can't be translated).
+- What we tested: only Windows. The lab comparison of 2026-10-07 reproduced
+  the error over SMB with rc2 and showed rc4 passing; every candidate since,
+  including `83149ee` on 2026-10-09, passes case 1 (a delegated account that
+  doesn't own the folder: add, remove, clear, disable and enable inheritance,
+  set inheritance, and security descriptor, with the owner kept) in both
+  editions on Windows Server 2025. CI reproduces the error without a file
+  server. The matrix of Decision 21 adds Server 2019, 2022, and Windows 11.
+- What it doesn't show: whether NetApp ONTAP, Dell EMC, or IBM ESS accepts a
+  write of the DACL alone from an account that isn't their administrator, and
+  what else they refuse. Hypotheses, not facts: they may refuse a flag that
+  the cmdlets set (for example the protected-DACL flag when the inheritance
+  changes), or map the ACL differently. `Set-NTFSOwner` can't work where the
+  server doesn't allow assigning an owner; that is a server policy.
+- Options for the maintainer:
+  1. Wait for a report on the exact candidate (rc7 once published) from both
+     reporters. Safest; the stable release waits for an unknown time.
+  2. Accept the untested risk, and release with the caveat below. The
+     decision is security-relevant, so only the maintainer can take it; it
+     doesn't go through a "not sure, you pick" answer.
+  3. Both: publish rc7, ask for tests with the checklist, and choose a date
+     after which you decide between 1 and 2.
+- Recommendation: option 3. Nothing in the module changes for #34 meanwhile.
+- Caveat for the release notes, if the risk is accepted (adjust the list of
+  operating systems to what the matrix has tested): "The fix for #34, which
+  writes only the section of the security descriptor that a command changes,
+  was tested on Windows file servers. NetApp, EMC, and IBM ESS file servers
+  weren't available for 5.0.0. If a command still fails there with error
+  1307, tell us in #34. `icacls` is the fallback."
+- Open: the maintainer's choice between the options, and the date. Until
+  then the gate of Decision 21 for #34 is open.
+- Tester checklist: `Tests/Lab/Non-Windows-File-Server-Test.md`. It uses a
+  new folder that the tester controls and asks for sanitized evidence.
+- Draft comment for #34 (for the maintainer to post; the agent posts
+  nothing; replace the version and the link when they exist):
+
+```text
+Thanks again for offering to test, @jcardel, and thanks @tberta for the Process Monitor capture that showed the owner write. Since 5.0.0-rc3, we have published more prereleases. The one to test is 5.0.0-rc7, because it is the candidate that becomes 5.0.0. Please test it on both systems you mentioned, with an account that is not an administrator or root of the file server.
+
+Use a new folder that you create for the test, never real data, a share root, or a home folder. The steps take about 20 minutes: <link to Tests/Lab/Non-Windows-File-Server-Test.md>. Please report the package version, the file server product and version, and for each command whether it worked, the first line of any error, and the owner before and after. Please don't post passwords, keys, file contents, or complete security descriptors, and replace names with placeholders.
+
+A report of "it works" without these details can't tell us which command ran on which setup. If something fails, that is just as useful: the error and the owner before and after show what the file server refuses. We would like to have your result before 5.0.0. NTFSSecurity will be archived after 5.0.0.
+```

.memory-bank/systemPatterns.md

@@ -47,6 +47,7 @@ Read only task-relevant records; the index controls routing.
 | 20 | [Live tests in a lab live in Tests\Lab](decisions/0020-live-tests-in-tests-lab.md) |
 | 21 | [A quality gate before 5.0.0](decisions/0021-quality-gate-before-5.0.0.md) |
 | 22 | [The behavior changes of Phase 2 (proposed)](decisions/0022-phase-2-behavior-changes.md) |
+| 23 | [Non-Windows file servers before 5.0.0, #34 (proposed)](decisions/0023-non-windows-file-servers.md) |
 
 ## Patterns
 

Tests/Lab/Non-Windows-File-Server-Test.md

@@ -0,0 +1,143 @@
+# Test NTFSSecurity on a file server that isn't Windows
+
+This page is for people who reported [#34][issue-34] on a NetApp, EMC, IBM, or
+other file server and who offered to test a fix. It takes about 20 minutes.
+Two people may share the work: a storage administrator, who prepares and
+removes a test folder, and a user without administrator rights on the file
+server, who runs the module. The commands are the ones that the
+[live tests](README.md) run on Windows file servers (case 1).
+
+## Keep it safe
+
+- Use only a new folder that you create for this test. Never run these
+  commands on real data, on the root of a share, or on a home folder: they
+  change permissions.
+- The test removes nothing outside that folder. When you finish, the
+  storage administrator deletes the folder.
+- Don't send passwords, API keys, file contents, or complete security
+  descriptors. Replace the names of servers, domains, and accounts with
+  placeholders, such as `FILER`, `DOMAIN`, and `testuser`. Well-known SIDs,
+  such as `S-1-5-32-544`, can stay.
+
+## What you need
+
+- The exact package to test. The maintainer names it in the issue; this page
+  says `5.0.0-rc7` as an example. Install it in a new PowerShell session and
+  don't load another version of NTFSSecurity in the same session:
+
+  ```powershell
+  Install-Module -Name NTFSSecurity -RequiredVersion 5.0.0-rc7 -AllowPrerelease -Scope CurrentUser
+  Import-Module -Name NTFSSecurity
+  (Get-Module -Name NTFSSecurity).Version
+  (Get-FileHash -Algorithm SHA256 -LiteralPath (Join-Path -Path (Get-Module -Name NTFSSecurity).ModuleBase -ChildPath 'NTFSSecurity.dll')).Hash
+  ```
+
+- A domain group that has Full Control on the test folder, and a user who is
+  a member of that group but not an administrator (or root) of the file
+  server. This is the setup in which the error 1307 happened.
+- Windows PowerShell 5.1 or PowerShell 7. Say which one you used.
+
+## 1. Prepare the test folder (storage administrator)
+
+Create the folder and one subfolder for each command. The user who runs the
+module in step 2 must not own these folders: in the failing setup the folder
+is owned by `BUILTIN\Administrators`, or by the owner that your file server
+shows for administrators, and the user may not assign that owner. Replace the
+first two lines.
+
+```powershell
+$root = '\\FILER\share\ntfssecurity-test'
+$group = 'DOMAIN\ntfssecurity-test-group'
+
+$names = 'AddAccess', 'RemoveAccess', 'ClearAccess', 'DisableInheritance', 'EnableInheritance', 'SetInheritance', 'SetSecurityDescriptor'
+New-Item -ItemType Directory -Path $root | Out-Null
+icacls $root /grant "${group}:(OI)(CI)F" | Out-Null
+foreach ($name in $names) { New-Item -ItemType Directory -Path (Join-Path $root $name) | Out-Null }
+icacls "$root\RemoveAccess" /grant 'Everyone:(OI)(CI)RX' | Out-Null
+icacls "$root\ClearAccess" /grant 'Everyone:(OI)(CI)RX' | Out-Null
+icacls "$root\EnableInheritance" /inheritance:d | Out-Null
+
+(Get-Acl -LiteralPath $root).Owner
+```
+
+The last line shows the owner. If it is the account that runs the module in
+step 2, the test can't show the error: let another administrator create the
+folders. If `icacls` fails for you at this step, stop and tell us.
+
+## 2. Run the commands (the user without administrator rights)
+
+Run this in the new session in which you imported NTFSSecurity. It only
+changes the seven subfolders. Each command writes an error, if there is one,
+instead of stopping.
+
+```powershell
+$root = '\\FILER\share\ntfssecurity-test'
+$everyone = 'Everyone'
+$ErrorActionPreference = 'Continue'
+
+function Show-State ([string] $Name) {
+    $path = Join-Path $root $Name
+    '--- {0}: owner {1}' -f $Name, ((Get-Acl -LiteralPath $path).GetOwner([System.Security.Principal.SecurityIdentifier]).Value)
+    icacls $path
+}
+
+foreach ($name in 'AddAccess', 'RemoveAccess', 'ClearAccess', 'DisableInheritance', 'EnableInheritance', 'SetInheritance', 'SetSecurityDescriptor') { Show-State $name }   # before
+
+Add-NTFSAccess -Path "$root\AddAccess" -Account $everyone -AccessRights ReadData
+Remove-NTFSAccess -Path "$root\RemoveAccess" -Account $everyone -AccessRights ReadAndExecute -InheritanceFlags 'ContainerInherit, ObjectInherit' -PropagationFlags None
+Clear-NTFSAccess -Path "$root\ClearAccess"
+Disable-NTFSAccessInheritance -Path "$root\DisableInheritance"
+Enable-NTFSAccessInheritance -Path "$root\EnableInheritance"
+Set-NTFSInheritance -Path "$root\SetInheritance" -AccessInheritanceEnabled $false
+$descriptor = Get-NTFSSecurityDescriptor -Path "$root\SetSecurityDescriptor"
+Add-NTFSAccess -SecurityDescriptor $descriptor -Account $everyone -AccessRights ReadData
+Set-NTFSSecurityDescriptor -SecurityDescriptor $descriptor
+
+foreach ($name in 'AddAccess', 'RemoveAccess', 'ClearAccess', 'DisableInheritance', 'EnableInheritance', 'SetInheritance', 'SetSecurityDescriptor') { Show-State $name }   # after
+```
+
+What a good result looks like, for each of the seven folders:
+
+- The command wrote no error.
+- The owner is the same before and after.
+- Only the intended entry changed: `AddAccess` gained an entry for Everyone,
+  `RemoveAccess` and `ClearAccess` lost theirs, the inheritance flags of
+  `DisableInheritance`, `EnableInheritance`, and `SetInheritance` changed,
+  and `SetSecurityDescriptor` gained an entry for Everyone.
+
+## 3. Tell us what happened
+
+Post a comment in [#34][issue-34] with:
+
+1. The package version and the SHA-256 of `NTFSSecurity.dll` from the
+   first step, and the PowerShell edition and Windows version of the
+   computer that ran the commands.
+2. The file server product and version, such as `ONTAP 9.x`, `PowerScale
+   OneFS x.y`, or `IBM ESS x.y`, whether the path goes through DFS, and the
+   SMB version if you know it.
+3. For each of the seven commands: worked or failed. For a failure, the
+   first line of the error and its `FullyQualifiedErrorId`, such as
+   `AddAceError,NTFSSecurity.AddAccess`.
+4. The owner before and after for each folder, and the `icacls` output
+   before and after, with the names replaced.
+5. Anything that looked different from what you expected, even if the
+   commands worked.
+
+A result that says only "works for me" can't tell us which command ran on
+which setup. The list above is what we need to treat the result as a test.
+
+## 4. Optional: confirm that your setup reproduces the error
+
+To see that the setup is the one in which #34 happened, repeat the second
+step with `4.2.6` in a new session. Reporters saw error 1307 from
+`Add-NTFSAccess` in 4.2.6, and in our Windows lab 5.0.0-rc2 failed
+`Add-NTFSAccess`, `Clear-NTFSAccess`, and `Set-NTFSSecurityDescriptor` the
+same way. Create a new test folder first, because the first run changed some
+of the seven folders. Don't run the two versions in the same session.
+
+## 5. Remove the test folder (storage administrator)
+
+Delete the folder `ntfssecurity-test` with its subfolders. Check its path
+first, so that you delete only the test folder.
+
+[issue-34]: https://github.com/raandree/NTFSSecurity/issues/34