Follow-up scope for #31 (write-cmdlet body parameters): everything deliberately deferred

[juemerson-at-purestorage]

Context

#31 converted 56 New-/Update- cmdlets to typed body parameters — implemented, independently
reviewed, merged into the integration branch, drift-confidence-guarded, full-suite regression
tested on both pwsh 7 and Windows PowerShell 5.1, and 22 live-tested against a real FlashBlade
(FB-A) with zero defects found. Nothing about those 56 cmdlets needs further work.

This issue exists purely to capture what the plan deliberately left out of scope, so it isn't
silently lost. Two groups below: (A) scope named in the original plan's own Task 13, and (B) items
surfaced and deferred during the #31 SDD session itself (2026-07-27 through 2026-07-28).

Group A — originally out of scope per the plan

1. Three cmdlets Don named on 2026-07-26 that fall outside the 56-cmdlet scope:

   • New-PfbActiveDirectory — 13 body fields + join_existing_account/names query params.
     Also carries two of Don's live-behavior claims that need verifying against a real array, not
     just the spec: the vserver::name default-attachment behavior, and a claimed silent
     aes256 encryption-type default.
   • New-PfbServer — dns field. create_ds and create_local_directory_service are already
     confirmed as genuinely distinct query parameters (settled, not open).
   • Update-PfbServer — 1 documented body field (see the field-reference doc / drift report for
     which one).

2. The other ~78 New-/Update- cmdlets with body gaps this plan didn't touch. PR Drift Report enhancements: per-parameter confidence, enrichment, systemic gaps, annotations #60's
   drift-confidence rework made these visible: 137 total write cmdlets have body gaps across the
   whole module; Write cmdlets silently drop documented body parameters (~48 New-*/Update-* cmdlets) #31 closed 56 of them. The remaining ~78 are a distinct, larger follow-up effort
   — see Reports/PfbApiDriftReport.md for the current list rather than duplicating it here.

3. Parser-gap triage for the Enabled/Name escape-hatch clusters. 41 endpoints are stuck at
   partial drift-confidence because of two escape-hatch field-name clusters (Enabled on 15+
   endpoints, Name on 12+) that the AST resolver can't currently trace through. This blocks
   confidence-based enrichment for most of the remaining ~78-cmdlet scope in item 2. Related:
   API drift report: systemicGaps/conventionStrength only aggregate over high-confidence endpoints, undercounting some field names #59.

4. Unpersisted DeprecatedBodyProperties gap. tools/lib/PfbSpecTools.ps1 computes which
   body properties are spec-deprecated, but Build-PfbCapabilityMap.ps1 never writes that flag
   to Data/PfbCapabilityMap.json. Consequence: deprecated fields keep surfacing as addable gaps
   in the drift report even after being deliberately excluded by hand. Write cmdlets silently drop documented body parameters (~48 New-*/Update-* cmdlets) #31 hand-excluded 3 such
   fields (role on Update-PfbAdmin and Update-PfbDirectoryServiceRole, max_role on
   Update-PfbApiClient) — a persisted flag would make this automatic going forward.

Group B — surfaced and deferred during the #31 session

5. .EXAMPLE block rewrite-vs-append pattern. The plan's Global Constraint 12 said to keep
   existing .EXAMPLE blocks and add new ones, but several implementers rewrote examples in
   place instead. Quantified by the whole-branch review: 25 of the 56 converted cmdlets lost 34
   -Attributes example blocks total (1 file lost 3, 7 lost 2, 17 lost 1). Two files have zero
   -Attributes examples left: Update-PfbLifecycleRule.ps1, New-PfbLegalHoldEntity.ps1 —
   prioritize those two if this only gets partially fixed.

6. Two test-coverage gaps (code is correct, only coverage is missing):

   • Tests/Update-PfbLag.Tests.ps1 covers -Ports @() but not -AddPorts @()/-RemovePorts @().
   • Tests/Update-PfbLifecycleRule.Tests.ps1 covers two integer fields with an explicit 0 test
     but not -KeepCurrentVersionFor/-KeepCurrentVersionUntil/-KeepPreviousVersionFor.

