NTFSSecurity/.memory-bank/systemPatterns.md

status	last-verified	owner	source
current	2026-10-09	active-agent	repository and regression evidence

System patterns

Architecture

Component	Responsibility
NTFSSecurity.psd1	Root script, nested binary, initialization, types, help
NTFSSecurity.Init.ps1	Loads Security2/privilege assemblies and prepends formatting
NTFSSecurity.dll	36 PowerShell cmdlets; BaseCmdlet path/privilege behavior
Security2.dll	DACL/SACL objects, owners, inheritance, effective access, Win32
AlphaFS	Long-path files/directories/links
PrivilegeControl / ProcessPrivileges	Token privilege operations
en-US/NTFSSecurity.dll-Help.xml	Committed help generated from cmdlet Markdown

Decisions

Read only task-relevant records; the index controls routing.

#	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
19	Cmdlets write only the sections that they change
20	Live tests in a lab live in Tests\Lab
21	A quality gate before 5.0.0
22	The behavior changes of Phase 2 (proposed)

Patterns

Cmdlets and security sections

• BaseCmdlet resolves relative paths against the current filesystem location; file-object input binds FullName through path transformation.
• Write only changed/read sections (Decision 19); a descriptor parameter changes memory until Set-NTFSSecurityDescriptor persists it.
• Access denial can retry through InvokeAsOwner; restore the previous owner on every exit, except a successful descriptor write that intentionally sets the owner. Restoration failures must report RestoreOwnerError.
• Privilege cleanup runs in EndProcessing and Dispose, reads current states, attempts all cleanup, and preserves explicit enables. Dispose has no stream.
• Pipeline getters never throw; per-item errors name input and allow continuation.
• Folder moves never use CopyAllowed; preserve cross-volume source folders.
• Apply implied Hidden/Force before deciding to emit, including the first item.

Tests and documentation

• Tests import Release in isolated processes, both editions and privilege modes. File/ACL/link fixtures use shared sandbox guards and cleanup. Privilege-dependent skips must have eligible counterparts in the matrix.
• Assert persisted state, errors/targets, continuation, and no failed PassThru output. Prove new characterization guards with bounded mutations; restore source exactly and rebuild before green validation or packaging.
• Fixture DACLs use .NET SetAccessControl, not Set-Acl's unintended SACL writes.
• Scope/descendant expectations are independent of the production converter.
• Desktop platyPS: generate help, rebuild, round-trip unchanged, check links.
• Live tests use only approved lab targets, SMB then independent server state; Get/SetFileSecurity preserves stored DACLs; rights oracles use S4U tokens.

CI results and publication

• Use Path.Combine then GetFullPath for a rooted-or-repository-relative result path; Join-Path appends even a rooted child and corrupts it.
• Discovery handles only expected PackageNotFound as absence; repository, authentication, and network errors remain failures.
• Rerun/uncertain-upload success requires Gallery SHA-512 equality with the exact build artifact. Base64 is case-sensitive: use ordinal comparison. Missing/different/unverifiable metadata preserves the upload error.
• Secrets stay by environment reference, never in process arguments/logs. Test all external publication commands with mocks; no test may upload.
• AltCover aggregates all four sequential runs without --save. Report sequence points, not unique source lines; keep unmatched paths visible.