Audit every pipeline-bound selector against the response schema, and guard the ones that cannot bind (#90)

[juemerson-at-purestorage]

Closes #90.

What this does

#90 asked for three things: audit every pipeline-bound selector against the field its resource
actually returns, decide per cmdlet whether to guard / alias / drop, and add a rail so a future
cmdlet cannot reintroduce the defect quietly. All three are here.

The audit is observational, not inferred. tools/Build-PfbPipelineSelectorMap.ps1 imports the
shipped module, shadows the request layer inside module scope with a capture shim, pipes a
schema-derived probe object into the real cmdlet, and records what actually reached the wire.
Nothing in the report is a conclusion drawn from reading source.

Result over 1,247 probe pairs (1,213 evaluated, 629 genuine candidates, control leakage 0):

Outcome	Rows	Meaning
Bound	578	bound correctly, no coercion
Coerced	264	the defect: whole object stringified into the selector
Unbindable	234	PowerShell declined to bind this probe object
Guarded	116	a coercion guard fired
NoSelector	47	nothing pipeline-bound to coerce
CmdletError	6	the cmdlet threw before a request was built
BindError	2	the only unmeasured outcome, pinned so it cannot grow silently

A correction to the issue's premise

#90 (and the tooling written for #64) states that binding resolves in three passes. It resolves
in four — ByValue, ByPropertyName, ByValue with coercion, then ByPropertyName with
coercion. Measured on pwsh 7.6.4.

This is not pedantry, it changes a remedy. The three-pass model implies that removing
ValueFromPipeline makes coercion structurally impossible, so Unbindable was documented as
immunity. It is not: a ValueFromPipelineByPropertyName-only parameter whose alias matches an
object-valued property still binds that object stringified at pass 4. Such a parameter needs a
guard, not an attribute removal. The tooling's comments and the Unbindable verdict text are
corrected accordingly.

What changed, by kind

A coercion guard — the one new runtime component. Private/Assert-PfbSelectorNotCoerced.ps1,
called as the first statement of process in 18 read cmdlets. It turns a silently unfiltered
result into an actionable error naming the property to pipe instead.

Two constraints in it are load-bearing and commented as such: it must stay imperative in
process, because a ValidateScript failure on a pipeline-bound argument is non-terminating
and end would still issue the unfiltered request; and its message must keep the substring
stringified object, which is how the map generator classifies the Guarded outcome.

Its predicate is structural rather than textual. It compares the bound selector against the
original pipeline item's own ToString() and suppresses the check when the item exposes a property
that could legitimately have bound. That catches a Hashtable and a generic Dictionary, which
render as bare type names and were invisible to the previous @{ test, without the type-name
pattern matching that would falsely reject a resource legitimately named e.g. System.backup.

Selector keys corrected where a cmdlet sent a generic names/ids to an endpoint that declares
a resource-specific key instead, and parent names preserved so policy-family pipelines bind at
pass 2 rather than falling through to coercion.

Dead selectors removed — parameters the endpoint declares no key for, which were therefore
either dropped on the wire or sent as a key the array ignores.

Reports regenerated: selector map, dead-key report, field/cmdlet map, API drift report.

Breaking changes

Please read this section rather than skimming it. Every removal below is a parameter that could
not work — the endpoint declares no corresponding query key at any cached spec version, so the
parameter either silently did nothing or put a key on the wire that the array ignores while
returning the unfiltered collection. The authoritative pinned list is
Tests/PfbDeadSelectorRemoval.Tests.ps1.

Renamed, old name still callable — not breaking

• Update-PfbBucketAuditFilter: -MemberName → -BucketName, -MemberId → -BucketId,
  -FilterNames → -Name. All three old names retained as aliases.
• Get-PfbLocalGroupMember: -Group → -GroupName, with Group retained as an alias.

Parameters removed — breaking

Cmdlet	Removed
Get-PfbBucketAccessPolicy	-Id, -MemberId, -MemberName, -PolicyId, -PolicyName
Get-PfbBucketAccessPolicyRule	-Id, -MemberName
Get-PfbBucketAuditFilter	-MemberId, -MemberName
Get-PfbBucketCorsPolicy	-Id, -MemberId, -MemberName, -PolicyName
Get-PfbBucketCorsPolicyRule	-Id, -MemberName
New-PfbBucketAccessPolicy	-MemberName, -PolicyName
New-PfbBucketAccessPolicyRule	-MemberName
New-PfbBucketAuditFilter	-MemberName
New-PfbBucketCorsPolicy	-MemberName, -PolicyName
Remove-PfbBucketAccessPolicy	-MemberName, -PolicyName
Remove-PfbBucketAuditFilter	-MemberId, -MemberName
Remove-PfbBucketCorsPolicy	-MemberId, -MemberName, -PolicyName
Get-PfbCertificateGroupCertificate	-Name
Get-PfbObjectStoreTrustPolicyRule	-PolicyId
Get-PfbOpenFile	-Filter, -Name, -Sort
Remove-PfbOpenFile	-Name

On Get-PfbOpenFile, filter and sort are declared at no version 2.17–2.28 (the endpoint
does not exist before 2.17), so they were inert.

Note one deliberate asymmetry: the Remove-Pfb* bucket cmdlets underwent the same
MemberName/MemberId rename but were given no compatibility aliases, while Update-* was.
Their legacy parameters wrote undeclared keys and so over-deleted; aliasing those onto a key that
does work would quietly change what a DELETE removes, which is worse than the break. The
rationale is recorded in the code so it does not read as an oversight.

Regression protection

• Tests/PfbPipelineSelectorRail.Tests.ps1 — Rail A asserts no unwaived selector coercion,
  and surrounds it with waiver hygiene: every waiver must name a cmdlet, parameter, issue and
  reason, be used exactly once, still cover exactly the producer count it was granted for, and —
  the sharp one — carry no waiver for a pair that no longer coerces, so a stale waiver fails
  rather than lingering. Rail B regenerates the map and requires byte-identical JSON and
  Markdown.
• Tests/Fixtures/PfbSelectorWaivers.psd1 — 101 entries, one per remaining coercion pair, each
  with Cmdlet / Parameter / Issue / Producers / Scope / Why. 100 are Family-scoped. These are
  pairs that cannot be fixed within one cmdlet: the coercion originates at a cross-endpoint
  producer, so the ceiling is documented per pair rather than waved at.
• Six new test files (~2,600 lines) pinning the specific decisions.

Rail B self-skips when the gitignored tools/specs cache is absent, which is worth knowing when
reviewing from a fresh clone.

Verification

Unit — scoped, both editions. Per-task and final runs were scoped to the touched files and run
under pwsh 7 and Windows PowerShell 5.1, judged by the container column rather than the counts.
Final re-review run: pwsh 7 292 passed / 0 failed / container ok; WinPS 5.1
281 passed / 0 failed / 11 skipped / container ok.

The aggregate full suite was not run locally — it exceeds the local tool timeout and CI owns it.

Aggregate, cross-OS — CI, and it caught something the scoped runs could not. The first CI run
on this branch failed on all four OS/edition jobs: 3,162 passed, exactly 2 failed. Both failures
were in tests this PR itself pins, and neither was a defect in the shipped code — but they were
real failures and are worth reading rather than skipping to the green result below.

Both were baseline figures pinned during the Stage 1 audit that the Stage 2 fixes deliberately
invalidated — probePairs 1179→1247, findings 389→264, coerced pairs 127→101 in
Tests/Build-PfbPipelineSelectorMap.Tests.ps1, and the module-wide pipeline-bound population
303→311 with ValueFromPipeline 214→209 in Tests/PfbPipelineSelectorTools.Tests.ps1.

These escaped every scoped per-task run because they assert on the module and the committed
artifact as a whole rather than on the files any one task touched — the exact blind spot scoping
trades away, and the reason CI runs the aggregate.

Both are now re-baselined, and neither figure was simply overwritten. The population change was
verified by diffing Get-PfbPipelineBoundParameter between origin/main and this branch: 26 rows
added, 18 removed, net +8. Every added row is the new name of a renamed selector, a selector
replacing a removed dead one, or a parent-name selector added so a policy-family pipeline binds by
property name instead of coercing; every removed row is one of those old names or a dead selector
this branch deleted. No row changed its ValueFromPipeline value, which independently
corroborates the four-pass correction above — the attribute removal was rejected as a remedy, so
nothing used it. The coerced-pair figure is cross-checked rather than free-standing: 101 is also the
waiver fixture's entry count, and Rail A fails on a waiver for a pair that no longer coerces, so the
two cannot drift apart quietly. The reasoning is recorded in the tests, so a later reader can tell a
justified re-baseline from a silenced tripwire.

The re-run is green on all four jobs: 3164 passed / 0 failed / 2 skipped on pwsh 7 across
ubuntu, macos and windows, and 2908 passed / 0 failed / 258 skipped on Windows PowerShell 5.1.

That also settles the one thing only a full-suite result can measure. The coverage gate reported
Coverage gate passed for both the pwsh7 and winps51 profiles on every job — so the
Tests/coverage-baseline.psd1 ceilings hold as-is, and no ceiling was raised against an unmeasured
figure.

Live — a lab FlashBlade at REST 2.26, reads and scoped writes. Mocked tests pass while a wire
contract is wrong, so the guard and the corrected keys were exercised against a real array.

Gaps, stated rather than omitted:

• The array holds no data for network-interface neighbors, certificate-group certificates, local
  groups/members, NFS export rules, or bucket access policies, so those paths are verified only
  for request construction and guard behaviour, not for correct rows.
• 13 of the 18 guarded cmdlets were not individually exercised live.
• Both POST cmdlets returned Skipped-Policy from the live harness's safety rails — the rails
  working as designed, not evidence of success.
• The claim that Get-PfbOpenFile's removed -Filter/-Sort were inert is spec-derived, not
  measured on the wire.

Found along the way, filed separately

• [P0] Empty list results return a coercing total_item_count wrapper; piping it can silently return the full collection #121 (P0) — Invoke-PfbApiRequest returns a one-element total_item_count wrapper on any
  empty list result, which is truthy, reports Measure-Object count 1 when the answer is zero, and
  coerces on the pipeline into names=@{total_item_count=0}. On at least one endpoint the array
  ignores that key and returns the full collection. Pre-existing on main, untouched here, and
  in the shared response layer, so it needs its own change and its own decision about -TotalOnly.
  The guard in this PR happens to catch it on its 18 cmdlets — useful evidence the approach
  generalises, but not a fix.
• Three sibling guards (Assert-PfbAdminNameNotCoerced, Assert-PfbRemoteNameNotCoerced,
  Assert-PfbFileSystemReplicaLinkTransferNameNotCoerced) still document the falsified three-pass
  model. Pre-existing on main and out of scope here; worth a follow-up sweep.
• One known gap is documented in the guard itself rather than papered over: a Hashtable-valued
  property binding at pass 4 via an alias passes both signals. Closing it means comparing against
  each binding property's ToString(), which widens the false-positive surface — a maintainer's
  call, not a drive-by. Reachability is low because ConvertFrom-Json yields PSCustomObject,
  whose ToString() does contain @{.

Two upstream specification defects were also established during this work and are being routed
to the API team rather than filed here, since neither is a module bug:

• GET /file-systems/open-files advertises protocols=nfs, which the array rejects with
  Unsupported protocols specified in the parameters while accepting smb.
• Ten collections declare ids and eight declare names over item schemas carrying no such field,
  so the selector silently does nothing and the caller gets an unfiltered 200.

Not included, deliberately

No version bump and no CHANGELOG entry — those are maintainer decisions in this repo.

Diff size

58 files, +10,231 / −4,933. The bulk is regenerated report artifacts and new tests; the runtime
change is one new private helper plus selector corrections across 35 files under Public/.