CH5-003 · DecisionContextSnapshot, מזהי מחזור וקורלציה

כיום אין תמונת מצב קפואה של מחזור החלטה. סוכנים צורכים נתונים חיים שעשויים להשתנות באמצע המחזור, ואין מזהה יחיד החוצה את כל המערכת — Candidate, Analysis, Trade, Order, Fill ו-Position אינם מקושרים למחזור אחיד. כתוצאה, לא ניתן לשחזר מחזור החלטה מבלי לחפש ידנית בלוגים, שני סוכנים באותו מחזור עלולים לצרוך גרסאות שונות של מחיר, ושינוי מחיר או הגדרה באמצע מחזור אינו מתועד כשינוי מהותי. CH5-001 זיהה זאת כפער קריטי: אין DecisionContextSnapshot, אין decision_cycle_id, ואין correlation_id.

להבטיח שכל החלטה ניתנת לשחזור מתוך תמונת מצב קפואה אחת ומזהים החוצים את כל המערכת. בתחילת כל מחזור החלטה ייווצרו: (א) חמישה Snapshots קפואים — Market, Portfolio, Policy, System ו-DecisionContext המקשר ביניהם; (ב) decision_cycle_id יחיד; (ג) correlation_id עקבי. כל ישות במסלול ההחלטה תקושר לשני המזהים, וניתן יהיה לשחזר את המחזור המלא ללא חיפוש ידני ב-Log. CIO Shadow וניתוח ההחלטה יפעלו על ה-Snapshot הקפוא — אך לפני יצירת Order חייב להתבצע Risk Gate עצמאי ועדכני הבודק מחדש מול המצב החי. ה-Snapshot הוא ראיית ההחלטה ואינו מחליף בדיקת סיכון עדכנית לפני ביצוע.

הגדרת חמישה סוגי Snapshot: Market, Portfolio, Policy, System ו-DecisionContext (המקשר ביניהם).

יצירת decision_cycle_id (מזהה עסקי קבוע למחזור אחד) ו-correlation_id (מזהה Trace החוצה רכיבים ואירועים) בתחילת כל מחזור החלטה.

מחזור החלטה נוצר רק על-ידי Orchestrator או מקור החלטה מוסמך — לא על-ידי refreshPortfolioPrices (רענון מחירים מקבל correlation_id תפעולי ו-data_as_of בלבד).

Retry של אותו מחזור אינו יוצר Snapshots כפולים — משתמש באותו decision_cycle_id ובאותם Snapshots (Idempotency Key). מחזור חדש מקבל מזהים חדשים.

אירוע ברוקר מאוחר שומר את מזהה המחזור המקורי ומקבל קשר ל-Reconciliation Case.

קישור כל ישויות המסלול לשני המזהים: Candidate, AnalysisOutput, Decision, RiskResult, Trade, Order, Fill/BrokerEvent, PositionUpdate, AuditEvent.

שמירת source_refs, data_as_of, schema_version, quality_summary, expires_at ו-content_hash בכל Snapshot.

מניעת ערבוב גרסאות או מחירים בין סוכנים באותו מחזור — כולם צורכים מאותו Market Snapshot.

CIO Shadow וניתוח ההחלטה פועלים על ה-Snapshot הקפוא — אך לפני יצירת Order חייב להתבצע Risk Gate עצמאי ועדכני.

Risk Gate לפני Order בודק מחדש: מזומן והון משוריין, פוזיציות וחשיפות, Global Freeze והגנות, מצב שוק, Trade Validity וסטיית מחיר — מול המצב החי, לא מול ה-Snapshot.

בנייה אטומית של חמשת ה-Snapshots: BUILDING → PUBLISHED או FAILED. Unique Constraint ו-Idempotency Key על decision_cycle_id. Snapshot חלקי אינו מתפרסם.

כללי שינוי מחיר באמצע מחזור: TTL ו-Max Data Age; סף שינוי מהותי לפי Trade Validity; שינוי מדיניות סיכון או Global Freeze מבטל מיידית את כשירות המחזור (SUPERSEDED).

