מדיניות חיות, כשירות ועדכניות — Local Engine Pilot

1.מטרת המסמך

מסמך זה מגדיר כיצד InvestIQ קובע ומדווח האם Local Engine חי, מחובר, כשיר, מתאושש, או פועל עם מידע שאינו עדכני. המדיניות מפרידה במפורש בין Engine Health לבין Source Data Freshness, בהתאם למסמכים המחייבים.

2.מסמכים מחייבים

מסמך זה אינו משנה Event Schema או Trigger Schema. הוא מגדיר policy semantics ו-state transitions שעליהם הרכיבים נשענים.

3.Out-of-Scope

• •אין שינוי Risk/Decision/Execution authority.
• •אין Broker connectivity או AI/LLM.
• •אין hardcoded thresholds בקוד.
• •אין קביעה סופית של SLA מוצר רב-משתמשים; זהו Pilot Policy.
• •אין הגדרה של market-data provider סופי.
• •אין קביעה ש-Engine Health תקין מבטיח ש-Source Data טרי; אלה שני צירים נפרדים.
• •אין automatic fallback ל-Base44 ללא health/freshness check של ה-fallback עצמו.

4.שני צירי כשירות נפרדים

Engine יכול להיות LIVE כאשר feed מסוים stale; במקרה כזה capability התלויה באותו feed אינה LIVE. מנגד, נתון אחרון יכול להיות צעיר אך Engine שחדל לשלוח heartbeat אינו נחשב LIVE.

5.Engine Health States

6.Pilot Policy Defaults — configurable, לא hardcoded

15/60 דקות אינם קבועים בקוד ואינם SLA סופי. הם defaults versioned. ה-heartbeat interval עצמו חייב להיות קצר משמעותית מ-stale_after כדי לאפשר detection אמין; היחס המספרי יינעל ב-Acceptance Test Plan.

7.State Transition Rules

8.מי קובע את מצב ה-Engine?

קיימים שני observers: Local Engine מדווח health event; Base44/Control Plane מודד באופן עצמאי את גיל ה-heartbeat האחרון. מצב התצוגה/ניהול ב-Control Plane אינו יכול להסתמך רק על state שה-Engine דיווח על עצמו.

עיקרון: Health הוא evidence-based. במקרה של ספק, אין שדרוג אופטימי של state.

9.Heartbeat Event Requirements

Heartbeat אינו "ping" ריק; הוא snapshot מינימלי של כשירות המנוע.

10.Source Data Freshness Model

אין להמציא source timestamp. כאשר מקור אינו מספק timestamp אמין, יש לתעד את בסיס החישוב החלופי ולהבדיל אותו מ-source-native timestamp.

11.Freshness Classification

AGING הוא classification של נתון בלבד ואינו Engine Health state.

12.Freshness Policy Dimensions

סף freshness אינו מספר גלובלי יחיד. הוא versioned policy שיכול להיות שונה לפי:

• •data source / adapter;
• •market (US / IL);
• •market state (open / closed / pre/post אם רלוונטי ומאושר);
• •capability (scan, trigger, display, reconciliation וכו׳);
• •data type (price, volume, indicator, config, news metadata בעתיד);
• •criticality.

כל combination שאינו מכוסה ב-policy מאושר → UNKNOWN, לא default סמוי.

13.Market Closed / Scheduled Silence

היעדר market ticks כאשר השוק סגור אינו הופך אוטומטית Engine ל-STALE. Engine Health נמדד באמצעות heartbeat. Freshness של market data מוערכת לפי market-state-aware policy.

לכן, נתון closing price יכול להיות תקין לתצוגה/ניתוח מסוימים כשהשוק סגור אך לא כשיר ל-capability הדורשת live quote. ה-policy חייב להגדיר זאת במפורש.

14.Clock Synchronization

• • Local Engine נדרש לסנכרון שעון מול מקור זמן אמין של מערכת ההפעלה/NTP-equivalent.
• • clock_skew_ms מדווח ב-health.
• • חריגה מסף מאושר אינה "מתוקנת" על ידי שינוי timestamps באירועים.
• • Clock skew מהותי → DEGRADED/HOLD ל-capabilities התלויות בסדר/זמן עד recovery.
• • יעד 5 שניות הוא planning target בלבד עד נעילת Acceptance Plan.

15.Recovery Protocol

רק לאחר PASS של כל הבדיקות הנדרשות ל-capability ניתן לעבור RECOVERING → LIVE. Failure שאינו רלוונטי לכל המנוע יכול להשאיר Engine DEGRADED עם HOLD נקודתי במקום OFFLINE.

16.DEGRADED/HOLD Semantics

HOLD במסמך זה הוא תפעולי ומקומי בלבד. הוא אינו Trade HOLD, אינו Decision HOLD ואינו משנה Risk Gate.

17.Control Plane Watchdog

