Update-PfbLegalHoldEntity -Name is a mandatory but unusable selector: a held entity has no name, and the array rejects a request selected only by it

[juemerson-at-purestorage]

Update-PfbLegalHoldEntity makes -Name mandatory and sends it as names on PATCH /legal-holds/held-entities. A held entity has no name. The array does not accept names as a selector for this operation, and the parameter's mandatory-ness makes it look like the primary one.

The spec says the key is declared

Unlike the New-PfbNlmReclamation case, names is not an undeclared key here — PATCH /legal-holds/held-entities genuinely declares names (query, optional) in every version from REST 2.17 through 2.28, alongside ids, file_system_names, file_system_ids, paths and recursive.

But the object it would select has no name to match. #/components/schemas/LegalHoldHeldEntity declares exactly four properties in 2.26:

file_system, legal_hold, path, status

No name, no id. A held entity is identified by the combination of the hold, the file system and the path — which is why the operation carries file_system_names and paths as separate keys rather than a single composite selector.

This is already known for the read side: Tests/Fixtures/PfbSelectorWaivers.psd1 waives GET /legal-holds/held-entities in the selector rail with the note "its items carry no name (file_system, legal_hold, path, status)." The waiver covers the read; the write side inherited the same declared-but-unusable key with a mandatory parameter in front of it.

Measured on a live array

FB-A, Purity//FB 4.8.2, REST 2.26, against a harness-created file system with a harness-created hold applied to it.

Naming only the hold — which is what a caller following the cmdlet's mandatory -Name would do:

Update-PfbLegalHoldEntity -Name <hold> -Released $true
  → 400  Either names or ids query parameter is required.

Note what that error is not. It is not "no such entity" and not "invalid name" — the array reports the selector as absent, having been sent names=<hold>. That is consistent with FlashBlade dropping a key it cannot apply and then finding itself with no selector at all.

Adding the file system and path but omitting the recursive flag:

Update-PfbLegalHoldEntity -Name <hold> -FileSystemNames <fs> -Paths '/' -Released $true
  → 400  Can't apply or release legal holds to directories without the recursive flag provided.

The form that actually works:

Update-PfbLegalHoldEntity -Name <hold> -FileSystemNames <fs> -Paths '/' -Recursive $true -Released $true
  → 200

So the real selector is file_system_names + paths + recursive, and -Name contributes nothing to it. The release proved synchronous — the hold deleted immediately afterwards with no status read-back needed.

The error text on the third form is identical to the one New-PfbLegalHoldEntity (the apply direction) produces for the same omission, so release is symmetric with apply rather than special-cased.

Why the mandatory parameter is the defect

names being declared-but-inapplicable is the array's business and matches the existing read-side waiver. What this repo owns is the signature. -Name mandatory says: this is how you address the thing you are changing. It is not. A caller supplying only -Name — the one parameter the cmdlet forces them to supply — gets a 400 whose text points at the selector rather than at their mistake.

Scope

Decide what -Name should be on this cmdlet. Options, in rough order of preference:

1. Drop -Name/names and make the real selector explicit — the file system plus path plus recursive triple the array actually uses.
2. Keep -Name as optional and documented as ineffective, and add a preflight check that a usable selector was supplied.

Either way the help should state the working form, since it is not inferable from the parameter list.

Note that -Name is currently mandatory, so removing it or demoting it is a breaking change for any caller passing it positionally. That call belongs to the maintainer.

Relationship to other issues

This is the same family of defect as #124 (a declared query key whose response items carry no such field) and shares its interface consequence with the New-PfbNlmReclamation -Name issue filed alongside this one. It is distinct from the released requiredness defect that #106 Part 2 identified on this same cmdlet — that one is a missing required input and is being fixed directly; this one is an unusable selector and is not.

Found while live-verifying the #106 Part 2 released fix, using the legal-holds live-test gate opened for that purpose.

[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.