Official Platform Adapters and Policy Snapshot

1. Problem: a successful response does not prove a current contract

An adapter can keep returning apparently valid responses while its API version, permission scope, schema, or provider policy has drifted. This lesson produces Official Platform Adapter & Policy Snapshot v1, an auditable record of the exact provider/product/version/operation/policy evidence that supports the current adapter state.

2. Lesson boundary

PLN-020 owns the adapter and policy snapshot. The capacity-advisor outcome in PLN-019 and capability registry in PLN-021 remain separate. This lesson performs no live publish, credential use, or network action.

3. External FACT versus MAKNOW DESIGN

GitHub REST API is versioned and X-GitHub-Api-Version pins request behavior; breaking changes arrive in new API versions. GitHub also publishes machine-readable OpenAPI descriptions for products and date-based versions. LinkedIn Marketing APIs use their own version header and release/sunset cadence. The states SUPPORTED / CONDITIONAL / UNSUPPORTED / STALE_EVIDENCE / UNKNOWN and the decision rules are MAKNOW DESIGN.

4. Identify platform and product surface precisely

platform_id and product_surface must be more precise than a provider brand name. Record the API family and product surface because one provider can expose multiple APIs, products, versions, and support windows.

5. Pin API version and version header

The snapshot records the exact API version. A stable endpoint path does not imply stable behavior. If the required version header is absent or the documented version differs from the adapter version, the contract is not current merely because the request returned 2xx.

6. Keep auth mode and permission scope separate from version

The version can be correct while the required scope has changed. permission_scope is an independent gate. Missing scope produces CONDITIONAL plus REAUTH_REQUIRED; do not invent authorization and do not execute externally.

7. Operation and endpoint are not enough; snapshot schema too

Record operation_id, endpoint, and request/response schema references against official evidence. OpenAPI can validate interface shape, but it does not prove provider policy, account eligibility, or execution authority.

8. Give the policy snapshot its own identity

Use policy_snapshot_id and policy_locator to identify the exact reviewed policy evidence. Reusing the same URL is not enough because provider content can change without the local adapter changing.

9. Freshness: retrieval time and review due

Volatile API and policy evidence needs retrieved_at and review_due. After review due, a healthy endpoint and successful request do not make old evidence current. The state becomes STALE_EVIDENCE with POLICY_RECHECK.

10. Preserve deprecation and sunset state

deprecation_notice and sunset_state are part of the adapter contract. An adapter can still work while its API version is approaching shutdown. An unsupported/sunset version becomes UNSUPPORTED/MIGRATE_VERSION; an active deprecation may be CONDITIONAL/REVIEW_DEPRECATION.

11. Bounded state machine

Use SUPPORTED only when version/header, permission, schema, policy freshness, deprecation/sunset, and provenance are all defensible. CONDITIONAL means a repairable gate remains open. STALE_EVIDENCE means time-bounded evidence is no longer current. UNSUPPORTED requires explicit negative support evidence. Missing evidence remains UNKNOWN.

12. Baseline: current GitHub adapter snapshot

The baseline records a currently documented GitHub version with X-GitHub-Api-Version, endpoint/schema references, policy snapshot, review dates, and complete provenance. It reaches SUPPORTED and can move only to the separate capability registry; this lesson never authorizes publish.

13. Dangerous shortcuts

Do not equate 2xx with a current contract. Stable endpoint does not mean stable schema. Do not treat a missing version header as acceptable by assumption, reuse expired policy because the URL is unchanged, carry an old permission model into a new version, or treat OpenAPI as authorization/business policy.

14. Transfer: same endpoint family, new scope and deprecation

The transfer provider keeps the same base path/endpoint family while the required scope and deprecation notice change. Rebuild the snapshot from current evidence. If the new scope is not ready or deprecation is active, do not copy the baseline state; preserve CONDITIONAL and the migration/re-auth path.

15. Lab, assessment, and freshness

Run python run_checks.py under lab/PLN-020-LAB1/learner/. The eight fixtures cover baseline, missing version header, stale policy, changed permission, sunset version, 2xx without snapshot, missing provenance, and transfer. GitHub and LinkedIn official sources were rechecked on 2026-09-16; accepted bytes require a new package version to change.