NTFSSecurity/.memory-bank/debugging-insights.md

---
status: current
last-verified: 2026-10-20
owner: software-engineer
source: Handoff 5 (the coverage unknowns), the rc8 fix, and the tests-only round: probes, red and green runs, and the independent reviews
---

# Debugging insights

Recurring defect classes and how to find them. Evidence is in
`Tests/Coverage/Quality-Gate-Unknowns-2026-10-10.md`; a fix needs a test that
fails without it (Decision 16).

## Culture-sensitive comparison (`tr-TR`)

- With `tr-TR`, `I` and `i` are different letters, so a comparison that takes
  the culture of the thread drops or misses items: `ToLower` or `ToUpper`,
  `Compare`, `StartsWith`, `EndsWith`, or `IndexOf(string)` without a
  `StringComparison`, a case-insensitive `Regex`, a `WildcardPattern` without
  `CultureInvariant` (`string.Equals(a, b)` and `==` are ordinal and safe).
  Handoff 5 found two defects of this class: `IdentityReference2.Equals(object)`
  called with a name, which lowercased both sides (now `OrdinalIgnoreCase`),
  and `Get-ChildItem2 -Filter` (`index*` did not list `Index.txt`).
- A scan of the C# is not enough: AlphaFS 2.2 builds a culture-sensitive regex
  from a search pattern. `Get-ChildItem2` therefore enumerates under
  `InvariantCultureScope` (around the creation of the enumerator and each
  `MoveNext`, never across a `WriteObject`) and its own `WildcardPattern` has
  `CultureInvariant`. Check any new library call that takes a user pattern.
- PowerShell `-eq`, `-contains`, and `-in` do not take the thread culture;
  only the .NET method call failed. Probe a claim before it enters the
  changelog or a report (the first wording named `-eq` and was wrong).
- A test sets the culture of the thread, restores it in `finally`, names the
  rows that differ (`index*`, `*.INI`), keeps a control (`INDEX*`), reads the
  culture in the next pipeline stage for each item and once after the call (a
  cmdlet that does not restore it, or writes an item inside the scope, fails
  both: two mutations proved it), and is proved red on the previous build and
  green on the new one in all four configurations
  (`Tests/ItemCmdlets.Tests.ps1`, `Tests/ObjectApis.Tests.ps1`).
- The argument completers of rc9 had the same flaw (`WildcardPattern` with
  `IgnoreCase` only: `THISFOLDERO<Tab>` found nothing under `tr-TR`); the
  second review found it, not the scan. A Turkish test word must put a capital
  `I` against a lowercase `i` of the name: `NOPROPAGATEINH` faces the capital
  `I` of `Inherit` and passes without the fix, so prove every row red first.

## A test oracle that is wrong on a domain member

- `Get-Acl -Audit` reads the SACL with the other sections and reports an item
  without audit entries as protected (Windows Server 2019, 2022, and 2025
  domain members, Windows 11); the module and `Get-NTFSInheritance` read the
  SACL alone. Tests read the flag with .NET `GetAccessControl(Audit)`
  (`Get-TestAuditAcl`). A suite that is green on the host proves nothing about
  an oracle: run a new test on a domain member before calling it done.

## A piped property and the parameter set

- An object with a property `AppliesTo`, piped into `Add-` or
  `Remove-NTFSAccess` or `-NTFSAudit` with a path, bound the default
  `PathComplex` set and lost the property. Fixed in `93ed2c7`: the four cmdlets
  declare no default set, so the property selects `PathSimple`, an object with
  `AppliesTo` and `InheritanceFlags` fails with `AmbiguousParameterSet`, and the
  tests pipe an object of each shape (red on the previous build, green on the
  new one). A probe that tells the sets uses an entry of the default scope:
  removing `ThisFolderOnly` from it leaves the `InheritOnly` part.
- PowerShell restores only the parameters that the previous piped object
  bound. A field that the cmdlet writes itself stays for the next object: the
  scope that `ProcessRecord` converted from `AppliesTo` into the field behind
  `-InheritanceFlags` went to the next object without a scope. `93ed2c7`
  shipped that, the third review found it (rc7 had it for piped
  `-SecurityDescriptor` objects), and `9783d2a` keeps the flags of a record in
  locals. A pipeline test pipes two or more objects of different shape in one
  call (`Objects with different scopes in one pipeline`, both ParameterSets
  files); one object per call cannot see it.
