برنامهریزی، تحلیل و عملیات پلتفرم · فصل ۴ — Adapter، Capability، Shadow/Direct Publish و Quota · 212
Platform Capability Registry
Build an evidence-backed capability registry that records the exact operation, resource/media type, API/version, auth scope, constraints, quota relevance, evidence locator and availability state for each platform capability, while preserving CONDITIONAL, UNSUPPORTED and UNKNOWN instead of inventing parity across platforms. میتواند برای «Platform Capability Registry» model، signal و guardrail لازم را در یک workflow محدود تعریف و ارزیابی کند.
Lesson summary
Build an evidence-backed capability registry that records the exact operation, resource/media type, API/version, auth scope, constraints, quota relevance, evidence locator and availability state for each platform capability, while preserving CONDITIONAL, UNSUPPORTED and UNKNOWN instead of inventing parity across platforms.
میتواند برای «Platform Capability Registry» model، signal و guardrail لازم را در یک workflow محدود تعریف و ارزیابی کند.
This lesson produces
میتواند برای «Platform Capability Registry» model، signal و guardrail لازم را در یک workflow محدود تعریف و ارزیابی کند.
Who it is for
Foundation
Use a guided C04 evidence matrix and one worked negative case.
Repair
Re-run only the failed owned dimension with a smaller deterministic synthetic fixture.
Experienced
Start from conflicting adapter/capability/publish/quota signals; require explicit trade-offs, uncertainty and provenance.
Prerequisites
1. Problem: feature visibility is not API capability
A button in a provider UI for video upload, post editing, or reporting does not prove the same operation exists in the official API, in the current version, for the current account and scopes. This lesson produces Platform Capability Registry v1, where every capability is tied to versioned provider evidence.
2. Lesson boundary
PLN-021 owns capability evidence only. The official adapter/policy snapshot from PLN-020, shadow validation from PLN-022, and direct publish from PLN-023 remain separate outcomes. This lesson performs no network call or external publish.
3. External FACT versus MAKNOW DESIGN
GitHub publishes a machine-readable OpenAPI description for its REST API. LinkedIn Marketing APIs are versioned and monthly changes can alter resource behavior. YouTube documents parameters and quota impact per method; videos.list has a documented cost of 1 quota unit as rechecked on 2026-09-16. The states SUPPORTED / CONDITIONAL / UNSUPPORTED / STALE_EVIDENCE / UNKNOWN are MAKNOW DESIGN.
4. Decompose the requested action into an exact operation
Statements such as “platform X supports video” are too coarse. Name the exact operation: read_video_metadata, create_video, update_video, or delete_video. Each operation is an independent capability; success on one does not prove another.
5. Keep resource and media type separate
resource_type identifies the object, while media_type constrains the data or media. Text-post support does not prove video upload. Video read support does not prove video update.
6. API version is part of the evidence
A capability record without api_version is incomplete. If the documentation belongs to another version or a version has changed/sunset, do not reuse the previous state. LinkedIn demonstrates why version headers and release cycles matter to the request contract.
7. Bind endpoint or method to official evidence
endpoint_or_method must point to the requested operation, not merely to a provider homepage or UI. GitHub OpenAPI can describe an operation and schema; YouTube method pages enumerate the parameters for that specific method.
8. Auth scope and account prerequisite are separate gates
A documented method is not enough. The credential can lack the required scope, or the account/product tier can fail a prerequisite. Such a row can be CONDITIONAL; it is not yet SUPPORTED for execution.
9. Keep constraints and quota in the same row
File size, media type, required parameters, visibility rules, and quota relevance must remain visible. Do not treat unknown quota as zero or unlimited; route it to QUOTA_REVIEW. An explicit incompatible constraint can make the capability UNSUPPORTED.
10. Evidence locator, retrieval time, and provenance
Every row carries evidence_locator, retrieval time, and provenance_ref. A URL without freshness is insufficient for volatile APIs. Old or version-mismatched evidence becomes STALE_EVIDENCE and requires recheck.
11. Bounded state machine
SUPPORTED requires documented operation, matching version, valid scope/account/constraints, defensible quota evidence, and provenance. CONDITIONAL means the operation is documented but an execution gate such as scope, account prerequisite, or quota review remains open. Use UNSUPPORTED only for explicit negative evidence. Missing evidence stays UNKNOWN; old evidence stays STALE_EVIDENCE.
12. Baseline: documented operation with complete evidence
The baseline records a documented GitHub operation with version, endpoint, scope, account prerequisite, constraints, quota relevance, and provenance. It reaches SUPPORTED. The next decision is only EXECUTE_SHADOW; this lesson never authorizes live publish.
| case_id | platform_id | operation | api_version | endpoint_or_method | auth_scope_granted | quota_relevance | availability_state | fallback_state | next_decision |
|---|---|---|---|---|---|---|---|---|---|
| baseline_github_documented | github | create_issue | 2022-11-28 | POST /repos/{owner}/{repo}/issues | True | KNOWN | SUPPORTED | NONE | EXECUTE_SHADOW |
| ui_only_feature | provider-x | auto_magic_edit | 2026-09 | — | False | NONE | UNKNOWN | EVIDENCE_REQUIRED | BLOCKED_EVIDENCE |
| missing_auth_scope | update_campaign | 202608 | PATCH /rest/adCampaigns/{id} | False | KNOWN | CONDITIONAL | REAUTH_REQUIRED | DEFER_SCOPE_REPAIR | |
| version_mismatch | read_campaign | 202607 | GET /rest/adCampaigns/{id} | True | KNOWN | STALE_EVIDENCE | REVERIFY_VERSION | DEFER_RECHECK | |
| unsupported_media_type | provider-y | create_media | v3 | POST /media | True | KNOWN | UNSUPPORTED | ALT_MEDIA_OR_MANUAL | REJECT_AUTOMATION |
| missing_provenance | github | create_issue | 2022-11-28 | POST /repos/{owner}/{repo}/issues | True | KNOWN | UNKNOWN | EVIDENCE_REQUIRED | BLOCKED_EVIDENCE |
| quota_unknown | provider-z | create_post | v1 | POST /posts | True | UNKNOWN | CONDITIONAL | QUOTA_REVIEW | DEFER_QUOTA_REVIEW |
| transfer_youtube_videos_list | youtube | read_video_metadata | v3 | GET /youtube/v3/videos | False | KNOWN | SUPPORTED | NONE | EXECUTE_SHADOW |
13. Dangerous shortcuts
Do not convert UI-visible into API-supported, create a generic supports_video=true, infer write from read, ignore missing scopes, call old-version evidence current, or treat unknown quota as unlimited. Those shortcuts create false platform confidence.
14. Transfer: same ecosystem, changed operation or media
The transfer row is rebuilt from new evidence. Here, YouTube videos.list documents the read method and its quota impact, so metadata read can be SUPPORTED; that result does not prove upload or update capability.
15. Lab, assessment, and freshness
Run python run_checks.py under lab/PLN-021-LAB1/learner/. The eight fixtures cover baseline, UI-only, missing scope, version mismatch, unsupported media, missing provenance, unknown quota, and transfer. GitHub, LinkedIn, and YouTube official sources were rechecked on 2026-09-16; accepted bytes require a new package version to change.
Assessment
There is no answer key in this lesson pack; answer it yourself and mark honestly. "Needs review" sends the lesson to your review queue.
PLN-021-S1 retrieval
Why does a provider UI feature not prove the corresponding API capability?
PLN-021-S2 application
Build a capability row for a documented operation with version, scope, constraints, quota evidence and provenance.
PLN-021-S3 diagnosis
Diagnose a row whose operation is documented but the required auth scope is not granted.
PLN-021-S4 transfer
Rebuild the registry row for YouTube videos.list without inferring create/update capability from the read method.
Assessment rubric
- Identity and boundary: capability registry is owned; adapter, shadow, and direct publish remain separate.
- Exact evidence binding: operation, version, method, scope, constraints, quota relevance and provenance are explicit.
- Typed negative states: UNKNOWN, STALE_EVIDENCE, CONDITIONAL and UNSUPPORTED are not coerced to success.
- Bounded decision: only SUPPORTED routes to the separate shadow gate.
- Transfer: changed platform/operation evidence is recomputed rather than copied.
References & freshness
Case studies
Lab files
دستور python run_checks.py را اجرا کنید. هر fixture را بررسی کنید و سپس rowهای محدود خودتان را بسازید. Lab آفلاین و synthetic است: API key، تماس Provider یا Publish واقعی ندارد.
هدف: capability مستند را از UI visibility جدا کنید و stateهای non-success را صریح نگه دارید.