zayra-events 0.0.1

package/README.md

@@ -0,0 +1,223 @@
+# zayra-events
+
+The central event communication layer for **ZAYRA AI**. `zayra-events` lets every `zayra-*` package publish and subscribe to events without depending on each other directly — `zayra-task-engine` doesn't need to know `zayra-memory` exists to tell it a task finished; both just talk to the same `EventManager`.
+
+This is version `0.0.1`. It contains **no frontend UI, no business logic, and no AI decision-making** — this package only handles communication.
+
+## Installation
+
+```bash
+npm install zayra-events
+```
+
+## Usage
+
+```js
+import { EventManager, TaskEvent } from "zayra-events";
+
+const events = new EventManager();
+
+events.on(TaskEvent.COMPLETED, (envelope) => {
+  console.log(`Task ${envelope.data.taskId} completed at ${envelope.timestamp}`);
+});
+
+await events.emit(TaskEvent.COMPLETED, { taskId: "t1" }, { source: "zayra-task-engine" });
+```
+
+## Event Manager API
+
+```js
+events.on(eventName, handler);      // subscribe — returns an unsubscribe function
+events.once(eventName, handler);     // subscribe for one occurrence, then auto-unsubscribe
+events.removeListener(eventName, handler);
+events.removeAllListeners(eventName?); // omit eventName to clear every listener on every event
+events.listenerCount(eventName);
+
+await events.emit(eventName, data?, { source? }); // publish — see "emit() semantics" below
+```
+
+## Event data format
+
+Every event `on()` receives, and every result `emit()` resolves to, follows the same shape:
+
+```js
+{
+  event: "task.completed",
+  timestamp: "2026-07-19T12:00:00.000Z",
+  data: { taskId: "t1" },
+  source: "zayra-task-engine", // whichever module passed { source } to emit(), or null
+}
+```
+
+## Standard events
+
+```js
+import { SystemEvent, ModuleEvent, PluginEvent, AiEvent, MemoryEvent, TaskEvent } from "zayra-events";
+
+SystemEvent.STARTING;    // "system.starting"
+SystemEvent.STARTED;      // "system.started"
+SystemEvent.READY;         // "system.ready"
+SystemEvent.SHUTDOWN;       // "system.shutdown"
+
+ModuleEvent.LOADED;    // "module.loaded"
+ModuleEvent.STARTED;    // "module.started"
+ModuleEvent.FAILED;      // "module.failed"
+ModuleEvent.REMOVED;      // "module.removed"
+
+PluginEvent.INSTALLED;    // "plugin.installed"
+PluginEvent.LOADED;        // "plugin.loaded"
+PluginEvent.ENABLED;        // "plugin.enabled"
+PluginEvent.DISABLED;        // "plugin.disabled"
+PluginEvent.REMOVED;          // "plugin.removed"
+
+AiEvent.MODEL_SELECTED;        // "model.selected"
+AiEvent.PROVIDER_CONNECTED;     // "provider.connected"
+AiEvent.PROVIDER_FAILED;         // "provider.failed"
+AiEvent.REQUEST_STARTED;          // "ai.request.started"
+AiEvent.REQUEST_COMPLETED;         // "ai.request.completed"
+AiEvent.REQUEST_FAILED;             // "ai.request.failed"
+
+MemoryEvent.CREATED;    // "memory.created"
+MemoryEvent.UPDATED;     // "memory.updated"
+MemoryEvent.DELETED;      // "memory.deleted"
+MemoryEvent.RECALLED;      // "memory.recalled"
+
+TaskEvent.CREATED;    // "task.created"
+TaskEvent.STARTED;     // "task.started"
+TaskEvent.COMPLETED;    // "task.completed"
+TaskEvent.FAILED;        // "task.failed"
+```
+
+These constants exist to prevent typos — they're a catalog, not a restriction. See **Plugin compatibility** below.
+
+## Plugin compatibility (custom events)
+
+Any dot-namespaced string is a valid event name, standard or not:
+
+```js
+events.on("custom.plugin.event", (envelope) => { /* ... */ });
+await events.emit("custom.plugin.event", { anything: true });
+```
+
+```js
+import { isStandardEvent } from "zayra-events";
+
+isStandardEvent("task.completed");     // true
+isStandardEvent("custom.plugin.event"); // false — still perfectly valid to emit/listen to
+```
+
+## `emit()` semantics
+
+- **Listeners run concurrently**, each on its own microtask — a slow or misbehaving listener never blocks the others, and `emit()` never blocks your synchronous code unless you explicitly `await` it (Performance Rules: lightweight, asynchronous, avoid blocking operations).
+- **A throwing or rejecting listener never crashes `emit()`** or stops other listeners — its failure is caught and reported in the result instead.
+- **`once()` listeners are removed after they run**, whether they succeeded or threw.
+
+```js
+const outcome = await events.emit("ai.request.completed", { ms: 420 });
+
+outcome.result;
+// { listenerCount: 3, errorCount: 1, errors: [{ name, code: "LISTENER_FAILURE", message, listenerName }] }
+```
+
+`emit()` itself only throws for a genuinely invalid call — a malformed event name, or an unexpected internal failure — never for a listener's own mistake.
+
+## Event history
+
+```js
+events.history.list();                          // everything recorded so far, oldest first
+events.history.list({ event: "task.completed" }); // filter by event name
+events.history.list({ source: "zayra-memory" });    // filter by source
+events.history.list({ limit: 20 });                  // only the most recent 20
+events.history.size;                                  // current entry count
+events.history.clear();
+```
+
+Each entry: `{ event, timestamp, source, result }`. Capped at `maxSize` (default `500`, configurable via `new EventManager({ historySize: 1000 })`) so long-running processes don't grow this unbounded — the oldest entry is dropped first once full.
+
+## Cross-package communication, without a direct dependency
+
+```js
+// Inside zayra-task-engine's manager.js (or any module wired with the same EventManager):
+await events.emit(TaskEvent.COMPLETED, { taskId: task.id }, { source: "zayra-task-engine" });
+
+// Inside zayra-memory's manager.js — no import of zayra-task-engine anywhere:
+events.on(TaskEvent.COMPLETED, async (envelope) => {
+  await memory.save({ content: `Task ${envelope.data.taskId} completed.` });
+});
+```
+
+Both sides only need `zayra-events` — this is what lets `zayra-core`, `zayra-config`, `zayra-memory`, `zayra-tools`, `zayra-plugins`, `zayra-provider`, and `zayra-task-engine` communicate without any of them importing each other.
+
+## Errors
+
+- `EventError` — the single error class this package throws, distinguished by `err.code`:
+  - `"INVALID_EVENT"` — a bad event name or missing/non-function handler was passed to `on()`/`once()`/`emit()`
+  - `"LISTENER_FAILURE"` — a listener threw or rejected during `emit()` (reported in the result, not thrown)
+  - `"PROCESSING_FAILURE"` — an unexpected internal failure while processing an event
+
+```js
+import { EventError } from "zayra-events";
+
+try {
+  events.on("", handler);
+} catch (err) {
+  if (err instanceof EventError && err.code === "INVALID_EVENT") {
+    console.error("Bad event name:", err.eventName);
+  }
+}
+```
+
+## Design note: dependency-free by convention
+
+Like every other `zayra-*` package, `zayra-events` ships with **zero npm dependencies**. Packages that previously shipped their own minimal fallback event bus (`zayra-plugins`, `zayra-task-engine`, `zayra-sdk`) can now depend on this package directly and swap their internal `EventBus` for a shared `EventManager` instance — the `on()`/`off()`/`emit()`-shaped API was kept intentionally close to make that swap mechanical.
+
+## What this package deliberately does NOT do
+
+Per its design rules:
+
+- No frontend/UI code
+- No business logic — `zayra-events` doesn't decide what an event *means*, it only delivers it
+- No AI decision-making
+- No enforcement of which events a package may or may not emit — that's each package's own concern
+
+## Project structure
+
+```
+zayra-events/
+  src/
+    index.js         # public entry point
+    manager.js          # EventManager — on/once/removeListener/emit
+    event-types.js         # SystemEvent, ModuleEvent, PluginEvent, AiEvent, MemoryEvent, TaskEvent catalogs
+    format.js                 # event name validation + createEventEnvelope()
+    history.js                   # EventHistory — bounded recent-events log
+    errors.js                       # EventError
+  package.json
+  README.md
+```
+
+## API reference
+
+### `class EventManager`
+
+| Method | Description |
+| --- | --- |
+| `new EventManager(options?)` | `options.historySize` (default `500`), or inject `options.history`. |
+| `on(eventName, handler)` | Subscribe. Returns an unsubscribe function. |
+| `once(eventName, handler)` | Subscribe for one occurrence. |
+| `removeListener(eventName, handler)` | Unsubscribe one handler. |
+| `removeAllListeners(eventName?)` | Clear listeners for one event, or all events. |
+| `listenerCount(eventName)` | Number of active listeners for an event. |
+| `emit(eventName, data?, options?)` | Publish. `options.source` tags the emitter. Returns `Promise<EmitResult>`. |
+| `.history` | The `EventHistory` instance backing this manager. |
+
+### Other exports
+
+`EventHistory`, `isValidEventName()`, `createEventEnvelope()`, `SystemEvent`, `ModuleEvent`, `PluginEvent`, `AiEvent`, `MemoryEvent`, `TaskEvent`, `STANDARD_EVENTS`, `isStandardEvent()`, `EventError`
+
+## Compatibility
+
+Designed to be the shared communication backbone for `zayra-core`, `zayra-config`, `zayra-memory`, `zayra-tools`, `zayra-plugins`, `zayra-provider`, `zayra-task-engine`, and `zayra-sdk`.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "zayra-events",
+  "version": "0.0.1",
+  "description": "Central event communication layer for the ZAYRA AI ecosystem — lets packages communicate without a direct dependency between them.",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "test": "node --test \"test/**/*.test.js\""
+  },
+  "keywords": [
+    "zayra",
+    "ai",
+    "events",
+    "event-bus",
+    "pubsub",
+    "communication"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {}
+}

