NTFSSecurity/.memory-bank/systemPatterns.md

status	last-verified	owner	source
current	2026-10-05	active-agent	repository evidence

System patterns

Architecture

NTFSSecurity.psd1 ─┬─ ScriptsToProcess: NTFSSecurity.Init.ps1
                   │    Add-Type: Security2.dll, PrivilegeControl.dll,
                   │    ProcessPrivileges.dll, inline NTFS.DriveInfoExt;
                   │    Update-FormatData -PrependPath format.ps1xml
                   ├─ TypesToProcess: NTFSSecurity.types.ps1xml
                   │    (Owner, IsInheritanceBlocked, LengthOnDisk on
                   │    FileInfo/DirectoryInfo; AccountType on ACEs)
                   ├─ RootModule: NTFSSecurity.psm1 (aliases)
                   ├─ NestedModules: NTFSSecurity.dll (36 cmdlets)
                   └─ en-US\NTFSSecurity.dll-Help.xml (Get-Help; generated
                        from Docs/Cmdlets, Decision 8)
NTFSSecurity.dll ── cmdlets ──> Security2.dll (FileSystemAccessRule2,
                                FileSystemAuditRule2, IdentityReference2,
                                FileSystemInheritanceInfo, EffectiveAccess)
                 ── long paths ──> AlphaFS
                 ── privileges ──> PrivilegeControl / ProcessPrivileges

• BaseCmdlet resolves only relative paths, against the current file system location of the session (not $PWD, #86). Path parameters carry [FileSystemPathTransformation], which binds file objects as full paths.
• On access denied, most cmdlets retry through InvokeAsOwner, which takes ownership and restores the previous owner on every exit path.
• BaseCmdletWithPrivControl enables Backup, Restore, TakeOwnership, and Security in BeginProcessing when PrivateData.EnablePrivileges is $true, and disables the ones it enabled in EndProcessing.
• PrivateData switches: EnablePrivileges, GetInheritedFrom, GetFileSystemModeProperty, IdentifyHardLinks, ShowAccountSid.
• Cmdlets accept -Path (alias FullName) or -SecurityDescriptor; the SD sets change the object in memory until Set-NTFSSecurityDescriptor.

Decisions

Each Decision record is a file in decisions/; read only the relevant ones.

#	Decision
1	Use the canonical Memory Bank base
2	Cmdlet reference stays platyPS markdown
3	Document the source at HEAD
4	Online help points to GitHub
5	Document defects, don't fix them in docs work
6	CI checks the docs against a build of the source
7	CHANGELOG lists user-visible changes only
8	Commit the generated help file and check it in CI
9	Keep the documentation on GitHub
10	One version for the manifest, assemblies, and changelog
11	CI and the wiki run on GitHub Actions
12	Releases are built and published by CI on a version tag
13	Set-NTFSInheritance keeps entries like the dedicated cmdlets
14	Repository hardening is optional
15	Merge stacked pull requests in order with merge commits
16	Fix only reproducible bugs
17	Issue labels
18	NTFSSecurity will be archived

Patterns

Verifying documentation

• Run platyPS in Windows PowerShell 5.1 against a Release build; a copy of Docs/Cmdlets must round-trip through Update-MarkdownHelp unchanged. Keep cmdlet pages ASCII-only. platyPS takes Position and Required from the shipped help file: after such a change, edit the page YAML, run New-ExternalHelp, rebuild, and check the round trip.
• MarkdownLinkCheck checks relative Docs links, Tests\Wiki.Tests.ps1 the wiki links and anchors. The wiki is generated from Docs (never edit it); Docs/README.md becomes Home, its cmdlet groups the sidebar.
• In cmdlet pages, end a sentence with a link (platyPS drops the space after it). Verify examples in a $env:TEMP sandbox, never on real data.

Testing the module

• Pester 5 tests in Tests/*.Tests.ps1 import the Release build; CI runs them in Windows PowerShell 5.1 and PowerShell 7 (Decision 11).
• A test that changes files, links, or security descriptors uses Tests\TestHelpers.psm1: its own sandbox, Assert-TestSandboxPath before each change, Remove-TestSandbox. Cases that need a privilege skip with Test-PrivilegeHeld and run in CI (elevated); Block-TestReadPermission and Block-TestWritePermission make a read or a write fail without elevation.
• Get-Help -Online tests run only in Windows PowerShell, which honors the hook BypassOnlineHelpRetrieval. Manifest.Tests.ps1 and Release.Tests.ps1 check the manifest, the version (Decision 10), the release notes, and the packages.