מפרט מנוע טריגרים קנוני — M3

1. מטרת המסמך

מסמך זה מגדיר את Trigger Engine של InvestIQ: מנוע דטרמיניסטי, configurable ו-versioned שמזהה תנאים חריגים/משמעותיים ומפיק trigger_fired event קנוני בהתאם ל-Canonical Event Schema v0.11.

המנוע אינו מחליט אם לקנות/למכור, אינו יוצר Trade, אינו משנה Decision/CIO ואינו עוקף Risk Gate. תפקידו היחיד הוא להפוך Observation שעומד בתנאי policy מאושר ל-Event מתועד, ניתן לשחזור ולביקורת.

2. מסמכים מחייבים ותלות

במקרה של סתירה, מסמכי היסוד המאושרים וגבולות הסמכות גוברים. שינוי Schema אינו נעשה במסמך זה.

3. Out-of-Scope

• • אין AI/LLM במנוע M3.
• • אין Broker connectivity או order creation.
• • אין Candidate, CIO/Decision או Trade creation.
• • אין שינוי Risk Gate.
• • אין שינוי System of Record; Base44 נשאר System of Record.
• • אין hardcoded operational thresholds.
• • אין production enforcement ב-M3; מצב M3 הוא SHADOW.
• • אין News interpretation ב-M3; NEWS category שמורה לחיבור עתידי לאחר milestone מתאים.
• • אין שינוי Event Schema v0.11 מתוך הקוד או מתוך Trigger configuration.

4. עקרונות מחייבים

5. Trigger Lifecycle

FALSE אינו failure. UNKNOWN נוצר כאשר אין די מידע אמין להכרעה, ובמקרה כזה אין trigger_fired; הסיבה מתועדת.

6. Trigger Definition — חוזה לוגי

7. Trigger Categories

הפעלת category או condition חדש דורשת configuration/policy מאושרים ובדיקת compatibility; אין הרחבה אד-הוק.

8. Condition Evaluators

הרשימה היא Registry ראשוני. evaluator חדש הוא שינוי מפרט/registry, לא string חופשי שמכניס לוגיקה בלתי מבוקרת.

9. Evaluation Context

10. Thresholds & Policy Governance

• • אין threshold מספרי מחייב במסמך זה.
• • כל threshold מגיע מ-SystemSettings/config/policy המאושרים ב-Base44 ומסונכרן ל-Local Engine.
• • כל trigger_fired שומר threshold_snapshot רק לערכים שהשתתפו בפועל בהחלטת trigger.
• • שינוי threshold יוצר config/policy version חדש או versioned revision לפי מנגנון ה-Config המאושר.
• • Local Engine אינו רשאי להמציא default תפעולי כאשר ערך מחייב חסר. Missing/invalid policy → evaluation UNKNOWN + warning.
• • Policy rollback חייב להיות traceable; events לאחר rollback נושאים את הגרסה הפעילה בפועל.

11. Debounce

Debounce נועד למנוע trigger על spike רגעי כאשר policy דורש persistence. הוא אינו משנה threshold אלא מגדיר כמה זמן/דגימות התנאי חייב להישאר TRUE.

דגימה UNKNOWN שוברת רצף אלא אם policy עתידי מאושר מגדיר אחרת.

12. Dedup & Logical Trigger Instance

• • trigger_instance_id מזהה fire יחיד לאחר qualification.
• • dedup_key נגזר באופן דטרמיניסטי מ-trigger_id + subject_key + logical condition window/context.
• • retry של אותו trigger_fired שומר event_id ו-idempotency_key בהתאם ל-Canonical Event Schema v0.11.
• • Dedup של Trigger Engine קודם ל-event delivery idempotency; אלה שתי שכבות שונות.
• • duplicate condition בתוך אותו dedup context אינו מפיק trigger_fired נוסף; counter של suppression מתעד זאת.

13. Cooldown

Cooldown מתחיל לאחר FIRE מוצלח לוגית, לא לאחר ACK transport. מטרתו למנוע fire חוזר תכוף של אותה תופעה.

CRITICAL priority אינו עוקף cooldown אלא אם policy version מאושרת מגדירה override מפורש.

14. Rate Limiting

• • Rate limit נועד להגן על queue/Base44 מפני event storm, לא להסתיר מצב שוק.
• • Rate limiting מתבצע לאחר condition/debounce/dedup/cooldown.
• • suppressed event אינו נעלם: counter + reason נרשמים ב-metrics/audit.
• • CRITICAL אינו פטור אוטומטית מ-rate limit; מדיניות חריגה חייבת להיות מפורשת.
• • אם rate limit עצמו גורם לאובדן visibility מהותי, engine עובר DEGRADED ומפיק warning/health בהתאם.

15. Freshness Gate

