[cameronehrlich]

What changed

• inventory all 99 official Platform SDK operations against 71 root response types and the complete 220-model response closure
• record response schema/source hashes plus strict, identifier, enum, and custom-validator fields in manifest schema v2
• harden the confirmed live-response compatibility hook so only exact Pydantic field/type/value mismatches are eligible
• revalidate the complete patched copy through the official SDK before returning unchanged wire JSON, preventing a known first-row mismatch from hiding later unrelated errors
• reject boolean and floating-point near misses for integer impression-share IDs
• document confirmed drift, unconfirmed sibling risks, and the required fail-closed extension procedure
• bump the CLI patch release to 1.1.1 without changing the pinned Apple SDK 1.109.0 contract

Why

The ASO adoption work confirmed Apple live responses that disagree with generated SDK types. The original narrow fallback preserved those responses, but a known mismatch raised early by nested SDK hydration could conceal a different invalid row later in the payload. It also used Python integer checks that include booleans.

The closest analogous SDK surface, business-brand keyword status, could not be live-confirmed because the available account is not eligible. It deliberately remains strict and has a regression test proving it is not swept into the compatibility allowlist.

Impact

Existing commands and wire output are unchanged for the two confirmed live mismatches. Unknown, sibling, mixed, malformed, boolean, and floating-point mismatches continue to fail nonzero. The manifest now detects response-model drift even when an SDK upgrade leaves the operation count unchanged.

No Apple Ads mutation or spend change was used for verification.

Validation

• uv run ruff check .
• uv run pytest -q — 407 passed
• manifest regeneration/check on Python 3.12 and 3.14
• 20 generated skill references current
• release metadata check for CLI 1.1.1 / SDK 1.109.0
• wheel and sdist build
• clean Python 3.12 wheel install and CLI smoke test
• packaged manifest verified as schema v2 with 99 operations and 220 response models
• representative safe live reads across available resource and reporting families
• git diff --check

Tracks roadmap-84yz.

Summary by CodeRabbit

• New Features

  • Added audited response-model metadata and validation to platform manifests.
  • Improved handling of confirmed SDK response-format mismatches while preserving strict validation for unrelated errors.
  • Updated the CLI release version to 1.1.1.

• Bug Fixes

  • Prevented near-miss or ambiguous response payloads from bypassing validation.
  • Ensured invalid identifiers and later row-level errors are reported correctly.

• Documentation

  • Expanded contribution, release, safety, and response-drift guidance.
  • Updated installation and release instructions for version 1.1.1.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 380b7730-01c0-4dff-965d-1f4775752f52

📥 Commits

Reviewing files that changed from the base of the PR and between 70bd2fe and 6cfa524.

📒 Files selected for processing (16)

• CONTRIBUTING.md
• README.md
• RELEASING.md
• SKILL.md
• asa_cli/__init__.py
• asa_cli/platform/client.py
• asa_cli/platform/manifest/apple_ads_platform_manifest.schema.json
• asa_cli/platform/manifest/apple_ads_platform_v1_109_0.json
• asa_cli/platform/manifest_discovery.py
• pyproject.toml
• references/safety-and-output-contracts.md
• references/sdk-response-drift-audit.md
• scripts/_command_catalog.py
• tests/test_platform_manifest.py
• tests/test_platform_runtime.py
• tests/test_release_metadata.py

---

📝 Walkthrough

Walkthrough

The manifest now inventories response models and field metadata. Runtime deserialization handles two confirmed SDK wire-format mismatches through copied-payload validation. Documentation, tests, and release metadata were updated for these changes and version 1.1.1.

Changes

Response model manifest

Layer / File(s)	Summary
Manifest schema and response-model generation asa_cli/platform/manifest/apple_ads_platform_manifest.schema.json, asa_cli/platform/manifest_discovery.py, scripts/_command_catalog.py	Manifest version 2 requires one response_model per operation and a top-level response_models map. Discovery records reachable models, hashes, and field-audit metadata.
Manifest drift and provenance validation tests/test_platform_manifest.py, CONTRIBUTING.md, references/sdk-response-drift-audit.md	Tests validate response-model closure, field-audit totals, and source provenance. Guidance documents the audited model inventory and upgrade review requirements.

Response deserialization compatibility

Layer / File(s)	Summary
Compatibility rules and audit references/safety-and-output-contracts.md, references/sdk-response-drift-audit.md, SKILL.md, CONTRIBUTING.md	The compatibility rules require exact live-confirmed mismatches, copied-payload validation, fail-closed near-miss handling, and rejection of boolean or floating-point identifiers.
Validated response fallback asa_cli/platform/client.py, tests/test_platform_runtime.py	The client matches confirmed validation errors, patches copied row data, validates the complete response through the SDK, and preserves unrelated later-row errors.

Release metadata update

Layer / File(s)	Summary
Version and release references asa_cli/__init__.py, pyproject.toml, README.md, RELEASING.md, tests/test_release_metadata.py	Package, CLI, installation, release, and version-test references now use version 1.1.1.

Estimated code review effort: 4 (Complex) | ~45 minutes

Merge Risk: ⚪ Minimal · up to 6cfa5

The PR tightens response-drift validation while preserving confirmed wire compatibility; no actionable merge-blocking risk remains after normal checks and review.

Sequence Diagram(s)

sequenceDiagram
  participant AppleAdsAPI
  participant Client
  participant SDKDeserializer
  AppleAdsAPI->>Client: response JSON
  Client->>SDKDeserializer: deserialize original response
  SDKDeserializer-->>Client: confirmed validation mismatch
  Client->>Client: copy and patch affected row values
  Client->>SDKDeserializer: validate complete patched response
  SDKDeserializer-->>Client: validated response
  Client-->>AppleAdsAPI: return original raw payload

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the primary change: stronger SDK response-drift validation for version 1.1.1.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/apple-search-ads-cli-sdk-response-drift-audit

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}