Learning/Product Analytics Event Taxonomy

سه محصول می‌گویند «درس کامل شد». آیا واقعاً یک event واحد را می‌گویند؟

یک سطح MAKNOW رویداد lesson_done می‌فرستد، دیگری completedLesson، و سومی lesson-complete-42 می‌سازد و شناسهٔ درس را داخل نام event می‌گذارد. یک producer زمان دستگاه را ثبت می‌کند، دیگری زمان دریافت سرور را، و dashboard هر سه رویداد Complete را به‌عنوان اثبات mastery تفسیر می‌کند.

چنین pipelineای شاید نمودار بسازد، اما هنوز analytics قابل‌اعتماد نمی‌سازد. raw occurrence فقط evidence این است که طبق semantics یک producer چیزی رخ داده است؛ خودبه‌خود اثبات intent، mastery، causal impact یا حتی semantic equivalence بین نسخه‌ها نیست.

در این درس Learning & Product Event Taxonomy Governance Contract v1 را می‌سازیم. این قرارداد semantic name پایدار را از instance data جدا می‌کند، event_timestamp را از observed_timestamp تفکیک می‌کند، هر record را به taxonomy/schema/producer version متصل می‌کند، privacy و cardinality را طبقه‌بندی می‌کند، deprecation/migration را قابل‌ممیزی نگه می‌دارد و derived metric و mastery claim را پایین‌دست raw event قرار می‌دهد.

قاعدهٔ مرکزی: اول معنای پایدار event؛ بعد evidence وقوع؛ و interpretation فقط با قرارداد evidence جداگانه.

برای: مهندسان learning platform و analytics، تیم product/data، صاحبان instrumentation و reviewerهای governance. نه برای: جمع‌آوری telemetry واقعی learner در این درس، بازنویسی معنای تاریخی، استنتاج mastery از click، یا تبدیل Caliper/OpenTelemetry به authority سیاست محصول MAKNOW.

جایگاه درس و مرز مالکیت

MKN-020 فقط مالک Learning/Product Analytics Event Taxonomy است. prerequisiteهای فریز‌شده MKN-017 (hard) و MKN-019 (soft) هستند. MKN-019 مالک Matching, Fairness & Explainability و MKN-021 مالک Contributor and Editorial Governance است؛ این درس outcome آن‌ها را جذب نمی‌کند.

مسیر foundation با field map و یک canonicalization case هدایت‌شده شروع می‌شود. مسیر repair اولین defect معنایی/provenance را جدا می‌کند و فقط gate مرتبط را دوباره اجرا می‌کند. مسیر experienced باید migration، versioning، replay، privacy و derived-metric boundary را بدون پنهان‌کردنشان در یک «analytics quality score» دفاع کند.

Checkpointها: F1 مرز مالکیت و یک non-goal؛ F2 تشخیص dynamic event name و mastery overclaim؛ F3 بازمحاسبهٔ نتیجه برای mobile producer آفلاین که پس از taxonomy revision داده را upload می‌کند.

مدل ذهنی: semantic contract → occurrence record → validation → storage → derivation

جریان را این‌طور ببینید:

taxonomy version → stable event definition → producer/schema version → event occurrence → event time + observed time → validation/privacy/cardinality → immutable raw record → migration/deprecation view → derived metric → separately justified learning claim

Event taxonomy می‌گوید این event چه معنایی دارد، نه این‌که learner mastery دارد. attributeهای instance می‌گویند کدام occurrence رخ داده است. producer version مشخص می‌کند کدام instrumentation آن را صادر کرده. event time زمان وقوع را نگه می‌دارد و observed time زمان دیده‌شدن/دریافت توسط collector یا component بعدی را. اختلاف این دو timestamp الزاماً خطا نیست.

Stateهای typed ضروری‌اند. Candidate می‌تواند REVIEW_REQUIRED، HOLD_DYNAMIC_EVENT_NAME، HOLD_TIMESTAMP_EVIDENCE، HOLD_MIGRATION_MISSING، HOLD_MASTERY_INFERENCE یا HOLD_PRIVACY_CLASS باشد. سیستم باید دلیل عدم promotion را نشان بدهد، نه اینکه uncertainty را به valid=true تبدیل کند.

قرارداد پایه: هر event به semantics پایدار و provenance قابل replay نیاز دارد

۲۱ dimension فریز‌شده عبارت‌اند از: taxonomy_version، event_name، event_definition، actor_ref_pseudonymous، object_ref، action_or_state، event_timestamp، observed_timestamp، context_ref، outcome، attribute_semantics، cardinality_class، privacy_class، schema_version، producer_version، validation_state، deprecation_state، replacement_event، derived_metric_ref، mastery_claim_forbidden_without_evidence و provenance.