• • Trigger המבוסס על market/data input לא יוערך כ-TRUE אם freshness policy מגדירה את הנתון כלא כשיר.
• • stale input → UNKNOWN או STALE_DATA trigger ייעודי, בהתאם להגדרה; אין שימוש בנתון ישן כאילו הוא live.
• • source_data_age_ms הוא per-observation; Engine Health הוא מצב מערכתי נפרד.
• • הספים המדויקים יינעלו ב-Heartbeat/Freshness Policy v0.1 ולא במסמך זה.

16. trigger_fired Mapping ל-Canonical Event Schema v0.11

payload.policy_version חייב להתאים ל-envelope.policy_version; mismatch הוא REJECT_SCHEMA בהתאם ל-v0.11.

17. Suppression & Audit

לא כל suppression מפיק warning event. כולם נמדדים ב-Metrics/Audit; warning מופק כאשר מדובר בכשל תפעולי/איכותי שמחייב visibility.

18. Metrics / Telemetry

Metrics אלה משתלבים ב-metrics_snapshot של Canonical Event Schema. אין חובה שכל metric יהיה field top-level; payload metrics יוכל להתרחב backward-compatibly בהתאם לאישור.

19. Failure Modes & Safe Behavior

20. Shadow Mode — M3

• • כל trigger ב-M3 פועל במצב SHADOW.
• • אין שינוי Candidate/Decision/Trade/Portfolio/Execution כתוצאה מ-trigger_fired.
• • התוצאות מושוות להתנהגות/נתוני הייחוס המאושרים לצורך Quality Baseline.
• • False positives/false negatives, latency, coverage ו-suppression reasons נמדדים.
• • המעבר מ-SHADOW ל-PRODUCTION/ENFORCED אינו חלק מ-G-TRIGGER ודורש Gate עתידי מפורש.

21. Acceptance Categories ל-Trigger Engine

הספים המספריים ו-test cases הסופיים יינעלו ב-Pilot Acceptance Test Plan v0.1.

22. דוגמת Trigger Definition — תיעודית בלבד

{
  "trigger_id": "trg-example-market-change",
  "name": "Example configured market change",
  "enabled": true,
  "category": "MARKET",
  "scope": {
    "market": "EXAMPLE",
    "subjects": "configured-watchlist"
  },
  "condition_type": "PERCENT_CHANGE",
  "parameters": {
    "field": "price",
    "reference": "configured-reference",
    "percent": "configured-value",
    "window": "configured-window"
  },
  "priority": "NORMAL",
  "debounce_policy": {
    "mode": "CONSECUTIVE_SAMPLES",
    "required_samples": 0,
    "max_sample_gap_ms": 0
  },
  "cooldown_policy": {
    "mode": "FIXED_DURATION",
    "duration_ms": 0,
    "scope": "TRIGGER_SUBJECT"
  },
  "rate_limit_policy": {
    "max_fires": 0,
    "window_ms": 0
  },
  "freshness_policy_ref": "freshness-policy-ref",
  "policy_version": "pol-vX",
  "config_version": "cfg-vX",
  "effective_from": "2026-09-09T00:00:00.000Z",
  "effective_until": null
}

כל הערכים בדוגמה הם placeholders. אין בדוגמה threshold, interval או limit תפעולי מאושר. ערכים מספריים מופיעים כ-0 להמחשת ה-type הצפוי (v0.11).

23. Derivation Trace

New Requirement מפורט במסמך זה: Trigger Definition contract, evaluator registry, suppression reason registry וסדר lifecycle מלא. אלה פירוט טכני הנדרש ליישום הדרישות המאושרות, ומובאים לאישור מפורש במסגרת G-TRIGGER.

24. שאלות לצוות לפני G-TRIGGER

1. האם Trigger Definition contract כולל את כל השדות הדרושים ל-M3 ללא הכנסת סמכות מסחרית?
2. האם evaluator registry הראשוני מספיק ל-M3, או חסר evaluator דטרמיניסטי חיוני?
3. האם category STATE_RISK צריך להישאר מוגבל/Shadow כפי שמוגדר, כדי למנוע חפיפה עם Risk Gate?
4. האם NEWS צריך להישאר Reserved בלבד ב-M3?
5. האם סדר lifecycle: Validate → Evaluate → Debounce → Dedup → Cooldown → Rate Limit → Fire נכון?
6. האם cooldown צריך להתחיל ב-FIRE הלוגי ולא ב-ACK transport כפי שמוצע?
7. האם dedup_key scope צריך להינעל במסמך זה או להיות evaluator-specific לפי policy?
8. האם suppression registry מספק לצורך audit ו-Acceptance Plan?
9. האם metrics המוגדרים מספיקים למדידת false positives/false negatives, latency ו-coverage?
10. האם קיים blocker לפני מעבר ל-Heartbeat/Freshness Policy v0.1?

25. Gate G-TRIGGER

26. החלטה מוצעת