Sync the locked contract and add fleet membership methods (1.2.0)

[roncodes]

Summary

Syncs the locked contract to Postman 9b59bef (the merged fleetbase/postman#59) and adds the fleet membership endpoints from the Fleet-Ops public Fleet resource expansion.

This also unblocks the fleetbase.io API reference build, which currently fails on main: the docs generator requires a PHP example for every request in the collection, and the catalog was still the 220-request one.

The 21 new requests are not 21 new operations

Four are:

Method	Route
assignDriverToFleet	POST /fleets/:id/drivers/:driver
assignVehicleToFleet	POST /fleets/:id/vehicles/:vehicle
removeDriverFromFleet	DELETE /fleets/:id/drivers/:driver
removeVehicleFromFleet	DELETE /fleets/:id/vehicles/:vehicle

The other seventeen are scenarios on endpoints already covered: retry an assignment to show it is idempotent, create a driver without contact details to show those are optional, send an empty relationship to show it is ignored.

The generator minted a method per request, so regenerating naively would have published createOrderWithEmptyRelationships, removeDriverFromFleetAgain, expandVehicleScalar, and updateDriverUnchangedContact — and would have put createFleetDriver and deleteFleetDriver on FleetService while they post and delete against /drivers, purely because the requests live in the Fleets folder. The compatibility gates make a published name permanent, so that is not a cost that can be walked back.

contracts/sdk-variants.json records which requests are scenarios and which operation each exercises, with a rationale per entry. A scenario still appears in the manifest, still appears in the API reference, and is still driven by the contract suite — through the canonical method, which is the claim worth testing: the scenario is reachable with the API the SDK already offers.

The examples improve as a result. Expand a Vehicle now documents what a caller actually writes:

$result = $fleetbase->vehicles->retrieveVehicle(
    $vehicleId,
    ['with' => ['vendor', 'not_a_relation']]
);

Adding an entry to the variant map never removes an existing method; it only declines to mint a new one. The map is validated in both directions — a stale entry that names no request fails generation, as does a variant pointing at another variant.

Two contract-generation bugs

Both are reachable by any request that repeats a query key, and both were latent before this sync:

• normalizeParameters kept only the last value of a repeated parameter, so ?with[]=vendor&with[]=not_a_relation recorded a single with[] and silently dropped vendor. Repeats now collect into a list under the base name.
• The manifest recorded the full url including an inline query string while the fixture recorded the query separately, so such a request carried its query twice. The manifest now records the path alone — which is what the other 239 requests already did.

ApiExamplesTest pinned its expected count as a literal, which is how it came to disagree with the lock. It now reads expected_requests from contracts/contract-lock.json.

Validation

All run locally on this branch:

• composer lint — 158 files, no syntax errors
• composer format:check — 0 of 158 files need fixing
• phpstan (at --memory-limit=1G; the default 128M is not enough for this codebase) — no errors
• composer test:unit — 35 tests, 4244 assertions, all passing
• composer contract:check --require-complete — 241 requests, 241 mapped, 0 exceptions, 0 unmapped
• composer contract:generated — regenerates to exactly the committed artifacts
• composer api:compatibility — compatible with the 1.0.2, 1.0.3, and 1.1.0 baselines

Not run: the mutation score. The release checklist asks for it to be measured and recorded for the candidate before publication, and I left that line as a task rather than carrying forward the 1.1.2 figure.

Release

Version bumped to 1.2.0 — additive surface, no removals or renames. Merging this branch starts the release workflow and derives 1.2.0 from the branch name.

Coordinate with fleetbase/fleetbase.io#97, which consumes contracts/php-sdk-examples.json from this branch. Land this first so the documented methods exist in a published version.