- Probe the route that the documentation shows. `Import-Csv` of a file gives an
  empty string for a blank cell, `ConvertFrom-Csv` of strings gives `$null` for
  a trailing blank cell, and `Import-Csv` gives `$null` for a column that a row
  lacks. The binder treats them differently: `$null` fails to bind, and a value
  that it cannot convert to the enum (an empty string, a typo) is ignored, so
  the object is handled as one without the property. The first statement and
  the first tests used the convenient route, and the reviewer found the false
  claim; the corrected claim was then too narrow once more (a value that
  converts binds, whatever its form; a flag next to an unusable value wins).
  Write the claim from a probe of each form, not from the one that you tried.
- A sentence that says what a test proves is a claim too: a title that says
  "and change nothing" needs an assertion that can see the change (the audit
  cmdlets write the SACL, not the DACL), and "cannot go red" needs a run.
- The cause was `DefaultParameterSetName = "PathComplex"`: when a piped object
  satisfies the mandatory parameters of the default set, PowerShell settles on
  it and never tries a parameter that belongs to another set. A stand-alone
  model with the four sets and no default binds `PathSimple` for an object with
  `AppliesTo`, `PathComplex` for one without, and an error for one with
  `AppliesTo` and `InheritanceFlags` (`probes\p-parameterset-binding*.ps1` in
  the Handoff 5 evidence; the model binds `PathComplex` for a piped descriptor
  where the real cmdlets bind `SDSimple`); the real cmdlets agreed for paths
  (`probes\p-proto-appliesto.ps1`). The default dated from 4.2.6, when
  `AppliesTo` was optional; `4b1abc9` made it mandatory in the Simple sets, so
  the default no longer decided a named call. Build a model of the parameter
  sets before you change an attribute, and test the real cmdlet afterwards.

## A swallowed initialization error (`catch { }`)

- `Win32.GetEffectiveAccess` ran the start of the authorization manager inside
  an outer `catch { }`. A refusal there gave no exception and no rights, so the
  cmdlet wrote an entry with `Synchronize` only (.NET adds it to every allow
  rule) and no error: a false "no access". The security review of the matrix
  found it (LOW); rc8 fixed it (`25fe775`) with one `try`/`catch` that records
  every exception in `authzException`.
- A trigger without a test seam: `Get-NTFSEffectiveAccess -ServerName ('a' *
  40000)`. `AuthzInitializeRemoteResourceManager` fails with error 14 for a name
  of 32,718 characters or more, and with 1722 (RPC server unavailable, which
  keeps the documented fallback and its warning) for a shorter one. Server
  2019, 2022, 2025, and Windows 11 26H1 agree (a probe in the rc8 record). Bisect
  the length of an input before you add a seam.
- The test accepts both outcomes (an error, or the result of this computer) and
  fails for no access without an error: the red run said `Expected FullControl,
  but got Synchronize`. A system-dependent boundary must not fail the test where
  a system answers like for a short name.
- The review found a second flaw in the same output: the warning "the result is
  based on this computer" came before an error that left no result. A warning
  that qualifies a result belongs with the result (`!FromRemote &&
  !OperationFailed`); the tests assert its absence next to the error.
- A word in the CHANGELOG is a claim: "an overlong name" suggested 256
  characters, where 1722 still falls back. The entry names the probed length.

## A helper that waits for a child that never started

- The helper that ran a test file in the four CI configurations passed the
  Pester name filter to the basic-user run through `runas /trustlevel:0x20000
  "…"`. A filter with spaces (`*treat a path with brackets*`) broke the nested
  quotes, the child never started, and the helper waited for its whole timeout
  (30 minutes). An implementer blamed the load of four agents at once; a call
  alone with the same spaced filter showed the helper.
- The filter now travels as base64 (`-FullNameBase64`), and a basic-user run
  gives up after 60 seconds when its runner never started (about 6 seconds
  normally). Before you blame the load for a stall, repeat the call alone with
  the same arguments.

## Optional enum parameters that take pipeline input by property name

- The binder skips a piped property that it cannot convert to the type of an
  OPTIONAL parameter and keeps the default: a typo for `Deny`, a blank CSV
  cell, or a misspelled scope silently made an Allow entry or the default
  scope (probe `p-unconvertible-optional-params.ps1` on rc8, both editions; a
  named call fails loudly; one parameter set with optional parameters does not
  help). `Get-FileHash2 -Algorithm` has the same flaw and stays a known limit.
