Repository navigation
contextScope has no version dimension #112
Description
Activity
Closing this as the recorded decision it is, now that the decision has a tripwire behind it rather
than only an argument.PR #131 adds one, test-only. It does not add the version dimension described above — that
omission stands exactly as recorded, and the reasoning for it is unchanged. What changes is that the
premise it rests on is now checked on every CI run instead of resting on an argument nobody
re-examines.Four assertions over every cached spec version:
Assertion Fires when ValueChangean endpoint declares a different scope in a later version KindGainedearlier tokens survive and a new one joins them ( FLEET→FLEET|REALM)Withdrawna later spec still has the operation but drops its override vocabulary any spec declares a domain token outside ARRAY/FLEETThe last one is the one most likely to fire first, and the reason it is separate: it needs a single
version to declare an unfamiliar token, not two versions to disagree. It also covers the case this
issue does not discuss — an endpoint becoming addressable by a new kind of context, a realm or a
topology group, rather than changing between the two we already know.Build-PfbCapabilityMap.ps1
sends an unrecognised token toscope: unknown, andunknownsuppresses the kind-vs-scope gate
entirely, so a new domain would not fail loudly — it would quietly stop validating those endpoints.
Set-PfbContext -Kindalready acceptsTopologyGroupwith no spec vocabulary behind it, so the
client half of that gap exists today.Two limits, on the record so a later reader does not over-read the green:
- The cross-version assertions are vacuously true right now. All five endpoints that declare a
domains override are the/presets/workloadverbs, and all five declare only in fb2.28 — so there
are no cross-version pairs to compare at all. Only the vocabulary assertion has live data behind
it. The comparison logic is therefore proven separately against synthetic declarations, because a
tripwire nobody has seen trip is indistinguishable from one that cannot. - The seam between the spec scan and the comparison is guarded by a positive control, not by an
end-to-end mutation. The scan must report more than 500 endpoints and at least one declaration
before any "no findings" result is believed — an empty walk is inconclusive, never negative.
The reopen trigger this issue asks for is now mechanical: the tripwire's failure messages name #112
directly. If it fires, reopen this rather than widening the expectation to make it pass.- The cross-version assertions are vacuously true right now. All five endpoints that declare a
- added a commit that references this issue
on Aug 20, 2026
Every other version-sensitive fact in
Data/PfbCapabilityMap.jsonis recorded per REST version.parameterscarries a version floor per parameter, which is what letsAssert-PfbApiCapabilitysay"this endpoint gained
context_namesat 2.17" and refuse it below that.contextScopeis a singlevalue per endpoint, computed last-seen-wins across the whole 2.0–2.28 spec set.
The justification is sound and should be kept in view before anyone "fixes" this. A resource does
not migrate between the fleet database and an individual array, so scope is a property of the
resource rather than of the API version, and the fb2.28 annotations describe 2.23-era endpoints
accurately. Last-seen-wins is correct here in a way it is explicitly not correct for parameter
component identity, which the map does version.
The gap is expressiveness rather than correctness: if a scope ever did change across versions, the
map has no way to represent it. The generator would silently record the newest reading, the runtime
gates would apply it to an array running an older REST version, and no test could detect the
difference — the drift suite compares the shipped artifact against generator output, and both sides
would agree.
Ask: no code change proposed. Recording this so the omission is visibly a decision rather than
an oversight, and so the next person to touch
schemaVersionknows that adding a version dimensionto
contextScopewas considered and deliberately skipped. If a scope change is ever observedupstream, this is the issue to reopen.