Invariantهای حداقلی:

1. نام event یک semantic identifier پایدار است. lesson ID، user ID، attempt number، resource ID و سایر dynamic valueها باید در attribute باشند، نه نام event.
2. Definition قبل از emission می‌آید. taxonomy occurrence و attributeهای مجاز/الزامی را تعریف می‌کند.
3. Actor reference در صورت الزام قرارداد pseudonymous است. privacy classification باید صریح باشد و از اسم field حدس زده نشود.
4. Event time و observed time دو field متفاوت‌اند. delayed/offline upload می‌تواند observed timestamp متأخر داشته باشد.
5. Taxonomy، schema و producer version مستقل‌اند. تغییر instrumentation نباید بی‌صدا معنی event را عوض کند.
6. Validation صریح است. evidence قاطعِ ناقص باید HOLD/UNKNOWN/REVIEW_REQUIRED بسازد، نه positive state حدسی.
7. Deprecation history را پاک نمی‌کند. event deprecated معنای اصلی و در صورت وجود replacement/migration reference را نگه می‌دارد.
8. Derived metric پایین‌دست است. count/funnel/retention/learning indicator باید derivation خود را نام ببرد و raw event را overwrite نکند.
9. Raw event اثبات mastery نیست. mastery قرارداد evidence و interpretation جدا می‌خواهد.
10. Replay باید semantics را حفظ کند. تبدیل تاریخی فقط با migration provenance صریح مجاز است و نسخه/معنای اصلی باید قابل بازیابی بماند.

توضیح عمیق: vocabulary بین‌سیستمی همان authority تفسیر محلی نیست

1EdTech Caliper. صفحهٔ جاری 1EdTech هنوز Caliper Analytics را با common language و metric profile برای نمایش سازگار فعالیت‌های یادگیری معرفی می‌کند و Caliper 1.2 را در منابع specification نشان می‌دهد. وقتی interactionهای MAKNOW semantic fit داشته باشند، mapping به Caliper می‌تواند interoperability را بهتر کند. اما Caliper mastery threshold، KPI محصول، retention یا privacy policy MAKNOW را تعریف نمی‌کند.

OpenTelemetry event semantic conventions. صفحهٔ جاری eventها را named occurrence در یک نقطهٔ زمانی توصیف می‌کند، event name معنادار می‌خواهد، dynamic value را در event name منع می‌کند، Timestamp را زمان وقوع می‌داند و ObservedTimestamp را از آن جدا نگه می‌دارد. خود صفحه فعلاً Development است؛ بنابراین MAKNOW آن را evolving practice می‌داند نه authority فریز‌شدهٔ محصول.

Inference MAKNOW. این دو منبع از یک inference مهندسی قوی حمایت می‌کنند: stable name + structured attributes + producer/version semantics برای cross-product analytics قابل‌مقایسه‌تر از ad-hoc nameهای پویاست؛ همچنین occurrence time باید از receipt/observation time جدا بماند. اما هیچ‌کدام ثابت نمی‌کنند “completion = mastery”.

Design authority MAKNOW. event namespace، required fields، privacy/cardinality class، validation state، deprecation window، migration/replay rule، metric formula، retention و learning-claim interpretation تصمیم‌های محلی هستند. استاندارد بیرونی representation را کمک می‌کند، نه اینکه اجازهٔ reinterpretation learner evidence بدهد.

مثال‌های حل‌شده

مثال A — canonicalization سه completion event قدیمی

producerهای قدیمی lesson_done، completedLesson و lesson-complete-42 می‌فرستند. مورد سوم defect ساختاری دارد، چون شناسهٔ 42 داخل event name است. Governance contract یک نام canonical پایدار مثل learning.lesson.completed می‌سازد، lesson ID را در object_ref می‌گذارد، producer version را ثبت می‌کند و legacy nameها را با migration evidence صریح map می‌کند.

Raw outcome فقط چیزی مثل «producer طبق taxonomy v3 completion را گزارش کرد» است؛ نه «learner درس 42 را mastered کرد». mastery_claim_forbidden_without_evidence=true باید visible بماند.

سقف مثبت: TAXONOMY_REVIEW_REQUIRED. Promotion نهایی هنوز decision governed/human است.

مثال B — mobile event دو روز دیرتر می‌رسد

client موبایل event_timestamp=2026-09-10T09:00Z را ثبت می‌کند، offline می‌شود و collector در observed_timestamp=2026-09-12T14:00Z record را می‌بیند. این اختلاف خودبه‌خود timestamp error نیست. هر دو زمان، producer version، taxonomy/schema قدیمی و migration provenance حفظ می‌شوند.

