New-PfbNlmReclamation -Name is a mandatory dead selector: the endpoint declares no names parameter and the operation is array-wide

[juemerson-at-purestorage]

New-PfbNlmReclamation makes -Name mandatory and sends it as a names query key. The endpoint declares no names parameter, and the operation it performs is array-wide.

Evidence

Public/FileSystem/New-PfbNlmReclamation.ps1:27-43 → POST /nlm-reclamations.

In every spec from tools/specs/fb2.8.json through fb2.28.json the operation declares no required query parameter and no request body, and no names parameter at all. The endpoint's own description treats reclamation as a system-wide operation rather than something addressed at a named object.

FlashBlade silently drops an undeclared query key rather than rejecting it, so the call succeeds and the value is discarded. There is no error to notice.

Why it matters twice over

The dead key itself is harmless — it goes nowhere. The mandatory parameter is the actual defect:

1. It forces every caller to invent a value that is guaranteed to have no effect, which is the opposite of what a mandatory parameter communicates.
2. It states, in the strongest form the language has, that this operation is scoped to one named thing. It is not. A caller reading only the signature would reasonably conclude they can reclaim locks for a single file system, and would be wrong in a way no runtime feedback corrects.

An optional parameter sending a dropped key would be untidy. A mandatory one is actively misleading about the operation's blast radius.

Scope

Reconcile the public interface with the operation the endpoint actually performs: drop the names query assignment, and decide whether -Name should be removed outright or retained as an optional, explicitly-documented no-op for backwards compatibility. Removing a mandatory parameter is a breaking change to any caller that supplies it positionally, so that call belongs to the maintainer.

Worth checking as part of the same pass whether the array offers any scoping mechanism for reclamation at all. If it does not, the cmdlet's help should say so — that is the part a caller cannot discover from the signature.

Relationship to other issues

This is a dead-key/misleading-interface concern, not a missing-required-input defect, so it is deliberately not part of #106 Part 2's required-field count.

It shares its shape with #124 (a declared query key whose response items carry no such field) but is a step further out: here the key is not declared at all. The dead-key report's committed ceiling covers keys it can see; this one is worth confirming appears there.

Found by the issue #106 Part 2 audit.

[juemerson-at-purestorage]

Written by Claude during triage, reviewed by @juemerson-at-purestorage before posting.

Triage: moved to status:needs-design

This issue was briefly labelled status:agent-ready during the label backfill on 2026-09-21. That was too optimistic and is now corrected. Nothing about the evidence here is in doubt — the blocker is that the approach is not decided, and an unattended agent given this issue would have to invent the decision.

The decision is shared with two other issues

#138, #139 and #142 all turn on the same question, which is why none of them is ready and why answering it once unblocks all three:

A cmdlet exposes a mandatory parameter whose wire key the endpoint cannot use — either undeclared entirely, or declared but unusable against the object it would select. Do we remove the parameter, or retain it as optional and stop sending the key?

Removing a mandatory parameter breaks any caller supplying it positionally. Retaining it as an optional no-op keeps those callers working but leaves a parameter that does nothing, which has to be documented as such or it becomes the next person's bug report. #138's own body says this call belongs to the maintainer, and the same reasoning applies to the other two.

The three instances, so the decision can be made against real cases rather than in the abstract:

Issue	Cmdlet	Key	Why it cannot work
#138	New-PfbNlmReclamation	names	Endpoint declares no names at all, in any version. The operation is array-wide.
#139	Update-PfbLegalHoldEntity	names	names is declared, but a held entity has no name. The real selector is file_system_names + paths + recursive, measured live.
#142 (part 2)	New-PfbCertificateSigningRequest	names	Endpoint declares no query parameters at all. May be a body property instead — not yet established.

A consistent answer across the three is worth more than three independently reasonable ones, in the same way #83 and #95 are paired.

What would make this status:agent-ready

A maintainer decision on remove-versus-optional, recorded on this issue. With that in hand each of the three becomes a small, well-specified change, and #139 already has its working request form measured on a live array.

[juemerson-at-purestorage]

Written by Claude during triage, reviewed by @juemerson-at-purestorage before posting.

Decision: remove the parameter outright

Following up the shared-decision comment above. The policy for a mandatory parameter whose wire key the endpoint cannot use is:

Delete the parameter. No deprecation window, no optional no-op.

Applies to this issue and to #139 / #138 (whichever of the pair this is not). It does not apply to #142 — see the note there; that one turned out to be a different defect.

Why removal rather than an optional no-op

The obvious objection to removing a mandatory parameter is that it breaks any caller supplying it positionally. That break surface was measured, and it is effectively empty:

PureStorageFlashBladePowerShell   not on the PowerShell Gallery
EverpureFBModule                  not on the PowerShell Gallery
PureStoragePowerShellSDK          PUBLISHED: 1.5.5.1 … 1.19.49.0   <- control

The module has never been published. The control in the third row matters: it is the same query against a module that is published, returning eleven real versions, so "not on the Gallery" is a true negative rather than a broken lookup.

#23 (publish 2.2.0 to the Gallery) is still open. So this is the last moment at which the signature can be corrected without breaking an installed base — after publication the same change costs a major version. Deprecating now would buy a compatibility guarantee for users who do not exist yet, and would ship a parameter that does nothing into the first public release.

Why not keep it as a documented no-op

Because that preserves the defect this issue is actually about. As #138 puts it, the mandatory parameter "states, in the strongest form the language has, that this operation is scoped to one named thing" — and it is not. An optional no-op still says the operation takes a name. The signature is the documentation people read; a .PARAMETER note saying "has no effect" is the documentation they do not.

What this means concretely

• Delete the parameter from the signature.
• Delete the query-key assignment that sends the dead key.
• Update the comment-based help and examples so nothing references it.
• If the operation's real scope is not obvious from the remaining signature (New-PfbNlmReclamation -Name is a mandatory dead selector: the endpoint declares no names parameter and the operation is array-wide #138: reclamation is array-wide), say so in the help. That is the part a caller cannot infer from what is left.
• Treat it as a breaking change in the notes for whoever writes the eventual CHANGELOG entry. Do not touch CHANGELOG.md or the module version in the PR — those are the maintainer's, always.

Status

Moving to status:design-approved. @dmann000 — this is a public-interface change decided without you because it is cheap to reverse before publication; if you would rather keep the parameter as an optional no-op, say so on the PR and it is a small edit in the other direction.