7. Dispatch-idiom drift. Public/Replication/New-PfbArrayConnection.ps1 and
   Public/Network/Update-PfbDns.ps1 use $PSCmdlet.ParameterSetName -eq 'Attributes' instead of
   Global Constraint 4's mandated -like '*Attributes'. Harmless today (neither cmdlet has a
   selector-axis parameter set to multiply against), but will silently stop working the moment
   either cmdlet gains one. The other 39 split cmdlets in this plan use the correct idiom.

8. Two pre-existing dead query keys (not introduced by Write cmdlets silently drop documented body parameters (~48 New-*/Update-* cmdlets) #31; found via the live-testing sweep
   and the whole-branch review's wire-key audit) — tracked separately given the unfiltered-write
   risk on one of them: see Pre-existing dead query keys on Update-PfbArrayConnection and Update-PfbAsyncLog (unfiltered-PATCH risk on the former) #64 (Update-PfbArrayConnection's dead -Name query key, plus
   Update-PfbAsyncLog's dead names/ids query keys).

9. Two unresolved API-behavior puzzles from live-testing against FB-A (cmdlet-level puzzles,
   not confirmed defects — worth a fresh investigation rather than further guessing, since
   several plausible fixes were already tried and rejected by the array):

   • New-PfbLegalHoldEntity -Names <holdname> -FileSystemNames <fsname> fails with "Names query
     parameter is missing" even though -Names was supplied. Tried once, not chased further.
     Needs a raw curl/Invoke-RestMethod probe against POST /legal-holds/held-entities before
     touching the cmdlet, to isolate cmdlet bug vs. documentation/understanding gap.
   • Update-PfbObjectStoreAccountExport fails with "Object store account export identifier is
     required" regardless of -Name format tried (bare name, account/name compound) or
     -Attributes shape supplied. Three attempts made this session, all rejected. Needs the same
     raw-probe treatment before assuming anything about the cmdlet's own code.

10. Stale, superseded local branch fix/fleet-member-wire-contract (tip 663c771,
    2026-07-23) — not an ancestor of the merged Write cmdlets silently drop documented body parameters (~48 New-*/Update-* cmdlets) #31 branch, and diverges in design from what
    shipped (New-PfbFleetMember on Write cmdlets silently drop documented body parameters (~48 New-*/Update-* cmdlets) #31 exposes -FleetName/-FleetId + -Members [hashtable[]]; the old branch exposed -FleetName + -FleetKey instead). The Write cmdlets silently drop documented body parameters (~48 New-*/Update-* cmdlets) #31 shape is
    spec-correct (POST /fleets/members takes { members: [ { key, member } ] }). Recommend
    closing/deleting the old branch rather than ever merging it.

11. Older deferred audit items, carried forward from before Write cmdlets silently drop documented body parameters (~48 New-*/Update-* cmdlets) #31's Tasks 2–10 even started
    (out of scope for a correctness pass):

    • M5: -Locked $null on Update-PfbAdmin sends a literal JSON null to the array rather
      than omitting the key or rejecting the input. Not necessarily a bug, but worth an explicit
      decision on intended behavior.
    • M7: New-PfbApiToken -Timeout supplied alone (no -Name/-Id) is unusable due to a
      pre-existing parameter-set ambiguity — predates this plan.
    • M9: piecemeal Everpure rebrand — at least 37 files under Public/Admin/ alone still say
      "Pure Storage" in header comments even where the same file's .DESCRIPTION already says
      "Everpure" a few lines below (self-contradictory). Repo-wide pre-existing condition, not
      something Write cmdlets silently drop documented body parameters (~48 New-*/Update-* cmdlets) #31 introduced or was meant to fix — scope as "worth a dedicated rebrand pass."

References

• Related: API drift report: systemicGaps/conventionStrength only aggregate over high-confidence endpoints, undercounting some field names #59 (parser-gap AST resolver limitation referenced in item 3)
• Related: Pre-existing dead query keys on Update-PfbArrayConnection and Update-PfbAsyncLog (unfiltered-PATCH risk on the former) #64 (dead query keys on Update-PfbArrayConnection/Update-PfbAsyncLog, split out of
  item 8 above)