Umbrella Event Envelope - noetl/ai-meta GitHub Wiki
Umbrella โ Event Envelope Reconciliation (EE-1..EE-4)
TaskList: #51 in the agent's running task list ยท Started: 2026-05-29 ยท Last update: 2026-06-01 ยท Status: In flight (EE-1 / EE-2 / EE-3 landed; EE-4 not started)
Goal
Reconcile the four divergent shapes of the event envelope that the system carries today so the Rust worker, the Python server, the projector, and the CLI all serialise/deserialise the same bytes for the same conceptual event.
The four shapes
Surfaced via the noetl-server wiki's event envelope page:
| Component | Type | Owns the wire format? |
|---|---|---|
| Python server | EventEmitRequest |
Today's source of truth |
| Rust server | EventRequest |
Mirror of Python (intended) |
| Rust worker | WorkerEvent |
Drifted โ uses an older shape |
| noetl-executor | ExecutorEvent |
Drifted โ uses CLI-local shape |
Result: serialising in worker, deserialising in server, requires careful field mapping that's currently inline + fragile.
Phases
EE-1 โ snowflake event_id โ (landed 2026-05-30)
All four shapes carry a bigint event_id generated by the
application via snowflake (per
observability.md Principle 3). Server-side
gen_snowflake() Postgres function stays as a fallback.
EE-2 โ meta.attempts โ
(landed 2026-05-30)
Every event envelope carries meta.attempts: int (retry count).
Projectors group by attempts without reaching back into worker
logs.
EE-3 โ status taxonomy alignment โ (landed 2026-05-31)
call.done status fields normalised across all four shapes:
COMPLETED / FAILED / ERROR / CANCELLED. Projector consumers
group by the single column without per-source translation.
Shipped in noetl-server v2.0.1 + worker v5.8.0.
EE-4 โ type unification โณ (not started, blocked on #45 step 1)
Drop WorkerEvent and ExecutorEvent; replace with a shared
noetl-events crate that both worker and CLI's local-mode
runner consume. Server's Rust port (per
Umbrella: Python Services to Rust)
will use the same crate, removing the last divergence.
Will likely land as part of the shared library work in #45 step 1 (publisher crate adds the shared library skeleton).
Related
- noetl-server wiki: event envelope page.
- Umbrella: Rust Worker Migration โ the migration this reconciliation supports.
- Umbrella: Python Services to Rust โ EE-4 lands as part of the shared crate work there.
Next concrete steps
EE-4: create noetl-events crate in the same workspace as
noetl-tools / noetl-executor. Both worker + executor depend
on it. Older types become re-exports during migration.