Canonical matching
Prevent duplicate Pages and preserve one score history per provider asset.
Canonical matching uses provider and immutable provider ID, not display name or handle.
| Subject | Canonical key shape |
|---|---|
| X account | x:{provider_user_id} |
| Telegram identity | telegram:{provider_id} |
| GitHub Creator | github:user:{github_user_id} |
| GitHub Agent or Skill | github:repo:{repository_id} |
Atomic server sequence
- Validate provider authorization and signed intent.
- Confirm that the intent belongs to the authenticated Clawdbase user.
- Read the provider identifier server-side.
- Lock and match or create the canonical Page.
- Create the ownership relation without duplicating it.
- Record verification method and timestamp.
- Start initial or refreshed scoring.
Re-running the same valid flow should return created: false with the existing Page. It must not clone the prior score into a second Page.
/api/clawdbase/pages/from-connectionThe preferred request identifies a verified connection and, for GitHub assets, the selected kind and repository:
{
"connectionId": "verified-connection-uuid",
"kind": "Agent",
"repoFullName": "owner/repository"
}Canonical keys
Account Pages are matched by provider plus immutable provider account ID. GitHub Agent and Skill Pages use the immutable repository ID and selected Page kind. Human-readable handles, repository names and display names remain presentation values.
| Page | Canonical authority | Mutable display |
|---|---|---|
| X account | X user ID | X handle and display name |
| Telegram account | Telegram subject/account ID and kind | Username and display name |
| Creator | GitHub user ID | Login, avatar and name |
| Agent | GitHub repository ID plus Agent kind | Owner/repository slug and description |
| Skill | GitHub repository ID plus Skill kind | Owner/repository slug and description |
Atomic server behavior
Validate the connection
Confirm it belongs to the authenticated Clawdbase user, is verified, has not expired and matches the requested provider.
Resolve the authoritative asset
Read provider identifiers from server-held callback data. For GitHub repositories, verify that the selected asset is in the authorized asset set.
Match or insert
Concurrent callbacks resolve to one canonical registration. A browser-side duplicate check is never the ownership authority.
Upsert ownership
Record user, provider, provider ID, method and verification time separately from the Page. This allows an existing Page to be matched without duplicating score data.
Trigger initial scoring
Start or reuse the Page's scoring state after the canonical write commits. Registration scoring is not charged to the developer usage ledger.
Idempotent outcomes
Repeating the same verified registration can return matched with the same Page ID. It must not create another ownership row, another canonical score source or a second card. A handle rename updates presentation for the existing provider ID.
Conflict outcomes
If the immutable provider identity is already linked to another Clawdbase user, return a conflict before writing legacy vault or Page data. The interface should show: “This account is already linked to another Clawdbase user. Sign out and use that account, or choose a different account.” Do not redirect to the landing page; return to the initiating Console or registration route.