feat(fusion): Phase 0 prerequisites - contextScope in the capability map, centralised component resolution, staleness warning

[juemerson-at-purestorage]

Phase 0 of the Fusion context_names work (#25, design spec rev 3 in #72). Prerequisites
only — nothing in this PR injects a context or changes any request on the wire. It
populates the data and centralises the contracts that Phase 1's injection path needs.

Closes the contextScope half of #25's Phase 0 scope. Sequencing agreed in
#84.

What shipped

18 files across 15 commits (3 docs, 10 code, 2 from the whole-branch review).

Task	Deliverable
1	Resolve-PfbParameterComponent — the single runtime home of the three-step component-resolution contract (Private/Resolve-PfbParameterComponent.ps1, Private/PfbContextConstants.ps1)
2	tools/lib consumes that Private/ resolver instead of inlining its own copy
3	Get-PfbSpecContextScope — reads the three x-pure-* remote-execution annotations
4	Per-endpoint contextScope emitted; capability map schemaVersion 1 → 2
5	Drift guard on the curated contextScope table
6	Connect-PfbArray warns once when the array outruns the bundled capability map
7	Top-level MemberName/FleetName on Get-PfbFleetMember

Five new test files, two modified.

The regenerated artifact

SHA-256       2E59D07D49B70A7CE90CBA2C6D5C243A6FECA199B4CE7E1C800DFEC4AA56A875
schemaVersion 2      versions 29      endpoints 632
provenance    default 604 | unknown 19 | declared 5 | live-tested 4
scope         array 606   | unknown 19 | fleet 7

Both distributions sum to 632. The full cross-tab:

scope	provenance	count
array	default	604
array	declared	1
array	live-tested	1
fleet	declared	4
fleet	live-tested	3
unknown	unknown	19

A contextScope of unknown is a designed degradation, not a gap. It suppresses
validation and leaves today's behaviour intact, so Phase 1 degrades rather than breaks.
Adding an entry later is a generator-table edit plus a regenerate — deliberately cheap.

Two things about the data worth not generalising

The /presets/workload read/write asymmetry is intentional. GET is array-scoped;
all four write verbs on the same path are fleet-scoped. Both sides are declared
provenance — curated deliberately, each individually evidenced. This is not a
"reads array, writes fleet" verb rule. That rule was proposed, tested against the wire,
and falsified in #73. It should not be reintroduced.

Every /fleets/* endpoint takes array/default. That is correct: scope describes
remote-execution context, not resource family, and fleet membership is array-local. The 7
fleet-scoped entries are the 4 /presets/workload writes plus the 3 /topology-groups*
reads.

Review history

Two rounds. Eight substantive issues found, all fixed and each mutation-verified. No
correctness defect survives in shipped code and there is no 5.1 compatibility break.

Folded below rather than cut: the round-1 findings existed only in conversation context
that has since been compacted, so this PR body is now their only durable home.

Round 1 — five defects found during per-task review

None of these were caught by the original testing.

#	Finding	Fixed in
1	Component keys resolved on PSCustomObject only. The generator builds [ordered]@{} in memory, and on an IDictionary .PSObject.Properties.Name returns the CLR surface (Keys, Count, …) — not the keys — so resolution silently missed every in-memory lookup	b5bd095
2	Four wrong resolver implementations survived mutation — the tests did not pin the contract. Killed by adding multi-key overrides (the real map has 40 such objects, 18 carrying context_names) and an ids/ids_or_names decoy	b5bd095
3	Zero last-seen-wins coverage. contextScope is assigned unconditionally per spec iteration while minVersion/parameters/bodyProperties use a first-sight guard three lines away. The fixture was a single spec version — precisely what cannot demonstrate non-version-gating	4241778
4	Fixture inverted reality on declared-vs-flagged precedence	4241778
5	The total_item_count sentinel was decorated into a nameless member, producing an object that looks like a fleet member whose name is $null — the exact silent-wrong-binding failure the decoration exists to prevent	dd6041a

Task 6's review changed the design

25 mutations, 21 killed. The question was whether an unguarded version parse in the warning
branch could break connecting. It could not — that line was a byte-for-byte replay of the
helper's own expression, so a $true return was itself proof the expression had succeeded.

But that safety rested on an invariant in a different file, with nothing at the call
site saying so. One mutation proved it fragile: making the helper's catch return $true
sent the call site throwing outside any try, and no connection was returned. Given the
asymmetry — the warning is worth little, a broken connect costs everything — the duplicate
parse was removed and the helper now returns the maximum via a [ref] out-param. That
mutation now degrades to a spurious warning.

Three survivors were genuine test gaps, all closed: a swapped-version warning
("running REST 2.28 … covers through REST 2.29" — backwards and actively misleading)
passed all 11 tests because each version was only asserted to appear somewhere; an
excluded property could be added to $defaultProps undetected; and a Find-Module source
grep was brittle in exactly the way it had been claimed strong — it trips on a harmless
comment and missed 3 of the 5 files in the call graph. Replaced with an AST walk over
invoked command names.

Round 2 — whole-branch review across all 13 commits (three findings)

Three gaps, all fixed in 6ae04e8 and 4f07080:

• A test was withholding 9 assertions from Windows PowerShell 5.1 for no reason of its
  own. Tests/PfbSpecTools.ContextScope.Tests.ps1's synthetic Describe carried an
  edition skip, but Get-PfbSpecContextScope is a pure PSObject walk with no pwsh-7
  dependency — the only 5.1 blocker was the fixtures' own ConvertFrom-Json -Depth 32,
  and those fixtures are four levels deep. Dropped -Depth, removed the skip; the block
  now runs on both editions. The sibling Describe keeps its guard, which is genuine
  (the real fb2.28 spec does need -Depth 64), and now states why. This matters because
  on 5.1 the file reported 0 passed for that block — indistinguishable from health.
• One more surviving mutation, now killed. IsIncompleteGre/BlocksRemoteExec test
  key presence and value, but all 304 occurrences of those extensions across the 29
  cached specs are literal true, so a presence-only implementation passed everything.
  An endpoint upstream deliberately un-flagged would have been forced to
  unknown/unknown silently. Now pinned, and the mutation fails on both editions.
• tools/README.md, the tracked contract doc for the map's shape, was stale. It did
  not mention contextScope or schemaVersion 2, and its parameter-component resolution
  prose was the one remaining copy of that contract not pointing at
  Private/Resolve-PfbParameterComponent.ps1 — the prose form of exactly the drift Move context_names component resolution from tools/lib into Private/ before the Fusion injection path is built #74
  exists to close.

Five mutations were run with hash-verified application and restore plus dual-edition
parse checks. Four were killed by existing tests: first-sight-wins substituted for
last-seen-wins on contextScope; min-scanned substituted for max in the staleness helper;
and the total_item_count sentinel guard neutralised. The three load-bearing behaviours
are each genuinely defended by a test that dies when you break it.

Verification

Live, against FB-A (REST 2.26 / Purity//FB 4.8.2). 7 ledger rows for
Get-PfbFleetMember, all at feat/fusion-context-phase-0@33fbd32, 185–1217ms.

• Unfiltered: 3 members, stable over 3 repeats. Decoration correct on all rows; nested
  member/fleet preserved.
• -MemberName 'FB-A' → exactly 1 row, decorated, 208ms. Never → 0.
• Bogus name → HTTP 400 "Fleet member does not exist." A specific rejection is
  positive evidence the key was parsed and acted on; an empty set would prove nothing.
• Control against main: identical filter counts, and PropertyNotFoundException on
  MemberName for every row. Property absent before, present after, same array, same
  call. This is the strongest single piece of evidence for Task 7.

Task 6 negative case: connect produced 0 warnings, and the silence is provably correct
rather than accidental — the shipped map's max is 2.28, so 2.26 is in range. Helper
verdicts against the real artifact: 2.26→False, 2.28→False (exact match must not warn),
2.29→True/2.28, 3.0→True/2.28, unparseable→False with HighestScanned untouched.

Tests. All seven of the branch's test files, scoped run, both editions:
pwsh 7 108 passed / 0 failed / 0 skipped; Windows PowerShell 5.1
48 / 0 / 60. Container ok on both. (The 60 skips on 5.1 are the tools/Build-*
suites, which carry a deliberate edition guard.)

One pre-existing failure you will hit locally, which this branch does not cause.
With real specs present, Tests/Build-PfbApiDriftReport.Tests.ps1 fails one assertion on
pwsh 7 — the "nothing vanishes" invariant, on
POST /file-system-replica-links|query|remote_default_exports. This was verified as
pre-existing by exporting the merge base with git archive into a clean tree with the same
29 specs and reproducing the identical 1757-vs-1756 result. Structurally confirmed too:
parsing both capability maps and comparing endpoints with contextScope stripped gives
byte-identical output. Reports/PfbApiDriftReport.json on main is one gap stale and has
been since before this branch — it is #84 PR 1's to fix, and is deliberately untouched here
(see limit 6).

Limits — please read these before reviewing the artifact

Stated plainly rather than buried, because overstating any of them is the specific way
this PR could mislead.

1. The drift guard gives ZERO CI protection. tools/specs/ is gitignored, and
   cross-platform-tests.yml — the only PR-triggered workflow — never fetches it, so every
   real-artifact assertion skips. Locally "7 passed" and in CI "7 skipped" look identical in
   a summary line. It is a maintainer gate only.
2. The artifact diff review is the actual verification for contextScope, not the live
   check. Do not overstate the live item.
3. Task 6's positive case is not lab-reachable. FB-A caps at 2.26, below the 2.29 needed
   to fire the warning. Verified at helper level against the real map, not on the wire.
4. Task 6 has no ledger row. Hand-connect plus helper probe. Sound, but weaker in kind
   than Task 7's evidence, not merely narrower.
5. The total_item_count guard is unreachable from this cmdlet — Get-PfbFleetMember
   has no TotalOnly parameter. Purely defensive, resting on its unit test.
6. Reports/ drift-report delta is pre-existing on main, established by reverting
   tools/lib/PfbContextRuleTools.ps1 to HEAD and re-running (identical 64/1), and confirmed
   independently. contextScope provably does not reach drift accounting: reports generated
   from the before- and after-maps are byte-identical, contextScope string count 0 in both.
7. 3 of the 4 curated contextScope entries are not live-checkable — no topology-group
   cmdlets exist on this branch.

Restating limit 2, because it is the one that matters for reviewing this PR: the
Data/PfbCapabilityMap.json diff is the verification for contextScope. There is no CI
gate comparing the committed artifact to what the generator produces (limit 1), and the live
check covers Task 7, not the map. Reading that diff is the review.

Sequencing — this is the first of two consecutive map regenerations

Data/PfbCapabilityMap.json will be regenerated again, immediately, by #84's PR 1
(the #71/#82 schema-walk fix). That is deliberate and agreed in
#84 — not
churn, and not someone undoing this work.

The order is Phase 0 first because its verification is the artifact diff (limit 2), which
only holds against an unmoved base. PR 1's verification is unit fixtures plus a diff
characterised in advance, which survives being re-derived on a moved base.

schemaVersion 1 → 2 is claimed here. PR 1 does not contest it; #83 will increment from
whatever it finds.

Deliberately not in this PR

• No Reports/ changes, and no claim to fix the 64/1 drift-report red. That belongs to
  PR 1, which owns the whole Reports/ diff.
• No version bump, no CHANGELOG.md. Maintainer's call.
• No fix for the CI gap in limit 1 — deferred until after Phase 0.
• Nothing reads contextScope at runtime yet. Kind-vs-scope validation and scope-aware
  error messages are Phase 1, which is the field's first consumer.

What this unblocks

Phase	Work
1	The PfbContext object, connection context state, and the injection path — needs resolved component names to call the cardinality predicate at all
1	Kind-vs-scope validation and scope-aware error messages — the first runtime consumer of contextScope
1	Set-PfbContext pipeline binding — depends on Task 7's top-level MemberName/FleetName, because ValueFromPipelineByPropertyName matches top-level names only
2	allow_errors surfacing and the HTTP 207 branch — will need the same component resolution Task 1 centralised
#38	Topology-group and fleet/realm cmdlets — not blocked on this; measured, those writes succeed with no context_names from the coordinator