fix: teach the empty-pipeline guard to tell a selector from a scope key (#126, #128)

[juemerson-at-purestorage]

Closes #126. Closes #128.

The defect

Test-PfbEmptyPipelineRead could not tell a selector (a key naming which objects the caller
wants) from a scope or shaping key (one that narrows, sorts or projects whatever is already in
scope). It suppressed a request only when the query was completely empty, so:

@() | Get-PfbFileSystem -Limit 10

issued an unfiltered read and returned file systems the caller never addressed. An empty pipeline
means "no objects were selected"; -Limit cannot select anything, so there was nothing to read.

What changed

Test-PfbEmptyPipelineRead now classifies every key in the outgoing query. If an empty pipeline
carries only non-selector keys the request is suppressed, and the caller gets a warning naming
the parameters that could not select. If any selector is present the request goes out exactly as
before.

Direct calls are never affected — ExpectingInput gates the whole predicate and is the first
executable line. Get-PfbX -Limit 10 typed at a prompt is a deliberate unfiltered read and stays
one. The change can only ever remove a request from the wire, never add or alter one.

One behaviour change worth calling out

@() | Get-PfbAlert -Flagged $true returns every alert on main and is suppressed here.

flagged is a dead key server-side (#142 — undeclared in all 29 published REST versions), so it was
initially reasoned about as an inert classification. That was wrong, and it is the one place where
this policy visibly changes a shipped cmdlet's output: dead-key-ness governs what the server does,
while this predicate decides on key presence and never reaches the server. Get-PfbAlert writes
the key under ContainsKey, and an undeclared parameter is a silent pass in the capability check, so
nothing stopped the send. Of the twelve classified keys this is the only one whose classification
demonstrably alters current output; it now carries a behavioural test.

Guard dominance (#128)

The existing rails asserted a guard existed in a cmdlet's end block, not that it executed on
every path to the request. A guard inside an if, a foreach, a switch case or a try body
satisfied the old check while leaving paths that reach the request unguarded. The rail now flags
those positions, with one deliberate subtlety: for an if, Clauses[i].Item1 is exempt only at
i == 0 — at i > 0 it is an elseif condition, which is itself conditionally executed. The
exemption is positional rather than sticky, so a guard at Clauses[0].Item1 nested inside a loop
still flags.

Also closed: a guard inside a nested function in an end block was invisible to every rail. The
enclosing search is recursive, so such a guard counted toward the outer cmdlet, while the
nesting check tested only for a scriptblock expression — and a function definition body is a plain
script block, not one. Its return would exit only the nested function, leaving the request to go
out with every rail green. Zero occurrences today; this is a tripwire.

Design decisions

A denylist, not an allowlist. $script:PfbNonSelectorQueryKeys lists the twelve non-selector
keys; anything unlisted reads as a selector. The failure direction is what decides this: a key
nobody classified yet gets treated as a selector and the request is issued — today's behaviour.
An allowlist would fail toward suppressing a legitimate read, which is new breakage. filter and
context_names are deliberately absent.

The list decides, not a spelling test. The predicate never consults the names/ids/*_names
shape test used by the CI gate. The two have opposite defaults, and filter is where that bites:
it matches no identity shape, so a shape test would call it a scope key and suppress a legitimately
filtered call. filter is reachable in 124 of the 130 guarded cmdlets.

Three classifiers, deliberately divergent. This policy, the CI shape test, and the dead-key
report's Test-PfbDeadKeySelectorName disagree by design, because their failure modes differ — a
misclassifying report produces a wrong row, a misclassifying runtime policy discards a request. Each
now carries a comment naming the others and stating why they differ.

Two contested placements left alone. Get-PfbRemoteArray's guard stays above its
current_fleet_only write: now that the key is classified, placement no longer changes the
decision, and moving it would drag a test allowlist change along for no benefit. The one consequence
is documented rather than "fixed" — because the guard runs before the write, an empty-pipe call
reaches it with an empty query and takes the quieter verbose-only path.

New CI rails

• A completeness gate that reds the build when a guarded cmdlet writes a query key no classifier
  knows about, failing closed on any query argument it cannot statically resolve.
• Guard-dominance and call-shape rails, including a mutation-tested nesting detector — that predicate
  is one-way, so if it regressed to always-false two other assertions would pass vacuously.
• A derived safety assertion replacing a hand-maintained list of cmdlet names that had gone stale:
  every guarded cmdlet whose verb is not Get/Test must carry a mandatory parameter in every
  parameter set. Otherwise the diagnostic's "call it directly instead of piping to it" advice could
  mean an unscoped destructive call. Unknown verbs default to state-changing, and the population is
  asserted non-empty so the check cannot pass vacuously.

Verification

Tests — scoped, both editions, Container ok throughout:

Scope	pwsh 7	Windows PowerShell 5.1
The seven files touched by the final round	58 / 0 / 0	58 / 0 / 0
Ten-file set incl. dependents	92 / 0 / 0	86 / 0 / 6 skipped

The derived-artifact gate reports all 11 committed artifacts up to date.

Live FlashBlade — this PR touches Private/ and Public/, so it is not exempt from live
verification. Run against an internal lab array, Purity//FB 4.8.2, REST 2.26, as the local array
account (nothing here involves context_names). Every call below is a read; nothing was created,
modified or deleted.

probe	invocation	main	this branch
A — the #126 defect	@() | Get-PfbFileSystem -Limit 10	2 (the full unfiltered inventory)	0, one warning
B — already suppressed	@() | Get-PfbFileSystem	0	0
C — control, selector present	@() | Get-PfbFileSystem -Filter "name='*'"	2	2
D — control, non-empty pipe	'fs-share' | Get-PfbFileSystem -Limit 10	1	1

A: 2 → 0 with B, C and D unchanged is the finding. The array holds only two file systems, so the
unfiltered read caps at 2 rather than 10 — the assertion is "same as an unfiltered read" versus
"zero", not the literal number. The zero alone would prove nothing, since a broken cmdlet also
returns zero; C and D returning their normal counts in the same session is what rules that out.
Counting used a non-null name filter, because @($null).Count is 1 and this module's empty list
result is a coercing wrapper whose | Measure-Object also reports 1.

Probe A emitted exactly one warning, naming the offending parameter:

Get-PfbFileSystem received an empty pipeline, so no object was selected. -Limit can only narrow or
shape a result set, not select objects, so no request was issued. If you did not intend to filter,
call Get-PfbFileSystem directly instead of piping to it.

Two harness ledger rows recorded the control in the other direction — a direct call with a
non-selector must still issue: Get-PfbFileSystem -Limit 2 (Pass, 264 ms) and
Get-PfbFileSystem -Name fs-share (Pass, 213 ms).

The probes were captured at a472a3f; the four commits since touch only Tests/, the design spec,
and comments. Both changed Private/ files are byte-identical after stripping comments (84 and 16
executable lines, unchanged), so nothing since the capture can alter what goes on the wire.

Not included

No version bump and no CHANGELOG.md entry — those are the maintainer's call.