phase6: standardized event envelope (aggregate_type, aggregate_id, occurred_at, correlation_id, schema_version) + outbox_deliveries table

app/core/outbox.py

@@ -34,8 +34,9 @@ logger = logging.getLogger(__name__)
 
 _INSERT_SQL = text(
     """
-    INSERT INTO event_outbox (tenant_id, event_name, payload)
-    VALUES (:tenant_id, :event_name, CAST(:payload AS JSONB))
+    INSERT INTO event_outbox (tenant_id, event_name, payload, aggregate_type, aggregate_id, occurred_at, correlation_id, schema_version)
+    VALUES (:tenant_id, :event_name, CAST(:payload AS JSONB), :aggregate_type, :aggregate_id, COALESCE(:occurred_at, now()), :correlation_id, COALESCE(:schema_version, 1))
+    RETURNING id
     """
 )
 
@@ -52,7 +53,8 @@ _CLAIM_SQL = text(
           LIMIT :batch_size
           FOR UPDATE SKIP LOCKED
      )
-    RETURNING id, tenant_id, event_name, payload, attempts, max_attempts
+    RETURNING id, tenant_id, event_name, payload, attempts, max_attempts,
+              aggregate_type, aggregate_id, occurred_at, correlation_id, schema_version
     """
 )
 
@@ -99,6 +101,11 @@ async def enqueue_outbox_event(
     tenant_id: uuid.UUID,
     event_name: str,
     payload: dict[str, Any],
+    *,
+    aggregate_type: str | None = None,
+    aggregate_id: uuid.UUID | None = None,
+    correlation_id: uuid.UUID | None = None,
+    schema_version: int = 1,
 ) -> None:
     """Insert an event into the outbox table within the current transaction.
 
@@ -110,8 +117,12 @@ async def enqueue_outbox_event(
     Args:
         db: Active async SQLAlchemy session (part of the business transaction).
         tenant_id: Tenant scope for the event.
-        event_name: Logical event name (e.g. ``"contact.created"``).
+        event_name: Logical event name (e.g. ``"crm.contact.created.v1"``).
         payload: Event payload dict (will be stored as JSONB).
+        aggregate_type: Type of the aggregate (e.g. 'contact', 'task').
+        aggregate_id: UUID of the aggregate entity.
+        correlation_id: Optional correlation UUID for tracing across services.
+        schema_version: Event schema version (default 1).
     """
     await db.execute(
         _INSERT_SQL,
@@ -119,6 +130,11 @@ async def enqueue_outbox_event(
             "tenant_id": str(tenant_id),
             "event_name": event_name,
             "payload": _json_payload(payload),
+            "aggregate_type": aggregate_type,
+            "aggregate_id": str(aggregate_id) if aggregate_id else None,
+            "occurred_at": None,  # DB defaults to NOW()
+            "correlation_id": str(correlation_id) if correlation_id else None,
+            "schema_version": schema_version,
         },
     )
 
@@ -161,10 +177,16 @@ async def process_outbox_batch(
 
     for row in rows:
         event_id = row[0]
+        tenant_id = row[1]
         event_name = row[2]
         payload = row[3]
         attempts = row[4]
         max_attempts = row[5]
+        aggregate_type = row[6] if len(row) > 6 else None
+        aggregate_id = row[7] if len(row) > 7 else None
+        occurred_at = row[8] if len(row) > 8 else None
+        correlation_id = row[9] if len(row) > 9 else None
+        schema_version = row[10] if len(row) > 10 else 1
 
         # payload comes back as a dict from JSONB
         if isinstance(payload, str):
@@ -174,10 +196,16 @@ async def process_outbox_batch(
             payload_dict = payload
 
         try:
-            # Enrich payload with event metadata for idempotency
+            # Enrich payload with standardized event envelope metadata
             payload_dict.setdefault("_event_id", str(event_id))
             payload_dict.setdefault("_event_name", event_name)
             payload_dict.setdefault("_event_timestamp", datetime.now(timezone.utc).isoformat())
+            payload_dict.setdefault("_tenant_id", str(tenant_id))
+            payload_dict.setdefault("_aggregate_type", aggregate_type)
+            payload_dict.setdefault("_aggregate_id", str(aggregate_id) if aggregate_id else None)
+            payload_dict.setdefault("_occurred_at", occurred_at.isoformat() if occurred_at else None)
+            payload_dict.setdefault("_correlation_id", str(correlation_id) if correlation_id else None)
+            payload_dict.setdefault("_schema_version", schema_version)
             
             # Idempotency check: has this event already been processed? (P1.5 fix)
             already_processed = await db.execute(