اگر taxonomy جدید نام event را عوض کرده، record قدیمی را overwrite نکنید تا وانمود شود producer معنای جدید را emit کرده است. raw historical record را نگه دارید و compatibility/migration view جدا بسازید.

مثال C — click event تبدیل به “mastery rate” می‌شود

learner روی Complete کلیک می‌کند و raw event معتبر است؛ dashboard بدون assessment/rubric/evidence جداگانه learner را “mastered” می‌نامد.

نتیجهٔ درست برای interpretation path: HOLD_MASTERY_INFERENCE. occurrence ممکن است valid بماند، در حالی‌که mastery claim invalid است. این دقیقاً boundary اصلی درس است.

Failure modeها و adversarial probeها

• Dynamic event name: lesson-complete-42 namespace را با instance data آلوده می‌کند. → HOLD_DYNAMIC_EVENT_NAME.
• Definition drift بدون version: همان نام در producer جدید معنای دیگری پیدا می‌کند. → HOLD_SCHEMA_OR_MEANING_DRIFT.
• Observed time جای event time: delayed upload طوری گزارش می‌شود که انگار action هنگام receipt رخ داده. → HOLD_TIMESTAMP_EVIDENCE.
• Rename بدون migration map: recordهای قدیمی بی‌صدا به نام جدید rewrite می‌شوند. → HOLD_MIGRATION_MISSING.
• Producer/schema version ناقص: reproducibility instrumentation از بین می‌رود. → HOLD_VERSION_EVIDENCE.
• Privacy class ناقص: actor pseudonym وجود دارد ولی data classification مشخص نیست. → HOLD_PRIVACY_CLASS.
• High-cardinality data در name: learner/session/document/error text وارد namespace می‌شود. → HOLD_CARDINALITY_POLICY.
• Derived metric raw evidence را overwrite می‌کند: provenance occurrence از بین می‌رود. → HOLD_DERIVATION_PROVENANCE.
• Completion = mastery: یک click/complete signal به‌تنهایی learning proof فرض می‌شود. → HOLD_MASTERY_INFERENCE.
• Replay history را rewrite می‌کند: original producer/version/meaning قابل بازیابی نیست. → HOLD_REPLAY_PROVENANCE.

Validator deterministic می‌تواند violationهای contract را بگیرد؛ ولی بدون evidence model جدا نمی‌تواند معنای آموزشی mastery را اختراع کند.

گزینه‌ها و trade-offها

یک event بسیار عمومی با attributeهای زیاد. تعداد nameها را کم می‌کند، اما semantic definition را مبهم و validation را ضعیف می‌کند. shared name فقط وقتی خوب است که definition واقعاً برای همهٔ occurrenceها یکسان باشد.

یک event name برای هر object instance. query prefix شاید ساده به نظر برسد، ولی cardinality را منفجر می‌کند و namespace را به محل data تبدیل می‌کند. semantic name پایدار + attribute قابل replayتر است.

Rewrite همهٔ history به آخرین schema. dashboard را ساده می‌کند، ولی provenance را می‌کشد. raw layer immutable و normalized/migrated view نسخه‌دار قابل دفاع‌تر است.

Infer outcome مستقیماً از raw event. سریع است، اما event می‌تواند missing، duplicated، delayed، inconsistent یا semantically insufficient باشد. derived metric باید formula/window/source version خود را نام ببرد و learning claim قرارداد evidence جدا بخواهد.

فقط Caliper یا فقط OpenTelemetry. Caliper برای learning activity vocabulary مفید است و OpenTelemetry برای event/telemetry representation. هیچ‌کدام به‌تنهایی event governance و interpretation policy محلی MAKNOW را مالک نیستند.

پل experienced: taxonomy یک قرارداد بین producerها و زمان است

در مقیاس بالا مشکل اصلی emit کردن JSON نیست؛ حفظ meaning وقتی SDK، client، dashboard و تیم‌ها مستقل evolve می‌شوند است.

یک registry/governed catalog داشته باشید که برای هر event این موارد را نگه دارد: stable name، definition، owner، taxonomy version، schema version، allowed attributeها، cardinality/privacy class، producer compatibility، deprecation state، replacement و change history. تست instrumentation در CI می‌تواند payloadهای producer را قبل از release مقابل این contract validate کند.

برای offline/replayed events هر دو occurrence و observation semantics را ذخیره کنید. Migration function باید deterministic، versioned و provenance-preserving باشد. اگر old event بدون تغییر meaning قابل map نیست، همان old event را نگه دارید و normalized interpretation را partial/unavailable اعلام کنید.

برای derived metric نیز metric ID/version، input event versionها، time window، dedup/idempotency rule، late-arrival policy و transformation provenance را ثبت کنید تا historical comparison با تغییر producer قابل توضیح بماند.

