fix(contract): pin the baseline to the snapshot's platform commit

[saurabhjain1592]

Summary

Closes #251.

Without --sha, scripts/refresh_wire_shape_baseline.py fell back to git rev-parse HEAD of the specs directory. The spec snapshot lives inside this repository, so that recorded the SDK's own commit as openapi_specs_sha, and the script exited 0. Nothing downstream could tell: the pin guard compares the baseline's SHA with the base branch's, and no test compared it with the snapshot.

Every snapshot file already names the platform commit it was derived at, in its generated header. The refresh now reads the commit from there.

Changes

• scripts/snapshot_openapi_schemas.py
  • snapshot_commit(dir) reads line 2 of every *.yaml, # Source: docs/api/<file> at platform commit <SHA>, and returns the commit they all name.
    • It returns None for a directory with no generated file, such as a platform checkout's docs/api.
    • It raises for a header that lacks its source line, names another file, or names an abbreviated commit, and for files that name different commits.
  • --check-snapshot enforces the same agreement.
  • Deriving now refuses an abbreviated --source-commit, so the script cannot write a snapshot its own reader refuses. Every header names a full 40-character commit.
  • The self-test gains three checks: the commit is read back, files naming different commits are refused, and an abbreviated commit is refused.
• scripts/refresh_wire_shape_baseline.py
  • resolve_specs_sha takes the commit from the snapshot's headers and refuses a --sha that contradicts them.
  • A directory that is not a generated snapshot names no commit, so it still needs --sha.
  • The git rev-parse HEAD fallback is deleted.
• Tests
  • tests/test_snapshot_openapi_schemas.py pins the headers' commit to the baseline's openapi_specs_sha. It also covers snapshots whose files name different commits, a header naming another file, an abbreviated commit on both the derive side and the read side, and a plain specs directory.
  • tests/test_refresh_wire_shape_baseline.py covers the resolution: the snapshot's commit is read, a contradicting --sha is refused before anything is written, and a plain directory must name its commit.
• Docs
  • CONTRIBUTING.md now runs the contract and the refresh against the committed snapshot. It had them cloning the mirror and relying on its HEAD.
  • Its pin-bump flow now re-derives the snapshot.
  • The snapshot README drops "always pass --sha".

No SDK code, no openapi_specs_sha and no snapshot *.yaml changes, so there is no CHANGELOG entry: this is contract tooling only, as in #249 and #250. It does carry the spec-pin-bump label, because the snapshot README lives under tests/fixtures/openapi/ and the pin guard treats any change there as a change to the pin. The guard's own log on this PR reads openapi_specs_sha 36e0e96b7e5c16626d394272b727b533f2b94a04 -> 36e0e96b7e5c16626d394272b727b533f2b94a04; snapshot changed: true: the pin is unchanged, and the only file changed under that directory is README.md.

The snapshot script is vendored byte-identical into the other SDKs, and each takes this change in its own pull request: TypeScript under getaxonflow/axonflow-sdk-typescript#278, and Go and Java in their spec-pin pull requests.

Testing

• The scenario from Wire-shape refresh without --sha pins the SDK's own commit #251, on this branch.
  • python scripts/refresh_wire_shape_baseline.py tests/fixtures/openapi with no --sha exits 0. It rewrites tests/fixtures/wire_shape_baseline.json byte-identical to the committed one, reporting openapi_specs_sha 36e0e96b7e5c16626d394272b727b533f2b94a04, 107 registered models and 22 drift entries.
  • With --sha 0000000000000000000000000000000000000000, it exits 2 with error: --sha 0000000000000000000000000000000000000000 disagrees with tests/fixtures/openapi, whose generated headers name platform commit 36e0e96b7e5c16626d394272b727b533f2b94a04, and the tree is unchanged.
• Mutation. Each guard was removed in turn, in its own file, and restored from the commit afterwards; the tree was clean after each. Every mutant turned the new tests red:
  • snapshot_commit accepting files that name different commits;
  • snapshot_commit accepting a header that names another file;
  • --check-snapshot no longer enforcing one commit;
  • an abbreviated commit being accepted;
  • the refresh accepting a contradicting --sha;
  • the refresh accepting a plain directory without --sha;
  • the baseline pinned to a commit the snapshot does not name.
• The full suite: 1548 passed, 30 skipped, coverage 85.17%.
• Gates: ruff check ., ruff format --check ., --self-test (now 12 checks) and --check-snapshot tests/fixtures/openapi all pass, each checked on its own exit code.