חוזה אירועים קנוני בין Local Engine ל-Base44

1. מטרת המסמך

מסמך זה מגדיר חוזה אירועים קנוני, versioned ו-idempotent לתקשורת בין InvestIQ Local Engine לבין Base44. הוא נגזר ישירות מ-Local Engine Pilot Specification v0.31 המאושר, ואינו משנה את גבולות הסמכות שנקבעו בו.

המטרה היא למנוע payloads נקודתיים או שונים בין רכיבים. כל event הנשלח מה-Local Engine ל-Control Plane חייב לעבור דרך Envelope אחיד, validation אחיד וכללי compatibility אחידים.

2. סמכות וגבולות

• • Base44 נשאר Control Plane ו-System of Record.
• • Event הוא דיווח/עובדה תפעולית; הוא אינו מעניק סמכות ל-Risk, CIO/Decision או Execution.
• • Trigger event אינו Candidate, Decision או Trade.
• • אין AI/LLM ואין Broker integration במסגרת M1-M3.
• • אין credentials, tokens או secrets בתוך event.
• • אין hardcoded thresholds בתוך schema; threshold/policy values מגיעים מ-configuration/policy versioned.
• • כל הרחבה של event type, enum מחייב או breaking field מחייבת versioning ואישור לפי כללי מסמך זה.

3. עקרונות החוזה

4. Canonical Event Envelope v1

5. הבחנה בין Freshness של נתון לבין Health של Engine

בהתאם ל-v0.31, קיימים שני מושגים שונים ואסור לערבב ביניהם:

אין להסיק Engine Health רק מ-source_data_age_ms, ואין להשתמש ב-health state במקום גיל נתון המקור.

6. Event Registry v0.1

הוספת trigger_fired ל-v0.1 נועדה לאפשר למסמך הבא — Trigger Engine Specification — להישען על חוזה קנוני מאושר, בלי להמציא event חדש מחוץ ל-schema.

7. Event Type: health

הספים המדויקים ל-LIVE/STALE/OFFLINE/DEGRADED אינם מוגדרים כאן; הם יוגדרו ב-Heartbeat/Freshness Policy v0.1 ויישארו configurable/versioned.

8. Event Type: config_synced

SystemSettings הקיימים ב-Base44 הם מקור configuration/policy בפיילוט. Local Engine אינו רשאי להחליף threshold מוגדר ב-SystemSettings בערך hardcoded.

9. Event Type: metrics_snapshot

Cost/Credit metering ב-M1 הוא measurement בלבד. הוא אינו משנה תדירות, איכות או safety כדי לעמוד במכסה.

10. Event Type: warning

warning אינו משנה Risk/Decision/Execution state. HOLD כאן הוא תפעולי ל-capability המקומית בלבד, בהתאם לסמכות שהוגדרה ב-v0.31.

11. Event Type: scan_summary

scan_summary אינו מכיל Candidate/Decision/Trade ואינו מפעיל Execution. פרטי asset-level חריגים, אם יידרשו, יוגדרו בהרחבת schema מאושרת ולא כ-payload אד-הוק.

12. Event Type: trigger_fired

trigger_fired הוא עובדה תפעולית בלבד. אין בו field מסוג action=BUY/SELL, order, trade_state או decision authority.

13. Idempotency, Dedup ו-Retry

• • event_id חדש נוצר פעם אחת עבור event logical instance ונשמר לאורך retry.
• • idempotency_key נשאר זהה בכל retry של אותה עובדה לוגית.
• • sent_at רשאי להשתנות בכל ניסיון שליחה; occurred_at אינו משתנה.
• • Base44/consumer חייב לשמור dedup record לפי idempotency_key או event_id בהתאם ל-event type.
• • duplicate delivery חייב להחזיר acknowledgement idempotent ולא ליצור duplicate side effect.
• • retry policy עצמה אינה מוגדרת במסמך schema; היא תישען על M1 reliability rules ו-Acceptance Plan.
• • event שנדחה בגלל schema violation אינו "מתוקן במקום"; producer יוצר event חדש רק לאחר תיקון המקור, עם trace/correlation מתאים.

14. Timestamp, Ordering ו-Clock Skew

• • כל timestamp הוא UTC ISO-8601 עם millisecond precision לפחות.
• • occurred_at מייצג זמן עובדה; sent_at מייצג זמן transport.
• • סדר arrival אינו מבטיח סדר occurrence. consumer חייב להשתמש ב-occurred_at + correlation/context ולא ב-arrival order בלבד.
• • clock_skew_ms נמדד ומדווח ב-health. חריגה מהסף העתידי תוביל ל-DEGRADED/HOLD לפי Heartbeat/Freshness Policy.
• • יעד התכנון הראשוני של 5 שניות נשאר non-binding עד Acceptance Test Plan.

15. Validation Rules

16. Versioning & Compatibility

• • schema_version בפורמט major.minor. גרסת envelope הראשונה המאושרת תהיה 1.0.
• • Minor change מותר רק כאשר הוא backward-compatible, כגון optional field חדש.
• • Major change נדרש למחיקה/שינוי משמעות/שינוי type/הפיכת optional ל-required או שינוי enum שאינו backward-compatible.
• • Producer ו-consumer חייבים לדווח supported major versions.
• • במהלך rollout ניתן לתמוך זמנית ביותר מ-major אחד; deprecation דורש חלון מעבר ותיעוד.
• • אין silent coercion של type לא תקין.

