feat(scaffold): openapi:roundtrip drift gate (#164)

[tonydspaniard]

Closes #164. Closes epic #160.

Summary

Adds bin/altair openapi:roundtrip \xe2\x80\x94 a CI-friendly drift gate that exercises the full OpenAPI \xe2\x86\x92 Altair YAML \xe2\x86\x92 OpenAPI chain in memory and refuses to let an emitter / parser change silently degrade the round-trip. Same contract shape as spec:emit-sdk --check: human or JSON report; exit code 1 in --check mode on drift so a build can refuse to merge.

This is the last piece of #160 \xe2\x80\x94 with this in, the import path is safe to depend on.

What the gate compares

For every (method, path) operation:

• summary \xe2\x80\x94 exact string match.
• x-altair-domain / x-altair-persistence / x-altair-queue \xe2\x80\x94 the extensions from x-altair-* OpenAPI extensions \xe2\x80\x94 round-trippable persistence, queue, webhook, idempotency #163. Deep equality.
• Response status set \xe2\x80\x94 restricted to statuses that carry an application/json schema in the source.

Operations missing from either side are flagged as missing_operation / extra_operation.

What the gate intentionally ignores

Documented in docs/openapi/roundtrip.md so the contract is explicit:

• Key order, empty optional arrays, info block, doc-level tags \xe2\x80\x94 trivial drift, says nothing about semantic loss.
• components/schemas \xe2\x80\x94 refs resolve to inlined types in the spec and re-emit as inlined objects; schema-level comparison lands when the importer learns to preserve components.
• Description-only responses (204, 404, etc.) \xe2\x80\x94 Altair's output: block can't represent an empty body.
• Enriched extensions \xe2\x80\x94 a source without x-altair-domain that gets a synthesised one back is the importer working as intended, not a regression. Drift only fires on loss, not on enrichment.

JSON receipt

{
  \"clean\": false,
  \"input\": \"openapi.yaml\",
  \"operations_compared\": 5,
  \"differences\": [
    {
      \"kind\": \"extension_drift\",
      \"pointer\": \"#/paths/~1users/post/x-altair-persistence\",
      \"expected\": { \"entity\": { \"class\": \"App\\\\User\\\\User\", \"...\": \"...\" } },
      \"actual\": null,
      \"message\": \"'x-altair-persistence' present in source was lost or changed by the round-trip.\"
    }
  ],
  \"error\": null
}

kind is a stable enum: missing_operation, extra_operation, summary_drift, extension_drift, status_drift. Receipt is byte-stable for the same input (no timestamps / IDs) \xe2\x80\x94 golden-file-safe for CI.

Files

Layer	Files
Runner + CLI	src/Altair/Scaffold/Cli/{OpenApiRoundtripCommand,OpenApiRoundtripRunner,OpenApiRoundtripOptions,RoundtripReceipt,RoundtripDifference}.php
Docs	docs/openapi/roundtrip.md
Tests	tests/Scaffold/Cli/OpenApiRoundtripRunnerTest.php (9 tests)

Verified

• 5 operations from benchmarks/tokens-to-ship/fixtures/posts.openapi.yaml round-trip clean.

Test plan

• composer cs \xe2\x80\x94 green
• composer stan \xe2\x80\x94 green
• composer rector (full tree, no cache) \xe2\x80\x94 green
• composer test \xe2\x80\x94 6229 tests (+9 new), 0 new failures (5 pre-existing env errors unchanged)
• bin/altair manifest:generate \xe2\x80\x94 clean
• Real-CLI smoke: bin/altair openapi:roundtrip benchmarks/tokens-to-ship/fixtures/posts.openapi.yaml reports clean: 5 operation(s) round-tripped without drift

Future work flagged in the docs

• --strict flag for schema-level comparison once OpenApiParser learns parameters[] + components/schemas preservation.
• --fixtures=<dir> for batch round-trip over a fixtures directory (mentioned in openapi:roundtrip \xe2\x80\x94 drift gate for openapi \xe2\x86\x92 spec \xe2\x86\x92 openapi #164's original CLI surface; deferred since the single-file form covers the common case).

The single-file form is what CI configurations need; the batch form lands when there's a second consumer asking for it.