Every Action, a Typed Event

Every event on the Aeion bus carries the same envelope shape so subscribers can rely on it without per-event boilerplate:

typescript interface EventEnvelope { id: string; // ULID — sortable, globally unique name: string; // module.entity.action — e.g. "commerce.order.created" tenantId: string; // Auto-injected from request context; subscribers filter on this traceId: string; // For distributed tracing — flows across module boundaries ts: number; // Unix ms epoch version: number; // Schema version of the payload payload: unknown; // Typed per-event payload — module-specific contracts }

Naming convention: module.entity.action (snake_case).

• commerce.order.created — domain event (something happened)
• commerce.order.payment_failed — sub-state transition
• cron.daily — scheduler event (no domain entity)
• record.created — auto-CRUD event (collection-agnostic; filter by payload.collection)

From a route handler the tenant context is implicit — aeion.events.emit auto-injects tenantId and traceId:

typescript // Inside a route handler await aeion.events.emit("commerce.order.created", { orderId: order.id, customerId: order.customerId, total: order.total, }); // → tenantId + traceId + ts + ULID id auto-attached

From a module setup function (no request context), pass tenantId explicitly:

typescript await api.events.emit("commerce.order.created", payload, { tenantId });

Subscribers register at module setup. The handler receives the typed payload + envelope so it can branch on tenant, trace, or version:

typescript await api.events.subscribe( "commerce.order.created", async (payload, envelope) => { const { orderId, customerId } = payload; const tenantId = envelope.tenantId; const aeion = await api.createContext(tenantId); // … do work as the tenant }, );

Filtering on auto-CRUD events: the platform emits record.created / record.updated / record.deleted for every collection write. Subscribe once + filter by collection slug — the cheapest auto-trigger when no module-specific event exists:

typescript await api.events.subscribe("record.created", async (payload, env) => { if (payload.collection !== "abandoned_carts") return; // … abandoned-cart recovery flow });

Wildcard subscriptions (Redis Streams glob pattern):

typescript await api.events.subscribe("commerce.*", handler); // any commerce event await api.events.subscribe("*.payment_failed", handler); // any payment failure

Events are how Aeion's modules talk without coupling. Examples already in production:

``` commerce.order.paid (Commerce) ↓ subscribed by: • aeionica → trigger license delivery + forensic-watermark embed • crm → log activity against the contact + bump LTV • finance → post journal entry • neural-bus → check fraud-anomaly model • notifications → send order-confirmation email

sentinel.alarm.tripped (Sentinel) ↓ subscribed by: • helpdesk → create high-priority incident ticket • fleet → broadcast "facility_lockdown" alert • smart-spaces → elevator-control restricted access • notifications → push + SMS to security director • exec.crisis → DEFCON level evaluator

record.created where collection="abandoned_carts" (auto-CRUD) ↓ subscribed by: • commerce.recover_cart agent → AI-drafted recovery email • marketing → enroll in abandoned-cart drip campaign ```

Every subscriber receives the same envelope. Cross-tenant data isolation is enforced at the bus layer — a subscriber for tenant A never sees an event from tenant B even when both run on the same Redis instance.

The bus delivers events through Redis Streams with consumer-group semantics — at-least-once delivery, ordered per stream, replayable from any point.

• Tenant scoping — tenantId is sealed in the envelope at emit time and validated on receive. Subscribers cannot fake a tenant.
• Trace propagation — traceId flows across module boundaries so distributed tracing shows the full request → event → handler → re-emit chain.
• Replay protection — handlers receive an idempotencyKey derived from {eventName}:{tenantId}:{sourceEventId} so re-deliveries (after consumer restart, after explicit replay) don't double-process.
• Consumer groups — each subscriber name owns its own offset; one slow consumer doesn't block another. Restart-safe.

Internal subscribers consume events directly off the bus. Customers (your tenants) configure outbound webhooks on a tenant-scoped allowlist:

typescript // Configure via Admin UI or webhooks API: { url: "https://customer-system.example/webhooks/aeion", events: ["commerce.order.created", "commerce.order.paid", "commerce.refund.processed"], secret: "whsec_...", // For HMAC-SHA256 signature verification }

Delivery semantics:

• HMAC-SHA256 signature in X-Aeion-Signature header (computed over the raw body)
• Retry with exponential backoff: 1s → 5s → 30s → 5m → 30m → 4h (max 6 attempts)
• Dead-letter queue after final attempt; admins replay manually from /admin/platform/webhooks/dlq
• Per-endpoint rate limit (1000 deliveries/min default) prevents accidental DoS of customer endpoints
• X-Aeion-Event, X-Aeion-Tenant, X-Aeion-Trace, X-Aeion-Timestamp headers for routing on the receiver side
• Replay protection — receiver should verify id hasn't been processed before; timestamp window prevents replay attacks (default ±5 min)