From ba3b6c9af695aa209c4efd6c4a13b0bf840d5bef Mon Sep 17 00:00:00 2001
From: Danijel Martinek <danijel@fraqtal.xyz>
Date: Fri, 8 May 2026 11:56:37 +0200
Subject: [PATCH] feat(core-events): EventDescriptor + defineEvent

TDD: red (test-only), then green. defineEvent(name, schema) returns a typed
EventDescriptor<TName, TSchema>. Also added @repo/core-testing to devDeps
(required for nodeVitestConfig's setupFiles). 3 tests passing.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 packages/core-events/package.json             |  1 +
 .../core-events/src/event-descriptor.test.ts  | 24 +++++++++++++++++++
 packages/core-events/src/event-descriptor.ts  | 13 ++++++++++
 pnpm-lock.yaml                                |  3 +++
 4 files changed, 41 insertions(+)
 create mode 100644 packages/core-events/src/event-descriptor.test.ts
 create mode 100644 packages/core-events/src/event-descriptor.ts

diff --git a/packages/core-events/package.json b/packages/core-events/package.json
index 4b925b4..31c4be8 100644
--- a/packages/core-events/package.json
+++ b/packages/core-events/package.json
@@ -24,6 +24,7 @@
   },
   "devDependencies": {
     "@repo/core-eslint": "workspace:*",
+    "@repo/core-testing": "workspace:*",
     "@repo/core-typescript": "workspace:*",
     "typescript": "^5.8.0",
     "vitest": "^3.0.0"
diff --git a/packages/core-events/src/event-descriptor.test.ts b/packages/core-events/src/event-descriptor.test.ts
new file mode 100644
index 0000000..1dfc7ed
--- /dev/null
+++ b/packages/core-events/src/event-descriptor.test.ts
@@ -0,0 +1,24 @@
+import { describe, it, expect } from "vitest";
+import { z } from "zod";
+import { defineEvent } from "@/event-descriptor";
+
+describe("defineEvent", () => {
+  it("returns a descriptor with name and schema", () => {
+    const schema = z.object({ id: z.string() }).strict();
+    const descriptor = defineEvent("test.thing.happened", schema);
+    expect(descriptor.name).toBe("test.thing.happened");
+    expect(descriptor.schema).toBe(schema);
+  });
+
+  it("descriptor.schema parses valid payloads", () => {
+    const schema = z.object({ id: z.string() }).strict();
+    const d = defineEvent("test.evt", schema);
+    expect(() => d.schema.parse({ id: "abc" })).not.toThrow();
+  });
+
+  it("descriptor.schema rejects invalid payloads", () => {
+    const schema = z.object({ id: z.string() }).strict();
+    const d = defineEvent("test.evt", schema);
+    expect(() => d.schema.parse({ id: 123 })).toThrow();
+  });
+});
diff --git a/packages/core-events/src/event-descriptor.ts b/packages/core-events/src/event-descriptor.ts
new file mode 100644
index 0000000..56cd3c7
--- /dev/null
+++ b/packages/core-events/src/event-descriptor.ts
@@ -0,0 +1,13 @@
+import type { z } from "zod";
+
+export type EventDescriptor<TName extends string, TSchema extends z.ZodType> = {
+  readonly name: TName;
+  readonly schema: TSchema;
+};
+
+export function defineEvent<TName extends string, TSchema extends z.ZodType>(
+  name: TName,
+  schema: TSchema,
+): EventDescriptor<TName, TSchema> {
+  return { name, schema };
+}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index bc42300..12bae23 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -531,6 +531,9 @@ importers:
       '@repo/core-eslint':
         specifier: workspace:*
         version: link:../core-eslint
+      '@repo/core-testing':
+        specifier: workspace:*
+        version: link:../core-testing
       '@repo/core-typescript':
         specifier: workspace:*
         version: link:../core-typescript