package/src/errors.js

@@ -0,0 +1,38 @@
+/**
+ * errors.js
+ *
+ * Error Handling (spec section: "Error Handling"). A single
+ * EventError class, distinguished by `err.code`, covering the three
+ * failure modes the spec calls out:
+ *
+ *   INVALID_EVENT       - a bad event name or missing handler was passed to on()/once()/emit()
+ *   LISTENER_FAILURE     - a listener threw or rejected during emit()
+ *   PROCESSING_FAILURE    - something else went wrong while processing an event
+ */
+
+export class EventError extends Error {
+  /**
+   * @param {string} message
+   * @param {object} [options]
+   * @param {"INVALID_EVENT"|"LISTENER_FAILURE"|"PROCESSING_FAILURE"|string} [options.code]
+   * @param {string} [options.eventName]
+   * @param {unknown} [options.cause]
+   */
+  constructor(message, options = {}) {
+    super(message);
+
+    this.name = this.constructor.name;
+    this.code = options.code ?? "EVENT_ERROR";
+    this.eventName = options.eventName ?? null;
+
+    if (options.cause !== undefined) {
+      this.cause = options.cause;
+    }
+
+    if (typeof Error.captureStackTrace === "function") {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+}
+
+export default { EventError };

package/src/event-types.js

@@ -0,0 +1,94 @@
+/**
+ * event-types.js
+ *
+ * Standard Events, Module Events, Plugin Events, AI Events, Memory
+ * Events, and Task Events (spec sections of the same names) — the
+ * shared event vocabulary every zayra-* package can rely on without
+ * having to agree on spelling separately.
+ *
+ * This is a catalog, not a restriction: per spec's "Plugin
+ * Compatibility" section, EventManager accepts any valid
+ * dot-namespaced event name, standard or custom (see format.js).
+ * These constants just prevent typos like "task.compelted" for the
+ * common cases.
+ */
+
+/** System lifecycle events. @readonly */
+export const SystemEvent = Object.freeze({
+  STARTING: "system.starting",
+  STARTED: "system.started",
+  READY: "system.ready",
+  SHUTDOWN: "system.shutdown",
+});
+
+/** Generic module lifecycle events (any zayra-* module). @readonly */
+export const ModuleEvent = Object.freeze({
+  LOADED: "module.loaded",
+  STARTED: "module.started",
+  FAILED: "module.failed",
+  REMOVED: "module.removed",
+});
+
+/** zayra-plugins lifecycle events. @readonly */
+export const PluginEvent = Object.freeze({
+  INSTALLED: "plugin.installed",
+  LOADED: "plugin.loaded",
+  ENABLED: "plugin.enabled",
+  DISABLED: "plugin.disabled",
+  REMOVED: "plugin.removed",
+});
+
+/** AI provider / model / request events (zayra-provider, zayra-ai-router). @readonly */
+export const AiEvent = Object.freeze({
+  MODEL_SELECTED: "model.selected",
+  PROVIDER_CONNECTED: "provider.connected",
+  PROVIDER_FAILED: "provider.failed",
+  REQUEST_STARTED: "ai.request.started",
+  REQUEST_COMPLETED: "ai.request.completed",
+  REQUEST_FAILED: "ai.request.failed",
+});
+
+/** zayra-memory events. @readonly */
+export const MemoryEvent = Object.freeze({
+  CREATED: "memory.created",
+  UPDATED: "memory.updated",
+  DELETED: "memory.deleted",
+  RECALLED: "memory.recalled",
+});
+
+/** zayra-task-engine events (the shared baseline subset — zayra-task-engine's own internal bus additionally has paused/resumed/cancelled/step-level events). @readonly */
+export const TaskEvent = Object.freeze({
+  CREATED: "task.created",
+  STARTED: "task.started",
+  COMPLETED: "task.completed",
+  FAILED: "task.failed",
+});
+
+/** Every standard event name, flattened, e.g. for isStandardEvent(). */
+export const STANDARD_EVENTS = Object.freeze([
+  ...Object.values(SystemEvent),
+  ...Object.values(ModuleEvent),
+  ...Object.values(PluginEvent),
+  ...Object.values(AiEvent),
+  ...Object.values(MemoryEvent),
+  ...Object.values(TaskEvent),
+]);
+
+/**
+ * @param {string} eventName
+ * @returns {boolean} Whether eventName is part of the standard catalog above (informational only — custom events are still valid, see format.js).
+ */
+export function isStandardEvent(eventName) {
+  return STANDARD_EVENTS.includes(eventName);
+}
+
+export default {
+  SystemEvent,
+  ModuleEvent,
+  PluginEvent,
+  AiEvent,
+  MemoryEvent,
+  TaskEvent,
+  STANDARD_EVENTS,
+  isStandardEvent,
+};

package/src/format.js

@@ -0,0 +1,55 @@
+/**
+ * format.js
+ *
+ * Event Data Format (spec section: "Event Data Format") — every
+ * event emitted through EventManager takes this shape:
+ *
+ *   { event: "task.completed", timestamp: "2026-07-19T12:00:00.000Z", data: {}, source: null }
+ *
+ * Also defines the event-name validation shared by manager.js. Per
+ * spec's "Plugin Compatibility" section, ANY dot-namespaced name is a
+ * valid event — not just the standard catalog in event-types.js — so
+ * a plugin can freely emit something like "custom.plugin.event".
+ */
+
+import { EventError } from "./errors.js";
+
+/** Dot-namespaced identifier: letters/digits/underscores, segments joined by ".". */
+const EVENT_NAME_PATTERN = /^[a-zA-Z0-9_]+(\.[a-zA-Z0-9_]+)*$/;
+
+/**
+ * @param {unknown} eventName
+ * @returns {boolean}
+ */
+export function isValidEventName(eventName) {
+  return typeof eventName === "string" && eventName.length > 0 && EVENT_NAME_PATTERN.test(eventName);
+}
+
+/**
+ * Builds a standard event envelope.
+ *
+ * @param {string} eventName
+ * @param {object} [data]
+ * @param {object} [options]
+ * @param {string} [options.source] - Which package/module emitted this event, e.g. "zayra-task-engine".
+ * @param {string} [options.timestamp] - Overrides the auto-generated ISO timestamp (mainly for tests).
+ * @returns {{ event: string, timestamp: string, data: object, source: string|null }}
+ * @throws {EventError} If eventName is invalid (code: "INVALID_EVENT").
+ */
+export function createEventEnvelope(eventName, data = {}, options = {}) {
+  if (!isValidEventName(eventName)) {
+    throw new EventError(
+      `Invalid event name: "${eventName}". Use a dot-namespaced identifier, e.g. "task.completed".`,
+      { code: "INVALID_EVENT", eventName }
+    );
+  }
+
+  return {
+    event: eventName,
+    timestamp: options.timestamp ?? new Date().toISOString(),
+    data: data ?? {},
+    source: options.source ?? null,
+  };
+}
+
+export default { isValidEventName, createEventEnvelope };

package/src/history.js

@@ -0,0 +1,76 @@
+/**
+ * history.js
+ *
+ * Event History (spec section: "Event History"). Stores recent
+ * events — name, time, source, result — in memory, capped at a
+ * fixed size so it stays lightweight (Performance Rules) rather than
+ * growing unbounded for a long-lived process.
+ */
+
+/**
+ * @typedef {object} EventHistoryEntry
+ * @property {string} event
+ * @property {string} timestamp
+ * @property {string|null} source
+ * @property {{ listenerCount: number, errorCount: number, errors: object[] }} result
+ */
+
+export class EventHistory {
+  /**
+   * @param {object} [options]
+   * @param {number} [options.maxSize=500] - Oldest entries are dropped once this many are stored.
+   */
+  constructor(options = {}) {
+    this.maxSize = options.maxSize ?? 500;
+    /** @type {EventHistoryEntry[]} */
+    this._entries = [];
+  }
+
+  /**
+   * Records an entry, dropping the oldest one first if at capacity.
+   * @param {EventHistoryEntry} entry
+   */
+  record(entry) {
+    this._entries.push(entry);
+    if (this._entries.length > this.maxSize) {
+      this._entries.shift();
+    }
+  }
+
+  /**
+   * Lists recorded entries, most-recently-recorded last, optionally
+   * filtered.
+   * @param {object} [filter]
+   * @param {string} [filter.event] - Restrict to one event name.
+   * @param {string} [filter.source] - Restrict to one source.
+   * @param {number} [filter.limit] - Only the most recent N entries.
+   * @returns {EventHistoryEntry[]}
+   */
+  list(filter = {}) {
+    let entries = this._entries;
+
+    if (filter.event) {
+      entries = entries.filter((entry) => entry.event === filter.event);
+    }
+    if (filter.source) {
+      entries = entries.filter((entry) => entry.source === filter.source);
+    }
+    if (typeof filter.limit === "number" && filter.limit >= 0) {
+      entries = entries.slice(-filter.limit);
+    }
+
+    return entries;
+  }
+
+  /** @returns {number} */
+  get size() {
+    return this._entries.length;
+  }
+
+  /** Removes every recorded entry. */
+  clear() {
+    this._entries = [];
+  }
+}
+
+export default EventHistory;

package/src/index.js

@@ -0,0 +1,27 @@
+/**
+ * index.js
+ *
+ * Public entry point for the zayra-events package.
+ *
+ * Anything a consumer needs should be exported from here — they
+ * should never need to import from "zayra-events/src/...". This
+ * keeps the internal file layout free to change without breaking
+ * every zayra-* package that subscribes/publishes through this one.
+ */
+
+export { EventManager } from "./manager.js";
+export { EventHistory } from "./history.js";
+export { isValidEventName, createEventEnvelope } from "./format.js";
+export {
+  SystemEvent,
+  ModuleEvent,
+  PluginEvent,
+  AiEvent,
+  MemoryEvent,
+  TaskEvent,
+  STANDARD_EVENTS,
+  isStandardEvent,
+} from "./event-types.js";
+export { EventError } from "./errors.js";
+
+export { EventManager as default } from "./manager.js";

package/src/manager.js

@@ -0,0 +1,230 @@
+/**
+ * manager.js
+ *
+ * EventManager (spec section: "Event Manager") — the central
+ * communication layer every zayra-* package can subscribe to and
+ * publish through, so they never need a direct dependency on one
+ * another (spec's "Event System Upgrade" goal).
+ *
+ * Performance Rules: lightweight, asynchronous, scalable, and never
+ * blocking. emit() reflects that directly:
+ *   - listeners run concurrently (Promise.allSettled), each kicked
+ *     off on its own microtask, so the caller's synchronous code
+ *     never blocks waiting on a slow or misbehaving handler unless
+ *     it chooses to `await emit(...)`.
+ *   - a throwing/rejecting listener never stops the others or
+ *     crashes emit() — its failure is caught, described, and
+ *     returned in the result instead (Error Handling: "listener
+ *     failure").
+ *
+ * Important Rules: this file only handles communication — no
+ * frontend UI, no business logic, no AI decision-making.
+ */
+
+import { EventError } from "./errors.js";
+import { isValidEventName, createEventEnvelope } from "./format.js";
+import { EventHistory } from "./history.js";
+
+/**
+ * @typedef {object} EmitResult
+ * @property {string} event
+ * @property {string} timestamp
+ * @property {object} data
+ * @property {string|null} source
+ * @property {{ listenerCount: number, errorCount: number, errors: object[] }} result
+ */
+
+export class EventManager {
+  /**
+   * @param {object} [options]
+   * @param {number} [options.historySize=500] - Passed to EventHistory.
+   * @param {EventHistory} [options.history] - Inject a custom/shared EventHistory instance instead of creating a new one.
+   */
+  constructor(options = {}) {
+    /** @type {Map<string, Map<Function, { once: boolean }>>} */
+    this._listeners = new Map();
+    this.history = options.history ?? new EventHistory({ maxSize: options.historySize });
+  }
+
+  /* ------------------------------------------------------------------ */
+  /* Subscribing: on / once / removeListener                             */
+  /* ------------------------------------------------------------------ */
+
+  /**
+   * Subscribes to an event. Duplicate on() calls with the same
+   * (eventName, handler) pair are harmless no-ops after the first —
+   * a Map keyed by the handler function can't hold it twice.
+   *
+   * @param {string} eventName
+   * @param {(envelope: { event: string, timestamp: string, data: object, source: string|null }) => void|Promise<void>} handler
+   * @returns {() => void} Unsubscribe function.
+   * @throws {EventError} If eventName or handler is invalid (code: "INVALID_EVENT").
+   */
+  on(eventName, handler) {
+    this._validateSubscription(eventName, handler, "on");
+    this._handlersFor(eventName).set(handler, { once: false });
+    return () => this.removeListener(eventName, handler);
+  }
+
+  /**
+   * Subscribes to an event for a single occurrence — the handler is
+   * automatically removed right after it runs (whether it succeeds
+   * or throws).
+   *
+   * @param {string} eventName
+   * @param {(envelope: object) => void|Promise<void>} handler
+   * @returns {() => void} Unsubscribe function.
+   * @throws {EventError} If eventName or handler is invalid.
+   */
+  once(eventName, handler) {
+    this._validateSubscription(eventName, handler, "once");
+    this._handlersFor(eventName).set(handler, { once: true });
+    return () => this.removeListener(eventName, handler);
+  }
+
+  /**
+   * Unsubscribes one handler from one event. Safe to call for a
+   * handler that was never subscribed.
+   * @param {string} eventName
+   * @param {Function} handler
+   */
+  removeListener(eventName, handler) {
+    this._listeners.get(eventName)?.delete(handler);
+  }
+
+  /**
+   * Removes every listener for one event, or every listener for
+   * every event if eventName is omitted.
+   * @param {string} [eventName]
+   */
+  removeAllListeners(eventName) {
+    if (eventName) {
+      this._listeners.delete(eventName);
+    } else {
+      this._listeners.clear();
+    }
+  }
+
+  /** @param {string} eventName @returns {number} */
+  listenerCount(eventName) {
+    return this._listeners.get(eventName)?.size ?? 0;
+  }
+
+  /* ------------------------------------------------------------------ */
+  /* Publishing: emit                                                     */
+  /* ------------------------------------------------------------------ */
+
+  /**
+   * Publishes an event. Never throws for a listener failure — those
+   * are collected into the returned result instead. Only throws for
+   * an invalid event name/data (a caller bug, per "Error Handling:
+   * invalid event") or an unexpected internal failure (code:
+   * "PROCESSING_FAILURE").
+   *
+   * @param {string} eventName
+   * @param {object} [data]
+   * @param {object} [options]
+   * @param {string} [options.source] - Which package/module is emitting this, e.g. "zayra-task-engine".
+   * @returns {Promise<EmitResult>}
+   * @throws {EventError}
+   */
+  async emit(eventName, data = {}, options = {}) {
+    let envelope;
+    let entries;
+
+    try {
+      envelope = createEventEnvelope(eventName, data, { source: options.source });
+      entries = [...(this._listeners.get(eventName)?.entries() ?? [])];
+    } catch (err) {
+      if (err instanceof EventError) {
+        throw err;
+      }
+      throw new EventError(`Failed to process event "${eventName}": ${err.message}`, {
+        code: "PROCESSING_FAILURE",
+        eventName,
+        cause: err,
+      });
+    }
+
+    const errors = [];
+    const settlements = await Promise.allSettled(
+      entries.map(([handler]) => Promise.resolve().then(() => handler(envelope)))
+    );
+
+    settlements.forEach((settlement, index) => {
+      if (settlement.status === "rejected") {
+        const [handler] = entries[index];
+        errors.push(this._describeListenerFailure(envelope.event, handler, settlement.reason));
+      }
+    });
+
+    // "once" listeners are removed after they've run, success or not.
+    const map = this._listeners.get(eventName);
+    if (map) {
+      for (const [handler, meta] of entries) {
+        if (meta.once) {
+          map.delete(handler);
+        }
+      }
+    }
+
+    const result = { listenerCount: entries.length, errorCount: errors.length, errors };
+
+    try {
+      this.history.record({ event: envelope.event, timestamp: envelope.timestamp, source: envelope.source, result });
+    } catch (err) {
+      // A broken history implementation should never take emit() down with it.
+      console.error("[zayra-events] Failed to record event history:", err);
+    }
+
+    return { ...envelope, result };
+  }
+
+  /* ------------------------------------------------------------------ */
+  /* Internals                                                            */
+  /* ------------------------------------------------------------------ */
+
+  /** @private */
+  _handlersFor(eventName) {
+    if (!this._listeners.has(eventName)) {
+      this._listeners.set(eventName, new Map());
+    }
+    return this._listeners.get(eventName);
+  }
+
+  /** @private */
+  _validateSubscription(eventName, handler, methodName) {
+    if (!isValidEventName(eventName)) {
+      throw new EventError(
+        `${methodName}() requires a valid dot-namespaced event name, got: "${eventName}".`,
+        { code: "INVALID_EVENT", eventName }
+      );
+    }
+    if (typeof handler !== "function") {
+      throw new EventError(`${methodName}() requires a function handler.`, { code: "INVALID_EVENT", eventName });
+    }
+  }
+
+  /**
+   * Turns a listener's thrown/rejected value into a plain,
+   * serializable description — never leaks the raw handler function
+   * or a non-serializable error object into history/results.
+   * @private
+   */
+  _describeListenerFailure(eventName, handler, reason) {
+    const cause = reason instanceof Error ? reason : new Error(String(reason));
+    const err = new EventError(`Listener for "${eventName}" failed: ${cause.message}`, {
+      code: "LISTENER_FAILURE",
+      eventName,
+      cause,
+    });
+    return {
+      name: err.name,
+      code: err.code,
+      message: err.message,
+      listenerName: handler.name || "<anonymous>",
+    };
+  }
+}
+
+export default EventManager;