Immutability ומודל עדכון: ארבעת ה-Snapshots המרכיבים (Market, Portfolio, Policy, System) הם Append-Only — אין עדכון לאחר יצירה. DecisionContextSnapshot ניתן לעדכון ב-CAS רק בעודו במצב BUILDING (מעבר build_status: BUILDING→PUBLISHED או BUILDING→FAILED). לאחר מעבר ל-PUBLISHED או FAILED הוא הופך Immutable — אין עדכון נוסף. קוראים (סוכנים, CIO Shadow, Risk Gate) רשאים לצרוך Snapshots רק כאשר ה-DecisionContextSnapshot המקשר הוא PUBLISHED — Snapshot במצב BUILDING או FAILED אינו זמין לקריאה עסקית.

computed_status: status (FRESH/STALE/EXPIRED/SUPERSEDED) הוא מצב מחושב על בסיס: created_at ו-expires_at; השוואת policy_hash הנוכחי לעבר Policy Snapshot; מצב Global Freeze; SnapshotInvalidationEvent או מחזור מחליף שנוצר. הוא אינו נשמר בישות Append-Only — הוא מחושב בזמן קריאה או נרשם כאירוע נפרד (SnapshotInvalidationEvent).

חישוב Hash קנוני: Canonical JSON עם סידור שדות קבוע; סדר קבוע של ארבעת ה-Snapshot Hashes; hash_algorithm ו-hash_version; הפרדה בין Content Hash לבין מזהים וזמנים משתנים; זמנים ב-UTC.

בדיקת תוקף: Snapshot שפג תוקפו חוסם פתיחת פוזיציה והגדלת חשיפה, אך אינו חוסם יציאה, צמצום או פעולת חירום מאושרת.

כלי שחזור: שאילתה לפי decision_cycle_id מחזירה את כל הישויות הקשורות ללא חיפוש ידני ב-Log.

Shadow mode: CH5-003 פועל זמנית על מקורות As-Is עד למימוש CH5-004/005. תיוג data_source=AS_IS; מעבר ל-CANONICAL מחייב Feature Flag נפרד.

Feature Flag להפעלה מדורגת: Shadow (השוואה בלבד) → קריאה קנונית → כיבוי וחזרה למסלול קריאה קודם (לא מסלול שעוקף הגנות).

Snapshot שפורסם אינו משתנה — שינוי מהותי מחייב מחזור חדש ו-Snapshot חדש.

ה-Snapshot הוא ראיית ההחלטה ואינו מחליף בדיקת סיכון עדכנית לפני ביצוע (Risk Gate עדכני לפני Order).

CIO נשאר Shadow — אין העברת סמכות ל-CIO או לסוכן כלשהו.

אין Candidate→Order ישיר — כל המסלול נשמר ומתועד.

אין לשמור Secrets, Tokens או נתוני הרשאה בתוך Snapshot.

אין שינוי לוגיקת השקעה או שליחת Order חי במסגרת מפרט זה.

Snapshot אינו מחליף Audit מחייב (AuditEvent, CH5-005) — הוא מקושר אליו.

status (FRESH/STALE/EXPIRED/SUPERSEDED) אינו יכול להשתנות בישות Append-Only — הוא מצב מחושב (created_at, expires_at, policy_hash נוכחי מול Policy Snapshot, Global Freeze, SnapshotInvalidationEvent) או אירוע נפרד.

ארבעת ה-Snapshots המרכיבים הם Append-Only. DecisionContextSnapshot ניתן לעדכון ב-CAS רק ב-BUILDING; לאחר PUBLISHED/FAILED הוא Immutable. קוראים צורכים Snapshots רק כשה-DecisionContext המקשר הוא PUBLISHED.

כיבוי Feature Flag אינו רשאי להחזיר למסלול ישן שעוקף Risk Gate, State Machine או Audit — החזרה למסלול קריאה קודם בלבד; נתוני Snapshot שנכתבו נשמרים.

כל מחזור חדש מקבל decision_cycle_id (מזהה עסקי קבוע למחזור אחד) ו-correlation_id (מזהה Trace החוצה רכיבים).

Retry של אותו מחזור אינו יוצר Snapshots כפולים — משתמש באותו decision_cycle_id ובאותם Snapshots.

מחזור חדש מקבל מזהים חדשים.

