events: modules log activity to the broker, any module reacts

The lighter sibling of provisioning — 1:many and broadcast, no credential,
just the broker's topic routing. A thin, audit-ready surface over the
broker's publish/subscribe:

- emit(type, body): publishes an Event carrying who emitted it (MESH_MODULE),
  on which node (MESH_NODE) and when (ISO timestamp) — so a listener can
  build a real audit trail.
- on(pattern, handler): react to events by topic pattern. The audit logger
  is just on("#", ...).

Tested: a module emits; a targeted listener (module.umami.#) hears only its
events, the audit sink (#) hears every module's, and the metadata audit
needs is present.

The declared side — a manifest's emits/consumes, so the mesh knows the
event graph — and the audit-logger module are the next pieces.

Claude-Session: https://claude.ai/code/session_01LrgweAeERJYBg88c5cKDzF

test/sdk.test.ts

@@ -7,6 +7,8 @@ import { join } from "node:path";
 import { seal, unseal, compareVersions } from "../dist/primitives/index.js";
 import { registerModuleTools, collectTools, resetTools, serveTools, listTools } from "../dist/tools/index.js";
 import { runProvisioner, type Grant } from "../dist/provisioner/index.js";
+import { emit, on, type Event } from "../dist/events/index.js";
+import { useBroker } from "../dist/messaging/index.js";
 
 test("seal round-trips and rejects the wrong key", () => {
   const sealed = seal("hunter2", "node-key");
@@ -126,10 +128,12 @@ test("serving refuses two modules exposing one tool name", async () => {
   await assert.rejects(serveTools(memBroker(), {}), /exposed by two modules/);
 });
 
-// A minimal in-memory broker: request routes to a registered handle. Enough to serve tools; the
-// real broker binding is the mesh's, provided by the hosting runtime.
+// A minimal in-memory broker: request routes to a registered handle, and publish routes to every
+// subscriber whose topic pattern matches. Enough to exercise tools and events; the real binding is
+// the mesh's AMQP one, provided by the hosting runtime.
 function memBroker() {
   const handlers = new Map<string, (b: unknown) => Promise<unknown>>();
+  const subs: { pattern: string; handler: (env: { key: string; node: string; body: unknown }) => Promise<void> }[] = [];
   return {
     async request<Req, Res>(key: string, body: Req): Promise<Res> {
       const h = handlers.get(key);
@@ -140,14 +144,68 @@ function memBroker() {
       handlers.set(key, handler as (b: unknown) => Promise<unknown>);
       return () => handlers.delete(key);
     },
-    async publish(): Promise<void> {},
-    async subscribe(): Promise<() => void> {
-      return () => {};
+    async publish<T>(env: { key: string; node: string; body: T }): Promise<void> {
+      for (const s of subs) if (topicMatch(s.pattern, env.key)) await s.handler(env);
+    },
+    async subscribe<T>(pattern: string, handler: (env: { key: string; node: string; body: T }) => Promise<void>): Promise<() => void> {
+      const entry = { pattern, handler: handler as (env: { key: string; node: string; body: unknown }) => Promise<void> };
+      subs.push(entry);
+      return () => {
+        const i = subs.indexOf(entry);
+        if (i >= 0) subs.splice(i, 1);
+      };
     },
     async close(): Promise<void> {},
   };
 }
 
+// AMQP topic matching: `*` one segment, `#` any run of segments.
+function topicMatch(pattern: string, key: string): boolean {
+  if (pattern === "#") return true;
+  const p = pattern.split(".");
+  const k = key.split(".");
+  let pi = 0;
+  let ki = 0;
+  while (pi < p.length) {
+    if (p[pi] === "#") return true; // simplification: # only as a trailing wildcard
+    if (ki >= k.length) return false;
+    if (p[pi] !== "*" && p[pi] !== k[ki]) return false;
+    pi++;
+    ki++;
+  }
+  return ki === k.length;
+}
+
+test("events: a module emits, a listener and the audit sink (#) both receive it, with metadata", async () => {
+  const broker = memBroker();
+  useBroker(() => broker);
+
+  process.env.MESH_MODULE = "umami";
+  process.env.MESH_NODE = "anchor";
+
+  const heard: Event[] = [];
+  const audited: Event[] = [];
+  await on("module.umami.#", async (e) => void heard.push(e));
+  await on("#", async (e) => void audited.push(e)); // the audit logger is just this
+
+  await emit("module.umami.site.created", { domain: "my-app" });
+  await emit("module.plex.play.started", { title: "x" }); // a different module's event
+
+  // The umami listener heard only umami's event; the audit sink heard both.
+  assert.deepEqual(heard.map((e) => e.type), ["module.umami.site.created"]);
+  assert.deepEqual(audited.map((e) => e.type), ["module.umami.site.created", "module.plex.play.started"]);
+
+  // The metadata an audit trail needs is present.
+  const e = heard[0];
+  assert.equal(e.source, "umami");
+  assert.equal(e.node, "anchor");
+  assert.equal((e.body as { domain: string }).domain, "my-app");
+  assert.match(e.at, /^\d{4}-\d{2}-\d{2}T/);
+
+  delete process.env.MESH_MODULE;
+  delete process.env.MESH_NODE;
+});
+
 async function waitFor(cond: () => boolean, ms: number): Promise<void> {
   const start = Date.now();
   while (!cond()) {