• •Base44 שומר last_received_health_at לכל engine_id.
• •Watchdog מחשב evidence age באופן עצמאי.
• •Watchdog מחיל stale_after/offline_after מה-policy version הפעילה.
• •absence-of-heartbeat מזהה גם crash/panic שבו Engine לא הצליח לשלוח warning.
• •Watchdog אינו מפעיל execution fallback אוטומטי.
• •אם בעתיד מופעל fallback, עליו לעבור health/freshness check משלו לפני שימוש.

18.Event & Warning Behavior

State transition משמעותי חייב להיות auditable גם כאשר מקור ה-transition הוא Watchdog ולא event מה-Engine.

19.Metrics / Telemetry

המדדים ישולבו ב-metrics_snapshot בהתאם ל-Canonical Event Schema v0.11. הרחבת payload תהיה backward-compatible ומאושרת.

20.Failure Modes

21.Restart & Persistence

• •restart אינו מאפס evidence היסטורי ב-Control Plane.
• •Local Engine טוען persisted queue/state ומתחיל ב-RECOVERING, לא LIVE.
• •Trigger state persistence נשלט לפי Trigger Engine v0.11.
• •service_uptime_sec מתאפס לאחר restart; engine_id נשאר יציב.
• •recovery event chain חייב לאפשר לזהות restart מתוכנן מול crash ככל שהראיות מאפשרות.
• •אין להסתיר gap באמצעות backdated heartbeat.

22.Policy Versioning & Runtime Change

• •שינוי heartbeat/freshness policy יוצר version חדש/מאושר.
• •כל health event נושא policy_version/config_version הפעילים.
• •Control Plane חייב לדעת איזו policy חלה בעת קביעת state.
• •שינוי stale/offline/freshness threshold אינו משכתב היסטוריה; הוא חל מ-effective_from.
• •Policy update בזמן RECOVERING מחייב הערכה מחדש תחת הגרסה החדשה לפני LIVE.
• •Policy/config update בזמן LIVE מחייב re-verification תחת הגרסה החדשה. מרגע effective_from אין להמשיך להציג LIVE על סמך verification של הגרסה הישנה בלבד; Engine עובר RECOVERING לצורך checks הרלוונטיים, וחוזר ל-LIVE רק לאחר PASS. שינוי שאינו משפיע על health/freshness יכול להיות מסווג מראש כ-non-health-impacting ורק אז אינו מחייב transition, אך הסיווג חייב להיות versioned/auditable.
• •Rollback policy traceable; אין ערבוב thresholds משתי גרסאות באותה evaluation.

23.דוגמת Policy — תיעודית בלבד

{
  "policy_id": "health-freshness-pilot",
  "policy_version": "pol-vX",
  "effective_from": "2026-09-09T00:00:00.000Z",
  "heartbeat": {
    "interval_ms": null,
    "stale_after_ms": 900000,
    "offline_after_ms": 3600000
  },
  "clock": {
    "target_max_skew_ms": 5000
  },
  "recovery": {
    "success_samples": null,
    "min_duration_ms": null
  },
  "freshness_rules": [
    {
      "source": "configured-source",
      "market": "US",
      "market_state": "OPEN",
      "capability": "trigger",
      "data_type": "price",
      "fresh_max_age_ms": null,
      "aging_after_ms": null
    }
  ]
}

900000/3600000 ו-5000 משקפים את defaults/יעדי התכנון שכבר תועדו במסמכים המאושרים; הם אינם hardcoded. ערכי null חייבים להינעל ב-policy/Acceptance Plan לפני execution.

24.Acceptance Categories

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

25.Derivation Trace

New Requirement מפורט במסמך זה: Control Plane Watchdog arbitration, FRESH/AGING/STALE/UNKNOWN data classification, recovery checklist ו-market-state-aware freshness dimensions. אלה נגזרים מהדרישה למדידה אמינה של health/freshness ומובאים לאישור מפורש במסגרת G-HEALTH.

26.שאלות לצוות לפני G-HEALTH

1. האם חמשת Engine Health states והמעברים ביניהם מלאים וברורים?
2. האם נכון שכל חזרה מ-STALE/OFFLINE/DEGRADED תעבור RECOVERING ללא חריג?
3. האם 15/60 דקות נשארים defaults תכנוניים בלבד עד Acceptance Plan, כפי שנקבע?
4. איזה heartbeat_interval נדרש לפיילוט כדי לספק detection אמין בלי צריכת Base44 מיותרת?
5. האם Control Plane Watchdog צריך להיות הסמכות המחמירה במקרה של סתירה מול self-reported health?
6. האם FRESH/AGING/STALE/UNKNOWN מספקים ל-data freshness?
7. האם freshness policy dimensions מפורטים מספיק לשוק US/IL ול-market open/closed?
8. האם recovery checklist R1-R8 מלא?
9. האם מצב Base44 unavailable אך Local Engine חי צריך להיות DEGRADED כברירת מחדל, או להיקבע per-capability/policy כפי שמוצע?
10. האם יש blocker לפני כתיבת Pilot Acceptance Test Plan v0.1?

27.Gate G-HEALTH

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