Capability map records no body fields for array-bodied endpoints (schema walk never descends through items) #82

Summary

The capability map's schema walk never descends through an array schema's items, so
every array-bodied endpoint records "bodyProperties": {}. Four endpoints are affected
and 23 body fields are invisible to both the runtime capability gate and the drift report.

Unlike #71 (which records fields with a wrong introducedVersion), these fields are
recorded not at all, and the defect reproduces on the current spec rather than
self-healing at 2.17.

Affected endpoints

All four array-bodied operations in fb2.28, all with bodyProperties: {}:

The fields exist in the spec, one hop below where the walk stops:

NodePost              capacity, chassis_serial_number, data_addresses, details, id,
                      management_address, name, node_key, raw_capacity, serial_number,
                      status, unique
ResourceAccessPost    resource, scope
TagBatch              copyable, key, namespace, resource, value
FleetMemberBatchPost  authentication_credentials, ca_certificate, ca_certificate_group,
                      management_address

Root cause

Add-PfbSchemaPropertyNodes in tools/lib/PfbSpecTools.ps1 — the recursive helper behind
Get-PfbSchemaPropertyNames/Get-PfbSchemaPropertyDetails — has branches for $ref
(via Resolve-PfbRef), allOf, properties and required. It has no branch for
items, and none for oneOf/anyOf.

The request body for PUT /workloads/tags/batch in fb2.28:

{ "maxItems": 30, "minItems": 1, "uniqueItems": true,
  "type": "array",
  "items": { "$ref": "#/components/schemas/TagBatch" } }

Resolve-PfbRef returns that array node unchanged. It has no properties key and no
allOf, so the accumulator adds nothing and the walk terminates. NodePost is
additionally allOf [Node, {node_key}], so it needs the existing allOf handling to run
after the items hop — the two compose.

Why it is easy to miss

"bodyProperties": {} is indistinguishable from "this endpoint legitimately has no body
fields." Nothing warns, nothing logs, and no test fails. There is no error state to
notice — only an absence that reads as a valid answer.

Runtime impact

Private/Assert-PfbApiCapability.ps1 reads bodyProperties to version-gate body fields.
For these four endpoints the map is empty, so no field-level gate can fire — a caller
supplying a field that requires a newer REST version gets an opaque wire error instead of
the local, actionable message every other endpoint produces.

This is why PR #81, which taught Assert-PfbApiCapability to accept array bodies at all,
deliberately guards the field loop on -is [System.Collections.IDictionary] rather than
validating the union of element field names: against an empty map such a check could never
fire, and a gate that cannot fire is worse than none, because it looks like coverage.
Endpoint minVersion and query-parameter gating do run for these endpoints today; only
field-level gating is missing.

Reporting impact

The drift report's addable-body-parameter axis reads bodyProperties, so these four
endpoints contribute zero addable fields and cannot appear as gaps.

That lands directly on #44 (batch-operation cmdlets for nodes, resource-accesses,
workload-tags and fleet-members) — the drift report cannot inform the design of precisely
the cmdlets #44 proposes. Set-PfbWorkloadTag already ships with a free-form
[hashtable[]]$Tags, and nothing in the tooling can tell a user that namespace,
copyable or resource are the valid keys.

readOnlyBodyProperties is null for all four. NodePost carries obviously read-only
members (id, status, capacity, raw_capacity), so that field should populate too
once the walk descends — worth asserting explicitly rather than assuming.

Suggested fix

Add an items branch to Add-PfbSchemaPropertyNodes that resolves the element schema and
recurses into it with the existing accumulator, so allOf composition inside the element
continues to work. Then rebuild Data/PfbCapabilityMap.json and diff.

Expected diff: four endpoints gain populated bodyProperties (23 fields total, each with
an introducedVersion derived per the normal first-sight rule), plus whatever
readOnlyBodyProperties resolves to. Nothing else should move.

Two constraints on the fix:

1. Depth budget. Descending through items consumes a level, and Capability map records 5 body fields with introducedVersion one release too late (MaxDepth=8 truncation in fb2.12-2.16) #71 is already about
   the walk running out of depth on the fb2.12–2.16 allOf chains. Capability map records 5 body fields with introducedVersion one release too late (MaxDepth=8 truncation in fb2.12-2.16) #71's suggested fix
   (an explicit -MaxDepth 32 at the Get-PfbSpecCapabilities call sites) supplies the
   headroom this needs. See the sequencing note in the tracking issue.

2. The "nothing vanishes" invariant. Tests/Build-PfbApiDriftReport.Tests.ps1 asserts
   that every field the map lists for an endpoint an existing cmdlet calls lands in
   exactly one of the report's addable / read-only buckets or the phantom-exclusion set.
   Newly-populated fields must be accounted for there in the same change, or that test
   goes red. No child issue on the map carries this requirement, so it is easy to trip.

A regression test wants a synthetic fixture whose request body is an array of an
allOf-composed element schema, asserting the element's fields are found — a fixture that
fails today.

Relationship to #71

Same function, different keyword, and neither fix subsumes the other:

Raising MaxDepth does nothing for this; adding items does nothing for #71. They share a
call site, a data file and a verification burden, so they are worth landing together — see
the tracking issue.

Out of scope

The array-level constraints on the same schemas (minItems, maxItems, uniqueItems)
are a separate gap requiring a new map field rather than a walker fix. Filed separately.