- Decision 27, fix B: the five parameters of the four add and remove cmdlets
  are `object`, converted in the cmdlet by `ParameterConversion`. All five
  must be `object`: with `AppliesTo` alone, a row with `AppliesTo` and flags
  lost its `AmbiguousParameterSet`. The price was found by the review, not by
  the author's tests: a `$null`, DBNull, or blank value of the OTHER group
  binds too (a CSV with columns of both groups is `AmbiguousParameterSet`); a
  named `$null` binds, where rc8 refused it (`MyInvocation.BoundParameters`
  shows it in `BeginProcessing`); a script block is no longer delay-bound; the
  completion of the names has to be rebuilt (quotes, wildcards, declaration
  order); help shows `Object`. Probe every form of a value before you write a
  claim, and ask a reviewer for the negative space.
- PowerShell accepts a comma list or an array for an enumeration that is not
  `[Flags]` and combines the numbers bit by bit (a logical or):
  `-AppliesTo 'ThisFolderOnly,FilesOnly'` made a `FilesOnly` entry and
  `-AccessType 'Allow,Deny'` a `Deny` entry (4.2.6 and rc8 alike). The
  conversion rejects a list for such an enumeration, in whatever kind of
  collection it comes; a single name and a one-element collection stay valid.
  A matrix of valid shapes, run on the published build and on the new one,
  showed that exactly the 9 list rows changed. Code that opens a one-element
  collection needs a depth limit: an array that holds itself hung the first
  version (the binder of rc8 ends the host with a stack overflow on it), so
  the conversion opens at most 32 levels and reads at most two elements. The
  three flags parameters still hand such a collection to PowerShell's own
  conversion, which ends the host with a stack overflow, as in rc8; not fixed
  (no real input builds one, and a test would end the Pester process too).
- The message of a bad value is built inside a catch block, and a formatter
  there must not throw: `Describe` called `ToString` of the one element outside
  a guard, so an element whose `ToString` throws (a script method) ended a
  piped command with an `ExtendedTypeSystemException` instead of one error for
  that item (found by the last delta check of the second review; the version
  before named a collection by its type and never formatted an element). Wrap
  the whole formatter and fall back to the type name, in the short form
  (`Type.ToString`; `FullName` spells out the assembly of every generic
  argument). A test that pins a limit (ten elements named, two elements read)
  is green on the code that it guards: prove it with a mutant of the limit (no
  limit: 4 rows red; a limit of nine: 6 rows red).
- A loop that stops early runs `Dispose` of the enumerator, and `Dispose` can
  fail: the catch of `TakeOneValue` returned the collection to PowerShell's
  conversion, which combines a list bit by bit, so a sequence whose enumerator
  throws in `Dispose` let a list through. The first patch (`isList = count >
  1` in the catch) fixed the reported shape (two elements) and left its
  sibling (one element that holds a comma list); the closing check found it.
  Fix the root: read with an explicit enumerator and release it in its own
  guard, so that a failing release never changes what was read. The test needs
  a compiled stand-in (`Add-Type`, as `PipelineControl.Tests.ps1` does); no
  built-in enumerator fails in `Dispose`.
- PowerShell calls the getter of a by-property-name parameter once per
  command, when a piped object first binds it (`p-getter-calls.ps1`). A test
  that must visit it pipes an object that has the property. A property getter
  that throws reads as `$null` without a trace: test it through reflection.

## A differential oracle that covers part of the input

- The matcher of `Get-ChildItem2 -Filter` was checked against Windows
  PowerShell 5.1 over 55,987 patterns, on 8.3-compliant names only, so that the
  short name is the real name. Such names have at most one dot, where the first
  and the last dot are the same, so a rule about the LAST dot was invisible:
  `*.??` dropped `archive.tar.gz`. The review found it with 849k pairs. Cover
  every dimension of the input, and neutralize a quirk of the oracle instead of
  avoiding the inputs that trigger it: `fsutil file setshortname` gives a long
  name a short name that matches nothing, `fsutil 8dot3name strip` removes it.
- A very long pattern ended the host with a stack overflow (recursion depth =
  tokens): bound the input of a recursive matcher (`ValidateLength`).

## Agents in parallel worktrees

- `git stash` is ONE list for all worktrees: a `pop` takes the top entry of
  whoever created it and moved the edits of one agent into another's tree. The
  brief forbids stash, `restore`, `reset`, `clean`, and checkout of a sha; a RED
  run on the unchanged product uses a private base worktree. Protect a foreign
  stash with `git update-ref` before anything else.
- An agent that ends its turn without a report may have done nothing (a clean
  worktree and an empty probe folder said so): write to it and ask.
- Help generation: `Update-MarkdownHelp` reads `Position` from the help file
  that the build copies, not from the C# attribute, so a page edit alone drifts:
  edit the page, `New-ExternalHelp`, rebuild, then check the docs (the files are
  a fixpoint). A pair of asterisks in one paragraph loses them in the XML.