fix(tools): walk array item schemas and raise MaxDepth (#71, #82)

[juemerson-at-purestorage]

Two bugs in the same schema-walking helper in tools/lib/PfbSpecTools.ps1, landing together
because they interact. Fixes #71. Closes #82's map and reporting scope.

Targets the integration/capability-map-2026-08 branch, not main — see Sequencing below.

The two bugs

#71 — MaxDepth defaults to 8, truncating fb2.12–2.16 allOf chains. Five body fields
on PATCH /password-policies carried introducedVersion = 2.17 when the specs say 2.16.
Runtime-visible, not cosmetic: Assert-PfbApiCapability reads bodyProperties, so it would
wrongly refuse those five parameters against an array on REST 2.16. The 2.17 spec
restructuring flattened these chains, which is why the defect self-heals from 2.17 onward
and is invisible against current data.

#82 — the walk never descended an array body's items. Four array-bodied endpoints
recorded no usable bodyProperties, hiding 23 fields from both the runtime gate and the
drift report.

They compose: descending through items consumes a depth level, so #82 needs #71's
headroom. Raising MaxDepth alone does nothing for #82, and adding items alone does
nothing for #71.

Why the fix is at the call site, not in the walker

#82's obvious fix — teach Add-PfbSchemaPropertyNodes to descend items — would have
silently corrupted Data/PfbResponseShapeMap.json. That walker is shared with
Get-PfbSpecResponseShapes, whose entire contract is that an envelope's properties and its
items[] element's properties are two deliberately-separate levels. Teaching the walker
to descend unconditionally collapses them, and the response-shape map's cross-version removal
detection would start comparing incomparable sets, with nothing to warn.

So the items hop happens at the Get-PfbSpecCapabilities call site, matching the precedent
Get-PfbSpecResponseShapes already sets. Add-PfbSchemaPropertyNodes is untouched.

The guard that proves it: Data/PfbResponseShapeMap.json is byte-identical before and
after — 423de668a78356bad13b6d345bf9e834eca3438e7badf96577e78a5bbf93fef6. If that SHA had
moved, the fix leaked.

MaxDepth = 32 is not a guess: Get-PfbSpecResponseShapes already defaults to it, with a
comment documenting the same fb2.12–2.16 truncation measured there as 184 false removals at
depth 8 versus 7 true ones at 32.

The regenerated artifact — exactly seven endpoint records change

Group	Change
#71	5 × introducedVersion 2.17 → 2.16 on PATCH /password-policies (name, id, enabled, is_local, location)
#82	23 bodyProperties recovered: POST /nodes/batch +12, POST /resource-accesses/batch +2, PUT /workloads/tags/batch +5, POST /fleets/members/batch +4
#82	readOnlyBodyProperties on POST /nodes/batch resolves from empty to 8 fields: capacity, chassis_serial_number, data_addresses, details, id, raw_capacity, status, unique
—	2 order-only records, no value changes: PATCH /ssh-certificate-authority-policies (bodyProperties key order) and PATCH /file-systems (top-level key order — contextScope and readOnlyBodyProperties swap position)

Nothing else. One correction to how #82 was described: those four endpoints did not have
an empty bodyProperties. Each had exactly one entry keyed by the empty string — the
nameless artifact of a walk that reached the array node and could not descend it. That is
what the 23 real fields replace.

Verification of the artifact itself

Because there is no CI gate comparing the committed map against generator output
(cross-platform-tests.yml never fetches the gitignored tools/specs/), the artifact was
checked by construction rather than assumed:

• Deterministic. Three consecutive regenerations produced identical SHA-256.
• Attributable. Reverting tools/lib/PfbSpecTools.ps1 to the base and regenerating
  reproduces Data/PfbCapabilityMap.json byte-identical to the committed Phase-0
  artifact. So every change above is caused by this PR's code — none is drift, staleness,
  or nondeterminism. This also independently confirms the Phase-0 map is exactly what the
  generator produces.
• Phase 0 undisturbed. schemaVersion still 2, 632 endpoints, and the full
  contextScope cross-tab unchanged: array/default 604, array/declared 1,
  array/live-tested 1, fleet/declared 4, fleet/live-tested 3, unknown/unknown 19.

The Reports/ diff is two independent halves — split across two commits

Conflating them is how the pre-existing half gets mistaken for damage this PR caused, so they
are separated at the commit level and each is independently reviewable.

Commit 28c34f2 — pre-existing, not caused by this PR. Regenerates Reports/ with the
walker held at the base. Reports/PfbApiDriftReport.json on main was one gap stale, which
is why the "nothing vanishes" invariant in Tests/Build-PfbApiDriftReport.Tests.ps1 has been
red locally. Root cause: New-PfbFileSystemReplicaLink's [Nullable[bool]]$RemoteDefaultExports
goes through a conditional assignment the drift tracer cannot follow → confidence high →
partial → enrichment disabled → systemicGaps/conventionStrength 252 → 246. Not spec
staleness; analysedVersions is identical at 2.28.

This diff (271/19/14/5 lines across four files) is numerically identical to what
origin/automated/update-api-capability-map already holds — that workflow has failed at its
Open pull request step on every run since 2026-07-24, so main never received it.

Commit e0d9a2b — this PR's own effect. Only three files move:
Data/PfbCapabilityMap.json plus the drift-report pair. PUT /workloads/tags/batch gains 5
missingBodyProperties (copyable, key, namespace, resource, value); addable body
properties 422 → 427. Only one of the four batch endpoints appears, because
Set-PfbWorkloadTag is the only existing cmdlet calling any of them — the other three are
#44's scope. Reports/PfbFieldCmdletMap.json, Reports/PfbValueEnumMap.json and their .md
siblings do not move.

The .gitignore change

tools/ is removed from .gitignore. The rule was inert for already-tracked files,
which is why every tools/ file was committed despite it. Removing it stops new files
under tools/ being silently refused — confirmed during this work: git add on a tracked
tools/ file prints the ignore warning and exits non-zero while still staging the file,
which will short-circuit any && git commit chain.

Live verification — FB-A, REST 2.26

Seven ledger rows, every one stamped
gitRef = fix/issue-71-82-schema-walk-depth-arrays@e0d9a2b, so the code under test is this
branch and not main. Outcomes below are the harness's own outcome field.

Cmdlet	Endpoint	Outcome	What it establishes
New-PfbFileSystem	POST /file-systems	Pass (421 ms)	The body-property gate accepts a normal typed body against the regenerated map
Get-PfbFileSystem	GET /file-systems	Pass (276 ms)	Read-back provisioned = 1073741824 — the create really landed
Update-PfbFileSystem	PATCH /file-systems	Pass (271 ms)	The order-only record. Observed state change 1 GiB → 2 GiB (2147483648), so the key-order shuffle is inert at runtime
Set-PfbWorkloadTag	PUT /workloads/tags/batch	Fail, HTTP 400 (302 ms)	#82's one reachable endpoint — see below
Update-PfbFileSystem	PATCH /file-systems	Pass (322 ms)	Destroy, for cleanup
Remove-PfbFileSystem	DELETE /file-systems	Pass (290 ms)	Eradicate
Get-PfbFileSystem	GET /file-systems	Fail, HTTP 400 (228 ms)	Confirms eradication — "File system does not exist." No residue left

The Set-PfbWorkloadTag failure is the informative result, and it confirms rather than
contradicts the #95 claim below. The array answered HTTP 400: Workload does not exist. —
a rejection of the resource, not of a body field. The call therefore reached the wire and
was never gated client-side: Tags is [hashtable[]], it hits the -is [IDictionary]
guard, and the body-field loop is skipped before bodyProperties is consulted. The 23
recovered fields are inert at runtime today, exactly as stated below — this measures
that rather than asserting it.

PATCH /password-policies could not be live-tested at all, for a second reason on top of
the version ceiling: password-policies is on the harness family deny-list, so the call
returns Skipped-Policy ("write verb 'Update' is denied for family 'password-policies'")
and never reaches the array. Not routed around.

What this does NOT do — stated explicitly

• Capability map records no body fields for array-bodied endpoints (schema walk never descends through items) #82's runtime goal is not reachable from the map alone, and is not claimed here.
  Assert-PfbApiCapability's body-field loop is guarded on
  -is [System.Collections.IDictionary] (:102), and an array body arrives as
  [hashtable[]], so the loop is skipped before bodyProperties is ever consulted. Runtime
  field-gating for these endpoints is tracked in Assert-PfbApiCapability cannot field-gate array bodies: the IDictionary guard outlives its premise once #82 lands #95.
• Capability map records 5 body fields with introducedVersion one release too late (MaxDepth=8 truncation in fb2.12-2.16) #71's 2.16 gating is not live-verifiable, for two independent reasons — FB-A runs REST
  2.26, above the version where the defect is observable, and the endpoint's family is on
  the live-harness deny-list (measured above).
• Capability map records no body fields for array-bodied endpoints (schema walk never descends through items) #82's batch gating is not live-verifiable — the type guard above blocks it, and of the
  four endpoints only Set-PfbWorkloadTag reaches one. Probed anyway; the array rejected the
  resource, not the body, which is the positive evidence that the guard short-circuits first.
• Unblocks one of Batch-operation cmdlets (nodes, resource-accesses, workload-tags, fleet-members) #44's two listed consequences — the drift-report half. The runtime half
  is Assert-PfbApiCapability cannot field-gate array bodies: the IDictionary guard outlives its premise once #82 lands #95.
• No schemaVersion bump. Phase 0 claimed 2; this PR does not contest it. Capability map cannot record array-body cardinality constraints (minItems/maxItems/uniqueItems) — needs schemaVersion 2 #83 increments
  from whatever it finds.
• No version bump, no CHANGELOG.md.

Sequencing

This is the second of the two consecutive regenerations of Data/PfbCapabilityMap.json
agreed in #84.
Phase 0 (#96) went first and took schemaVersion 2; this PR rebased onto it and regenerated
once on the stable base.

Both are stacked on integration/capability-map-2026-08 so the combined state is built
and tested before anything reaches main, rather than the two changes meeting for the first
time after they have both landed. One final PR will bring the integration branch to main.