אירוע ברוקר מאוחר שומר את מזהה המחזור המקורי ומקבל קשר ל-Reconciliation Case.

refreshPortfolioPrices אינו יוצר מחזור החלטה — הוא מקבל correlation_id תפעולי ו-data_as_of בלבד.

בנייה אטומית: חמשת ה-Snapshots נבנים כ-BUILDING → PUBLISHED או FAILED. Snapshot חלקי אינו מתפרסם.

Unique Constraint ו-Idempotency Key על decision_cycle_id — Retry אינו יוצר עותקים.

כל ארבעת ה-Snapshots המרכיבים — Market, Portfolio, Policy ו-System — קיימים או שהמחזור נחסם.

נוצר DecisionContextSnapshot המקשר בין ארבעת ה-Snapshots עם content_hash משלו.

שני סוכנים באותו מחזור צורכים אותה גרסת Market Snapshot — אין ערבוב גרסאות.

לפני יצירת Order מתבצע Risk Gate עצמאי ועדכני הבודק מחדש: מזומן והון משוריין, פוזיציות וחשיפות, Global Freeze והגנות, מצב שוק, Trade Validity וסטיית מחיר — מול המצב החי, לא מול ה-Snapshot.

אי-עמידה ב-Risk Gate חוסם יצירת Order, אך אינה חוסמת יציאה, צמצום או פעולת חירום מאושרת.

שחזור לפי decision_cycle_id מציג את כל הישויות (Candidate, Analysis, Decision, RiskResult, Trade, Order, Fill, PositionUpdate, AuditEvent) ללא חיפוש ידני ב-Log.

TTL ו-Max Data Age מוגדרים לכל סוג Snapshot; חריגה מ- expires_at מסמנת את ה-Snapshot כ-STALE/EXPIRED.

סף שינוי מהותי מוגדר לפי Trade Validity (price_drift_threshold) — חריגה מחייבת בדיקה מחדש, לאו דווקא Snapshot חדש.

שינוי מדיניות סיכון או Global Freeze מבטל מיידית את כשירות המחזור (SUPERSEDED) — נדרש מחזור חדש.

לפני Order מתבצעת בדיקת סטיית מחיר מול השוק העדכני (לא מול ה-Snapshot).

Snapshot חסר או פג תוקף חוסם פתיחת פוזיציה והגדלת חשיפה, אך אינו חוסם יציאה, צמצום או פעולת חירום מאושרת.

status (FRESH/STALE/EXPIRED/SUPERSEDED) הוא מצב מחושב על בסיס: created_at, expires_at, השוואת policy_hash נוכחי מול Policy Snapshot, מצב Global Freeze, SnapshotInvalidationEvent או מחזור מחליף — אינו נשמר בישות Append-Only.

ארבעת ה-Snapshots המרכיבים הם Append-Only. DecisionContextSnapshot ניתן לעדכון ב-CAS רק ב-BUILDING; לאחר PUBLISHED/FAILED הוא Immutable. קוראים צורכים Snapshots רק כשה-DecisionContext המקשר הוא PUBLISHED.

חישוב Hash כולל: Canonical JSON עם סידור שדות קבוע; סדר קבוע של ארבעת ה-Snapshot Hashes; hash_algorithm ו-hash_version; הפרדה בין Content Hash למזהים/זמנים משתנים; זמנים ב-UTC.

Shadow comparison בין הנתיב החדש לקיים עומד בסבילות המאושרת.

CIO Shadow וניתוח ההחלטה פועלים על ה-Snapshot בלבד — לא מנתונים חיים.

אין Secrets או Tokens בשום Snapshot.

כל אירוע Audit ו-Message במחזור מקושר ל-decision_cycle_id ו-correlation_id.

כיבוי Feature Flag אינו רשאי להחזיר למסלול ישן שעוקף Risk Gate, State Machine או Audit — נתוני Snapshot נשמרים, החזרה למסלול קריאה קודם בלבד.

המפרט אושר לפני תחילת ביצוע.

כל סוג Snapshot קיבל Schema, בעלים ומקור נתונים.

כל תנאי קבלה קיבל בדיקה ותוצאה.

לא נוצרה נסיגה בהגנות, ב-State Machine או ב-Idempotency של CH3.

