feat: events, signals, observability packages — Prompt 4

Signed-off-by: Todd Palmer <todd@betterdata.co>

Author: betterdataco

packages/events/package.json

@@ -15,9 +15,11 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "typecheck": "tsc -p tsconfig.json --noEmit"
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
   },
   "dependencies": {
-    "@loopengine/core": "workspace:*"
+    "@loopengine/core": "workspace:*",
+    "zod": "^3.22.0"
   }
 }

packages/events/src/__tests__/events.test.ts

@@ -0,0 +1,48 @@
+// @license MIT
+// SPDX-License-Identifier: MIT
+import { describe, expect, it } from "vitest";
+import { LoopEventSchema } from "../schemas";
+import { extractLearningSignal } from "../types";
+
+describe("events package", () => {
+  it("parses valid loop.started event", () => {
+    const result = LoopEventSchema.safeParse({
+      type: "loop.started",
+      eventId: "e1",
+      loopId: "demo.loop",
+      aggregateId: "A-1",
+      orgId: "acme",
+      occurredAt: new Date().toISOString(),
+      correlationId: "corr-1",
+      initialState: "OPEN",
+      actor: { type: "human", id: "user@example.com" }
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it("extractLearningSignal computes numeric delta", () => {
+    const completed = {
+      type: "loop.completed",
+      eventId: "e2",
+      loopId: "demo.loop",
+      aggregateId: "A-1",
+      orgId: "acme",
+      occurredAt: "2026-01-04T00:00:00.000Z",
+      correlationId: "corr-1",
+      terminalState: "DONE",
+      actor: { type: "human", id: "user@example.com" },
+      durationMs: 1,
+      transitionCount: 2,
+      outcomeId: "done",
+      valueUnit: "done"
+    } as const;
+    const result = extractLearningSignal(completed as any, [
+      {
+        occurredAt: "2026-01-01T00:00:00.000Z"
+      } as any
+    ], {
+      cycle_time_days: 2
+    });
+    expect(typeof result.delta.cycle_time_days).toBe("number");
+  });
+});

packages/events/src/bus.ts

@@ -0,0 +1,24 @@
+// @license MIT
+// SPDX-License-Identifier: MIT
+import type { LoopEvent } from "./types";
+
+type Handler = (event: LoopEvent) => Promise<void>;
+
+export class InMemoryEventBus {
+  private handlers = new Set<Handler>();
+
+  async emit(event: LoopEvent): Promise<void> {
+    for (const h of this.handlers) {
+      try {
+        await h(event);
+      } catch {
+        // Handler errors should not block emission.
+      }
+    }
+  }
+
+  subscribe(handler: Handler): () => void {
+    this.handlers.add(handler);
+    return () => this.handlers.delete(handler);
+  }
+}

packages/events/src/index.ts

@@ -1,66 +1,6 @@
 // @license MIT
 // SPDX-License-Identifier: MIT
-import type {
-  ActorRef,
-  AggregateId,
-  CorrelationId,
-  Evidence,
-  GuardId,
-  LoopId,
-  OutcomeId,
-  StateId,
-  TransitionId
-} from "@loopengine/core";
-
-export interface LoopEventBase {
-  eventId: string;
-  loopId: LoopId;
-  aggregateId: AggregateId;
-  orgId: string;
-  occurredAt: string;
-  correlationId: CorrelationId;
-  causationId?: string;
-}
-
-export interface LoopStartedEvent extends LoopEventBase {
-  type: "loop.started";
-  initialState: StateId;
-  actor: ActorRef;
-}
-
-export interface TransitionExecutedEvent extends LoopEventBase {
-  type: "loop.transition.executed";
-  fromState: StateId;
-  toState: StateId;
-  transitionId: TransitionId;
-  actor: ActorRef;
-  evidence: Evidence;
-  durationMs?: number;
-}
-
-export interface GuardFailedEvent extends LoopEventBase {
-  type: "loop.guard.failed";
-  fromState: StateId;
-  attemptedTransitionId: TransitionId;
-  guardId: GuardId;
-  guardFailureMessage: string;
-  severity?: "hard" | "soft";
-  actor: ActorRef;
-}
-
-export interface LoopCompletedEvent extends LoopEventBase {
-  type: "loop.completed";
-  terminalState: StateId;
-  actor: ActorRef;
-  durationMs: number;
-  transitionCount: number;
-  outcomeId: OutcomeId;
-  valueUnit: string;
-}
-
-export type LoopEvent =
-  | LoopStartedEvent
-  | TransitionExecutedEvent
-  | GuardFailedEvent
-  | LoopCompletedEvent;
+export * from "./types";
+export * from "./schemas";
+export * from "./bus";
 

packages/events/src/schemas.ts

@@ -0,0 +1,115 @@
+// @license MIT
+// SPDX-License-Identifier: MIT
+import { z } from "zod";
+
+const BaseSchema = z.object({
+  eventId: z.string().min(1),
+  loopId: z.string().min(1),
+  aggregateId: z.string().min(1),
+  orgId: z.string().min(1),
+  occurredAt: z.string().min(1),
+  correlationId: z.string().min(1),
+  causationId: z.string().optional()
+});
+
+const ActorSchema = z.object({
+  type: z.enum(["human", "automation", "ai-agent", "webhook", "system"]),
+  id: z.string().min(1)
+});
+
+const EvidenceSchema = z.record(z.unknown());
+
+export const LoopStartedEventSchema = BaseSchema.extend({
+  type: z.literal("loop.started"),
+  initialState: z.string().min(1),
+  actor: ActorSchema
+});
+
+export const TransitionRequestedEventSchema = BaseSchema.extend({
+  type: z.literal("loop.transition.requested"),
+  transitionId: z.string().min(1),
+  actor: ActorSchema,
+  evidence: EvidenceSchema,
+  requestedAt: z.string().min(1)
+});
+
+export const TransitionExecutedEventSchema = BaseSchema.extend({
+  type: z.literal("loop.transition.executed"),
+  fromState: z.string().min(1),
+  toState: z.string().min(1),
+  transitionId: z.string().min(1),
+  actor: ActorSchema,
+  evidence: EvidenceSchema,
+  durationMs: z.number().optional()
+});
+
+export const TransitionBlockedEventSchema = BaseSchema.extend({
+  type: z.literal("loop.transition.blocked"),
+  transitionId: z.string().min(1),
+  reason: z.enum(["guard_failed", "unauthorized_actor", "invalid_transition", "loop_closed"]),
+  actor: ActorSchema,
+  guardFailures: z.array(z.object({ guardId: z.string(), message: z.string() })).optional()
+});
+
+export const GuardFailedEventSchema = BaseSchema.extend({
+  type: z.literal("loop.guard.failed"),
+  fromState: z.string().min(1),
+  attemptedTransitionId: z.string().min(1),
+  guardId: z.string().min(1),
+  guardFailureMessage: z.string().min(1),
+  severity: z.enum(["hard", "soft"]).optional(),
+  actor: ActorSchema
+});
+
+export const LoopCompletedEventSchema = BaseSchema.extend({
+  type: z.literal("loop.completed"),
+  terminalState: z.string().min(1),
+  actor: ActorSchema,
+  durationMs: z.number(),
+  transitionCount: z.number().int().nonnegative(),
+  outcomeId: z.string().min(1),
+  valueUnit: z.string().min(1)
+});
+
+export const LoopErrorEventSchema = BaseSchema.extend({
+  type: z.literal("loop.error"),
+  errorState: z.string().min(1),
+  errorCode: z.string().min(1),
+  errorMessage: z.string().min(1),
+  actor: ActorSchema
+});
+
+export const LoopSpawnedEventSchema = BaseSchema.extend({
+  type: z.literal("loop.spawned"),
+  parentAggregateId: z.string().min(1),
+  childLoopId: z.string().min(1),
+  childAggregateId: z.string().min(1)
+});
+
+export const SignalReceivedEventSchema = BaseSchema.extend({
+  type: z.literal("loop.signal.received"),
+  signalType: z.string().min(1),
+  confidence: z.number(),
+  triggeredLoopId: z.string().optional()
+});
+
+export const OutcomeRecordedEventSchema = BaseSchema.extend({
+  type: z.literal("loop.outcome.recorded"),
+  outcomeId: z.string().min(1),
+  valueUnit: z.string().min(1),
+  businessMetrics: z.record(z.unknown()).optional(),
+  durationMs: z.number()
+});
+
+export const LoopEventSchema = z.discriminatedUnion("type", [
+  LoopStartedEventSchema,
+  TransitionRequestedEventSchema,
+  TransitionExecutedEventSchema,
+  TransitionBlockedEventSchema,
+  GuardFailedEventSchema,
+  LoopCompletedEventSchema,
+  LoopErrorEventSchema,
+  LoopSpawnedEventSchema,
+  SignalReceivedEventSchema,
+  OutcomeRecordedEventSchema
+]);