17. Security & Privacy

• • אין API keys, passwords, access tokens, refresh tokens, broker credentials או OS secrets באירועים.
• • user_id הוא internal identifier; אין צורך בשם, אימייל או מידע אישי לצורך schema זה.
• • settings_digest אינו כולל secret values.
• • payload logging כפוף ל-redaction rules; raw secret לעולם אינו נרשם.
• • Transport נדרש להיות TLS בהתאם ל-v0.31.
• • Authentication של Engine Identity הוא דרישת M1 אך credential format אינו חלק מה-event schema.

18. Delivery Acknowledgement — חוזה מינימלי

HTTP/API transport details, endpoint paths ו-auth headers אינם ננעלים במסמך זה; הם יוגדרו ב-M1 implementation contract. החוזה הלוגי של acknowledgement כן ננעל כאן.

19. דוגמאות קנוניות

{
  "event_id": "evt-uuid-001",
  "event_type": "health",
  "schema_version": "1.0",
  "user_id": "usr-internal-01",
  "engine_id": "eng-01",
  "source": "local_engine",
  "occurred_at": "2026-09-09T07:30:00.000Z",
  "sent_at": "2026-09-09T07:30:00.120Z",
  "correlation_id": "health-20260909-0730",
  "idempotency_key": "eng-01:health:20260909T073000Z",
  "severity": "INFO",
  "status": "LIVE",
  "source_data_age_ms": null,
  "engine_version": "pilot-m1-build",
  "config_version": "cfg-vX",
  "policy_version": "pol-vX",
  "payload": {
    "health_state": "LIVE",
    "service_uptime_sec": 3600,
    "last_successful_sync_at": "2026-09-09T07:29:58.000Z",
    "queue_depth": 0,
    "storage_state": "OK",
    "clock_skew_ms": 120,
    "reason_code": null,
    "recovery_action": null
  }
}

{
  "event_id": "evt-uuid-002",
  "event_type": "trigger_fired",
  "schema_version": "1.0",
  "user_id": "usr-internal-01",
  "engine_id": "eng-01",
  "source": "trigger_engine",
  "occurred_at": "2026-09-09T08:00:00.000Z",
  "sent_at": "2026-09-09T08:00:00.080Z",
  "correlation_id": "scan-cycle-example",
  "idempotency_key": "trigger-example-instance",
  "severity": "WARNING",
  "status": "FIRED",
  "source_data_age_ms": 1500,
  "engine_version": "pilot-m3-build",
  "config_version": "cfg-vX",
  "policy_version": "pol-vX",
  "payload": {
    "trigger_id": "trg-example",
    "trigger_instance_id": "tri-example",
    "trigger_category": "MARKET",
    "reason_code": "THRESHOLD_CROSSED",
    "reason_text": "Example only",
    "policy_version": "pol-vX",
    "threshold_snapshot": { "example_threshold": "configured-value" },
    "observed_values": { "example_value": "observed-value" },
    "priority": "NORMAL",
    "dedup_key": "dedup-example",
    "cooldown_until": null
  }
}

הערה: cfg-vX / pol-vX / pilot-m1-build הם placeholders תיעודיים בלבד; אין במסמך זה קביעה של גרסה תפעולית אמיתית. הדוגמה אינה מגדירה threshold, symbol, BUY/SELL או פעולה מסחרית; היא מדגימה את מבנה החוזה בלבד.

20. Error/Failure Events

v0.11 משתמש ב-warning + health לצורך failure reporting ואינו מוסיף event_type נפרד בשם error. הסיבה: למנוע כפילות בין severity לבין event type בשלב M1.

21. Derivation Trace

New Requirement המסומן במסמך זה: acknowledgement logical contract ו-schema compatibility rules מפורטים. הם נגזרים פונקציונלית מדרישות reliability/idempotency/versioning של v0.31, אך לא פורטו שם ברמת שדות; לכן הם מובאים כאן לאישור מפורש כחלק מ-G-EVENT.

22. שאלות לצוות לפני G-EVENT

1. האם Envelope fields מלאים ומינימליים, או שיש שדה חובה נוסף שחסר לפני M1?
2. האם source_data_age_ms במילישניות הוא היחידה הנכונה, או להעדיף timestamp של source ולחשב age בצרכן?
3. האם event types: health, config_synced, metrics_snapshot, warning, scan_summary, trigger_fired מספיקים ל-M1-M3?
4. האם נכון להשאיר error כ-severity/health-warning ולא ליצור event_type נפרד בשלב זה?
5. האם ACK logical contract צריך להינעל כבר ב-v0.1 כפי שמוצע?
6. האם user_id + engine_id מספיקים isolation/audit לפיילוט יחיד בלי להוסיף account_id בשלב M1?
7. האם metrics_snapshot צריך לכלול base44_credit_units nullable, או להסתפק ב-base44_calls_count עד שקיימת מדידת credits אמינה?
8. האם threshold_snapshot ב-trigger_fired צריך להכיל רק ערכים רלוונטיים ל-trigger ולא policy מלא? ההמלצה במסמך: רק הערכים הרלוונטיים.
9. האם קיימת דרישת retention/audit ב-Base44 שיש לנעול כבר ברמת schema, או להשאיר ל-M1 implementation/Acceptance Plan?
10. האם יש blocker שמונע מעבר ל-Trigger Engine Specification v0.1 לאחר אישור מסמך זה?

23. Gate G-EVENT

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