חוזי הסוכנים וה-CIO Shadow של CH4 נשמרו.

CIO נשאר Shadow; אין העברת סמכות.

הופק דוח ביצוע הכולל ראיות, חריגות והמלצת סגירה.

רק לאחר אישור דוח הביצוע משתנה סטטוס המפרט ל-Version 1.0 — Closed.

base44/entities/MarketSnapshot.jsonc — ישות חדשה (Append-Only) עם market_status per-venue, fx_rate_usd_ils.

base44/entities/PortfolioSnapshot.jsonc — ישות חדשה (Append-Only).

base44/entities/PolicySnapshot.jsonc — ישות חדשה (Append-Only).

base44/entities/SystemSnapshot.jsonc — ישות חדשה (Append-Only, ללא fx_rate — הועבר ל-Market).

base44/entities/DecisionContextSnapshot.jsonc — ישות חדשה מקשרת; ניתנת לעדכון ב-CAS רק במצב BUILDING, ו-Immutable לאחר PUBLISHED או FAILED (עם build_status, content_hash, idempotency_key).

base44/entities/Trade.jsonc — הוספת decision_cycle_id, correlation_id, decision_context_snapshot_id.

base44/entities/AnalysisOutput.jsonc — אכיפת מילוי decision_cycle_id; הוספת correlation_id, decision_context_snapshot_id.

base44/shared/snapshotBuilder.ts (חדש) — בנייה אטומית, Idempotency, hash קנוני.

base44/shared/correlationMiddleware.ts (חדש) — הזרקת מזהים, late broker events, refreshPortfolioPrices correlation_id תפעולי.

base44/shared/riskGateExecution.ts (חדש) — Risk Gate עדכני לפני Order.

base44/shared/snapshotRecovery.ts (חדש) — שאילתת שחזור + computed_status.

base44/functions/runAgentScan/entry.ts — יצירת מחזור (Orchestrator) והזנה מ-Snapshots.

base44/functions/refreshPortfolioPrices/entry.ts — correlation_id תפעולי בלבד, ללא יצירת מחזור.

src/pages/Ch5Spec003.jsx — עמוד מפרט זה (תיעוד).

1. יצירת חמש ישויות Snapshot: ארבעת המרכיבים (Market, Portfolio, Policy, System) — Append-Only. DecisionContextSnapshot — CAS-updatable רק ב-BUILDING, Immutable לאחר PUBLISHED/FAILED. כולל build_status, content_hash, hash_algorithm, hash_version.

2. יצירת base44/shared/snapshotBuilder.ts — בנייה אטומית (BUILDING→PUBLISHED/FAILED), Idempotency Key על decision_cycle_id, hash קנוני.

3. יצירת base44/shared/correlationMiddleware.ts — הזרקת מזהים, טיפול ב-late broker events, refreshPortfolioPrices מקבל correlation_id תפעולי בלבד.

4. יצירת base44/shared/riskGateExecution.ts — Risk Gate עדכני לפני Order (מצב חי, לא Snapshot).

5. יצירת base44/shared/snapshotRecovery.ts — שאילתת שחזור + computed_status.

6. הוספת decision_cycle_id, correlation_id ו-decision_context_snapshot_id ל-Trade, AnalysisOutput.

7. סימון Candidate, Decision, RiskResult, Order, Fill/BrokerEvent, PositionUpdate, AuditEvent כ-Planned/GAP עם קישור למזהים.

8. הזרקת מזהים ב-runAgentScan — יצירת מחזור בתחילת סריקה (Orchestrator).

9. הזרקת correlation_id תפעולי ב-refreshPortfolioPrices — ללא יצירת מחזור החלטה.

10. הזנת סוכנים מה-Snapshots בלבד (לא מנתונים חיים) בשלב הניתוח.

11. Risk Gate עדכני לפני יצירת Order — בדיקה מול מצב חי.

12. Feature Flag: Shadow comparison — השוואת תוצאות הנתיב החדש מול הקיים.

13. בדיקות קבלה: בנייה אטומית, Idempotency, Risk Gate, TTL/Max Age, computed_status, Hash קנוני, late broker event, Rollback מחמיר.

14. הפקת דוח ביצוע CH5-003 עם כל הראיות.