تمرین هدایت‌شده و مستقل

مرحلهٔ هدایت‌شده. lab://MKN-020/MKN-020-LAB1 را باز کنید. baseline canonical را با dimensionهای visible پر کنید: stable event name، versionها، timestampها، privacy/cardinality، provenance و mastery boundary. Gate deterministic باید روی TAXONOMY_REVIEW_REQUIRED بایستد، نه auto-promotion.

بعد dynamic-name mutation را بررسی کنید. lesson identifier را از name به object_ref منتقل کنید؛ legacy mapping record را نگه دارید تا history پاک نشود.

مرحلهٔ مستقل. حداقل چهار mutation را diagnose کنید: observed timestamp ناقص، rename بدون migration، completion→mastery inference و missing privacy class. برای هر مورد failed dimension، typed state، minimum repair و evidence تاریخی immutable را نام ببرید.

Transfer. mobile client زیر taxonomy v2 offline شده و وقتی v3 فعال است upload می‌کند. result را از changed evidence دوباره بسازید: v2 name/schema/producer semantics و event/observed time را حفظ کنید، برای v3 compatibility view migration provenance بدهید و هر baseline-answer reuse که meaning قدیمی را rewrite می‌کند رد کنید.

Verification و evidence

artifact اصلی MKN-020-T1 — Learning & Product Event Taxonomy Governance Contract v1 است و سه سناریو دارد: canonical baseline، dynamic-name/mastery shortcut نامعتبر و offline transfer پس از taxonomy revision.

Verification باید ثابت کند:

• هر ۲۱ critical dimension فریز‌شده visible است؛
• event name semantic identity دارد نه dynamic instance value؛
• event و observed timestamp جدا هستند؛
• taxonomy/schema/producer version مستقل قابل trace هستند؛
• privacy/cardinality و validation state صریح‌اند؛
• deprecation/replacement/migration معنای اصلی را پاک نمی‌کند؛
• derived metric پایین‌دست raw event است؛
• mastery بدون evidence جدا ممنوع می‌ماند؛
• missing evidence typed HOLD/REVIEW_REQUIRED می‌سازد؛
• transfer از changed evidence recompute می‌شود و baseline-oracle reuse را رد می‌کند.

Oracle deterministic همان Bible فریز‌شده + fixture synthetic visible است؛ نه hidden model reasoning و نه backend live analytics.

Assessment و transfer gate

S1 — retrieval. مرز owned درس Learning/Product Analytics Event Taxonomy و یک non-goal را توضیح بده. S2 — application. Learning & Product Event Taxonomy Governance Contract v1 را برای baseline synthetic بساز. S3 — diagnosis. stable event name را با dynamic name دارای lesson identifier جایگزین کن و broken dimension، consequence و minimal repair را مشخص کن. S4 — transfer. mobile client بعد از taxonomy revision eventها را upload می‌کند؛ event time/observed time، producer version، old meaning و migration provenance را حفظ کن و v2 event را بی‌صدا به v3 rewrite نکن.

Passing نیازمند identity/version/timestamp/provenance دقیق، negative evidence visible، decision محدود به evidence و recomputation واقعی در transfer است. Human reviewer باید بتواند نتیجه را بدون hidden model reasoning بازتولید کند.

منابع، freshness و مرز authority

FACT — 1EdTech Caliper Analytics. در 2026-09-13 بازبینی شد. صفحات جاری 1EdTech همچنان Caliper Analytics 1.2 و metric profile/common vocabulary برای نمایش سازگار learning activity را ارائه می‌کنند. Caliper سیاست mastery، KPI، privacy، retention یا taxonomy promotion MAKNOW را تعریف نمی‌کند.

FACT — OpenTelemetry semantic conventions for events. در 2026-09-13 بازبینی شد. صفحهٔ جاری با status Development، event را named point-in-time occurrence معرفی می‌کند، dynamic value در event name را منع می‌کند، event timestamp را زمان occurrence می‌داند و observed/received semantics را جدا نگه می‌دارد. این منبع learning interpretation MAKNOW را تعریف نمی‌کند.

INFERENCE — versioned semantic layer. MAKNOW از این patternها stable name، structured attribute، separation زمان وقوع/مشاهده و migration provenance نسخه‌دار را برای comparability producerها استنتاج می‌کند؛ این inference مهندسی است، نه نقل‌قول requirement برای MAKNOW.

DESIGN — event governance MAKNOW. namespace، critical dimensionها، privacy/cardinality class، validation state، deprecation/migration/replay، metric definition، retention و mastery boundary authority محلی هستند. تغییر منبع بیرونی باعث mutation بی‌صدای accepted package نمی‌شود.