Fork atıfını oku — bir persona nereden geldi, nereye gitti

Bir persona Moonborn'da hiç tek başına yaşamaz — her zaman bir soy ağacının (lineage tree) içinde. Sıfırdan üretilenler ağacın köküdür (root); fork'lanan her varyant ebeveyne (parent) bir kenar (edge) ekler. Bu yapı sayesinde "bu marka varyantı hangi kanonik karakterden geliyor?" veya "biz yayınladığımız bu persona şu ana kadar kaç kez fork'landı?" gibi soruları tek bir soy çağrısıyla yanıtlarsın.

Bu rehber soy atalar zincirini (ancestry) okumayı, aşağı yöndeki (downstream) fork sayımını ve pazaryeri listelemelerini (listings) içeren organizasyonlar arası (cross-org) atfı (attribution) gösterir.

Bu rehberi bitirdiğinde

• Bir persona'nın atalar zincirini (kök → ... → ebeveyn) sorgulayabileceksin.
• Doğrudan ve geçişli (transitive) fork sayılarını ayırt edebileceksin.
• Bir pazaryeri listelemesinin aşağı yöndeki etkisini ölçebileceksin.
• Organizasyonlar arası atfın soy ağacında nasıl göründüğünü bileceksin.
• Lisans (CC-BY / ShareAlike / ticari kullanım) ile soy kenarlarının nasıl etkileştiğini anlayacaksın.

Ön koşul: API anahtarı + en az bir soy ağacına sahip persona. Fork mekaniğine yeni başlıyorsan önce Marka varyantlarını fork'la.

1. Bir persona'nın atalar zincirini bul

getLineage çağrısı ebeveyn zincirinin tamamını köke (root) kadar döndürür.

const lineage = await client.personas.getLineage({ id: persona.id });
 
console.log('root:', lineage.root.id);
console.log('ancestors:', lineage.ancestors.map((a) => a.id));
console.log('parent:', lineage.parent?.id);

Beklenen yanıt (kısaltılmış):

{
  "root": { "id": "per_canonical_brand...", "name": "Brand voice — canonical" },
  "ancestors": [
    { "id": "per_canonical_brand...", "depth": 0 },
    { "id": "per_formal_variant...",  "depth": 1, "note": "Sales variant" }
  ],
  "parent": { "id": "per_formal_variant...", "depth": 1 },
  "self":   { "id": "per_formal_de_locale...", "depth": 2, "note": "Formal DE locale" }
}

2. Doğrudan + geçişli fork'ları say

İki ayrı sayım vardır:

const lineage = await client.personas.getLineage({ id: canonical.id });
 
console.log({
  directForks: lineage.children.length,
  totalDescendants: lineage.descendants.length,
});

Örnek: kanonik bir marka karakterinden iki doğrudan varyant (resmi / formal, sıradan / casual) türettiysen ve resmi varyanttan da iki dil-bölge varyantı (DE, TR) türetildiyse:

Canonical (root)
├── Formal           ← doğrudan çocuk
│   ├── Formal-DE    ← torun (doğrudan değil)
│   └── Formal-TR    ← torun (doğrudan değil)
└── Casual           ← doğrudan çocuk
 
directForks:       2
totalDescendants:  4

3. Pazaryeri listelemesinin aşağı yöndeki etkisi

Bir pazaryeri (marketplace) listelemesi yayınladığında aşağı yöndeki istatistikler de soy ağacından beslenir. Listeleme detay sorgusu:

const listing = await client.marketplace.listings.get({ id: 'lst_01H...' });
 
console.log({
  downloads:  listing.downloads,   // kurulum sayısı (yeni persona üretmedi)
  forks:      listing.forks,       // kurulum + fork (yeni persona üretti)
  ratingsAvg: listing.ratingsAvg,
});

Burada downloads (kurulum) ile forks arasındaki fark önemlidir:

Persona kuruldu, kullanıcı kanonik halinde kullanıyor.
Henüz fork yapmadı — kullanıcı persona'yı sadece tüketiyor.

4. Organizasyonlar arası atıf

Pazaryeri kurulumu bir organizasyonlar arası (cross-org) kenar yaratır: orijinal listeleme senin organizasyonundadır, kurulum kullanıcının organizasyonundadır. Soy ağacı bu kenarı da görür.

Kullanıcı kurulumdan sonra fork yaparsa, fork'un atalar zincirinde:

{
  "ancestors": [
    {
      "id": "per_original_listing_persona...",
      "depth": 0,
      "marketplaceListingId": "lst_01H...",
      "marketplaceOrgId": "org_publisher...",
      "license": "CC-BY-4.0"
    },
    {
      "id": "per_installed_at_consumer_org...",
      "depth": 1,
      "note": "Installed from marketplace"
    },
    {
      "id": "per_customer_variant...",
      "depth": 2,
      "note": "Customized for support channel"
    }
  ]
}

marketplaceListingId ve marketplaceOrgId organizasyonlar arası iz (breadcrumb) taşır — aşağı yöndeki atıf analizinde kullanılır.

Lisans uyumu

Soy kenarları lisansa uymak zorundadır:

5. Pratik kullanım desenleri

Bir persona'yı arşivlemeden önce aşağı yöndeki etkiyi kontrol et

const lineage = await client.personas.getLineage({ id: 'per_to_archive...' });
 
if (lineage.descendants.length > 0) {
  console.warn(
    `Bu persona'yı arşivlemek ${lineage.descendants.length} aşağı yöndeki varyantı etkileyebilir`,
  );
}

Arşivlenmiş persona'lar çalışma zamanında (runtime) çalışmaz — torunlar (descendants) ebeveyne referans gösteriyorsa çalışma zamanı davranışı kırılabilir.

Marka denetiminde "bu varyant nereden geldi" sorusu

Marka denetiminde bir varyantın kaynağını sorgulamak istersen:

const lineage = await client.personas.getLineage({ id: 'per_variant_in_question...' });
console.log('Root canonical:', lineage.root.id);
console.log('Variant chain:', lineage.ancestors.map((a) => a.note).join(' → '));

Plan gereksinimi

• Soy sorgusu (kendi organizasyonundaki persona'lar): her plan.
• Organizasyonlar arası pazaryeri atfı: Free ve üstü (listeleme herkese açık yayınlandıysa).

İlgili