Promote local COG contract to stable (#2300)

[brendancol]

Summary

Closes #2300. Part of the #2286 production-readiness wave; siblings #2301 / #2302 / #2303 are in flight in parallel.

Flip the local COG read and write paths to the stable tier in xrspatial.geotiff.SUPPORTED_FEATURES, document the stable contract, and call out the combinations that stay outside it.

Changes

• xrspatial/geotiff/_attrs.py:
  • SUPPORTED_FEATURES['writer.cog']: advanced -> stable.
  • SUPPORTED_FEATURES['reader.local_cog']: advanced -> stable.
  • SUPPORTED_FEATURES['reader.http_cog'] stays advanced; the per-key comment now spells out why (range fetching, redirect handling, SSRF / private-host filter, cache / retry policy not yet contracted at the stable bar).
  • The block comment above SUPPORTED_FEATURES carries the full stable-contract bullet list and the out-of-scope list.
• docs/source/reference/geotiff.rst: new Stable COG contract section at the top of the page (positioned at the top so the sibling rio-cogeo / GDAL validate_cloud_optimized_geotiff as required CI gate (#2286 prod-ready wave C) #2302 CI-validator note can land elsewhere) plus Outside the stable contract sub-section.
• examples/user_guide/52_COG_Overview_Generation.ipynb: short stable-contract note inserted after the intro. The notebook's existing examples all sit inside the contract; cautious phrasing kept for HTTP COG and the out-of-scope combos.
• CHANGELOG.md: Unreleased entry pointing at the writer compliance suite (COG readiness: external compliance test suite for to_geotiff(cog=True) (#2286 PR 2/6) #2292), the parity gate (COG readiness: HTTP/range byte-budget contract tests (#2286 PR 3/6) #2293), and the byte-budget contract (COG readiness: add COG rows to backend parity/release gate (#2286 PR 4/6) #2294 / Pin HTTP/range COG byte-budget contract (#2293) #2298) that back the promotion.

Scope notes

• Does not touch _writer.py, CI workflows, or BigTIFF code.
• Does not promote reader.http_cog.
• Stays away from the end of the SUPPORTED_FEATURES dict so sibling BigTIFF COG external compliance + tier decision (#2286 prod-ready wave D) #2303 can append writer.bigtiff_cog cleanly.

Test plan

• pytest xrspatial/geotiff/tests/ -- 5169 passed, 69 skipped.
• pytest xrspatial/geotiff/tests/test_supported_features_tiers_2137.py -- the tier-shape test still passes against the new stable values.
• CI green on the PR.
• Docs build picks up the new section (RTD check).

[brendancol]

Self-review

Read-only docs-and-metadata PR; no production code paths change behaviour. The review covers the tier flip, the two doc surfaces, the notebook cell, and the changelog entry.

Blockers (must fix before merge)

None.

Suggestions (should fix, not blocking)

• examples/user_guide/52_COG_Overview_Generation.ipynb -- the inserted markdown cell has no id field. The rest of the notebook's cells also have no ids (the project leaves them off), so this stays consistent, but the note here is to flag the choice so a future reviewer doesn't mistake it for an oversight.
• docs/source/reference/geotiff.rst -- the "Outside the stable contract" sub-section uses --------------------------- underline length matching "Outside the stable contract" (27 chars). Sphinx requires the underline to be at least as long as the title; 27 == 27 is the minimum legal length. Counted by hand, but worth eyeballing in the next docs build.

Nits (optional improvements)

• xrspatial/geotiff/_attrs.py:262-273 -- the per-key comments above reader.local_cog and reader.http_cog repeat material from the block comment above SUPPORTED_FEATURES. The repetition is deliberate (the block carries the contract, the per-key comments explain why this key landed in this tier), but if someone wants to slim down later the per-key reader comment could shorten by half.
• CHANGELOG.md -- the entry is a single 700-char run-on. Matches the style of the other Unreleased entries (e.g. #2277, #2276, #2016) so I left it alone, but if the project ever wants to break long entries onto sub-bullets this would be a candidate.

What looks good

• Tier flip is isolated to two string values; the surrounding SUPPORTED_FEATURES dict shape, the iteration order, and the derived _EXPERIMENTAL_CODECS set are unaffected.
• reader.http_cog stays advanced per the issue acceptance, with a documented reason in the per-key comment.
• No runtime code reads SUPPORTED_FEATURES['writer.cog'] or ['reader.local_cog'] for gating, so the tier change cannot regress runtime behaviour. Confirmed by grep -rn "SUPPORTED_FEATURES\[" xrspatial/geotiff/ --include="*.py" | grep -v tests returning nothing.
• The _attrs.py block comment and the geotiff.rst "Stable COG contract" section carry the same bullet list; if the contract changes in a follow-up, both surfaces need to be edited (acceptable cost; the alternative is one canonical surface with a cross-reference, but Sphinx can't pull from a Python comment).
• The 39_GeoTIFF_IO notebook's stability table is built dynamically from SUPPORTED_FEATURES, so it picks up the new stable values without a manual edit.
• Stays away from the end of SUPPORTED_FEATURES so sibling BigTIFF COG external compliance + tier decision (#2286 prod-ready wave D) #2303 can append writer.bigtiff_cog cleanly. Stays away from _writer.py and CI workflow files per the conflict-avoidance plan.

Tests

• pytest xrspatial/geotiff/tests/ -- 5169 passed, 69 skipped locally.
• test_supported_features_tiers_2137.py walks the dict and asserts every key has a valid tier; the new stable values pass.

Checklist

• Algorithm matches reference / spec (the stable contract bullet list matches the Promote local COG contract to stable: flip tiers, document the contract, release notes (#2286 prod-ready wave A) #2300 issue body verbatim apart from light wording around "byte-for-byte" vs "round-trip")
• No NaN / edge-case concerns (docs / metadata only)
• No dask / GPU concerns (no kernel changes)
• No premature materialization (no compute changes)
• Test suite green locally
• Notebook prose updated
• Reference docs section added
• Release notes entry present