feat(coverage): sdk-coverage.v1.json per-capability snapshot (#182)

[mikemcdougall]

Summary

Publishes compatibility/sdk-coverage.v1.json, this SDK's producer snapshot for honua-server's cross-product capability matrix (honua-server#2892 / #2893). Maps packages/honua-sdk + packages/honua-admin client source to the canonical, server-owned capability key vocabulary so honua-evidence's aggregate run can join this SDK's coverage against every other producer.

Changes

• scripts/gen_sdk_coverage.py: generator + CI gate. COVERAGE hand-curates 29 of the 110 canonical keys as covered or partial, built by reading packages/honua-sdk/packages/honua-admin source against every published key. Three checks run every time:
  1. Every key in COVERAGE is validated against the canonical key list (unknown key fails).
  2. Every entrypoints dotted path is resolved via importlib/getattr against the installed packages -- a renamed/removed class or method fails the gate. This is the real drift signal for "SDK release that changes coverage without snapshot update fails."
  3. The committed snapshot must match a fresh collect_snapshot() byte-for-byte.
• compatibility/sdk-coverage.v1.json: the generated snapshot (29 entries; 25 covered, 4 partial with a required stop-note each).
• compatibility/capability-keys.fixture.json: pinned, point-in-time offline copy of honua-server's key list, used only when HONUA_CAPABILITY_KEY_LIST_URL is unset (local/offline dev, and the unit test suite -- both stay network-free). CI always sets the env var to the live URL.
• docs/sdk-coverage.md (+ linked from docs/compatibility.md, added to mkdocs.yml nav): schema table, honesty rules, drift-protection explanation, key-list resolution order.
• .github/workflows/ci.yml: new steps in the compatibility job -- run the gate against the live key list, then upload sdk-coverage.v1.json as a build artifact on trunk pushes only.
• .github/workflows/publish-python-sdk.yml: same gate added to both the honua-sdk and honua-admin publish jobs, so a release cannot ship a stale coverage claim.
• tests/test_sdk_coverage_gate.py: 25 tests covering entrypoint-drift detection, partial-note enforcement, key-list resolution order (fixture vs. env-var override), snapshot-drift detection, and the never-pad rule.

Decisions

• This is a client SDK, so "covered" means this SDK has a client surface that talks to the corresponding server capability -- not that honua-server implements it. Several judgment calls from the source review, called out with a note where coverage is partial:
  • serve.odata: read/query only, no create/update/delete entity-set operations.
  • serve.i3s-scene: generic byte-fetch works for I3S-tagged endpoints (same resolution path as 3D Tiles), but there's no I3S-specific .slpk node/resource-tree parsing (only the 3D Tiles tileset.json walker is implemented).
  • raster.multidim-coverage: read-only multidimensionalInfo metadata query; no client surface to register/configure a multidimensional coverage dataset.
  • raster.temporal-mosaic: mosaic_rule + ISO-8601 time selection is a typed, documented parameter on the ImageServer histogram/statistics/sample operations only -- not on export_image/tile/identify/query.
• process.geoprocessing vs process.ogc-api-processes: only the latter is covered. HonuaGeoprocessing/AsyncHonuaGeoprocessing (client.geoprocessing()) is built entirely on OGC API Processes (/ogc/processes). The Esri GPServer surface that process.geoprocessing's description specifically names is never hit live by this SDK -- migration/modelbuilder.py's GPServer references are an offline ArcPy-migration codemod parsing exported service-definition JSON, not a live task-submission client. Distinguishing these two kept the snapshot honest rather than conflating "geoprocessing" broadly.
• streaming.feature-subscriptions omitted, not partial: the description is specifically "Subscribe to WebSocket and SSE feature-change streams with filters and replay cursors." HonuaGrpcClient.query_features_stream is a gRPC paged bulk-query stream with different transport and semantics (no subscribe/replay-cursor concept) -- close enough to look tempting but not the same capability, so it's omitted rather than stretched into a misleading partial.
• All identity.* keys omitted: no OIDC/SAML/SCIM/portal-token/mTLS surface anywhere in the SDK (verified by grep) -- the SDK only forwards whatever bearer/API-key token it's given.
• sinceVersion is the literal string "unreleased (source preview; not yet published to PyPI)" on every entry, per the issue's instruction never to invent a released version number -- this repo has internal 0.1.x release-please tags but no PyPI publish has ever happened.
• Every other capability key (identity/alerts/channels/dr/analytics/fieldops/printing/staticmap/ai/routing/caching/import/etc.) was checked by source grep during triage and genuinely has zero SDK surface -- omitted per the never-pad rule, not marked none.

Test plan

• ruff check . -- clean
• python -m mypy packages/honua-sdk/honua_sdk packages/honua-admin/honua_admin -- clean (scripts/ is out of mypy's scope per this repo's pyproject.toml, matching compatibility_gate.py/gen_sync.py)
• python scripts/gen_sync.py --check -- unaffected, still in sync
• python scripts/compatibility_gate.py -- unaffected, passes
• python scripts/gen_sdk_coverage.py -- passes offline (pinned fixture) and with HONUA_CAPABILITY_KEY_LIST_URL set to the live honua-server URL
• python -m pytest tests/ -q --cov=honua_sdk --cov=honua_admin --cov-fail-under=94 -- 1516 passed, 18 skipped, 94.37% combined coverage
• Per-package floors (honua_sdk 94.11%, honua_admin 94.60%) both above the 93% gate
• mkdocs build --strict -- clean, no new warnings

Deferred

• honua-evidence ingestion end-to-end proof (one of feat: sdk-coverage.v1.json — per-capability coverage snapshot for the capability matrix #182's three acceptance criteria) is explicitly deferred -- it requires a live aggregate run in honua-evidence consuming this artifact, which is out of scope for this repo's PR. Not claiming "Closes feat: sdk-coverage.v1.json — per-capability coverage snapshot for the capability matrix #182" for that reason; this PR satisfies the other two criteria ("snapshot generated + validated in CI, schema documented" and "drift gate fails on stale coverage") but leaves the ingestion proof to honua-evidence's side.

Related: honua-io/honua-server#2892, honua-io/honua-server#2893.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

[mikemcdougall]

Review

Best-designed of the three coverage snapshots: the entrypoint-resolution drift gate (renamed/removed SDK symbols fail CI) means the snapshot cannot rot silently — recommend the other SDK repos adopt it. Honest-omission calls verified: no identity/OIDC surface in src (omitted, correctly); GPServer vs OGC Processes distinction is exactly right; streaming bulk-query ≠ change-subscriptions not stretched to partial. 25 covered + 4 partial with concrete where-it-stops notes; full suite 1516 green at 94% coverage; gate proven against both fixture and live URL. Merging.

[mikemcdougall]

Scorecard thread addressed: the new upload-artifact step is now pinned by commit hash (043fb46d # v7). Pre-existing unpinned uses elsewhere in the repo are prior debt, out of scope for this PR.