@opengroundplan/core 0.1.1

package/templates/architectures/event-driven/files/src/__solutionName.snake__/broker/adapters/in_memory.py

@@ -0,0 +1,61 @@
+"""Default adapter so a fresh repo runs with no infrastructure.
+
+Deliberately NOT durable: nothing replays and a crash loses in-flight events. Swap it for a real
+broker before you depend on delivery.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+
+from ...events import EventEnvelope
+from ..config import BrokerConfig
+from ..port import EventHandler
+
+_log = logging.getLogger(__name__)
+
+
+class InMemoryEventBroker:
+    def __init__(self, config: BrokerConfig) -> None:
+        self._config = config
+        self._subscribers: dict[str, list[EventHandler]] = {}
+        self._dead_lettered: list[EventEnvelope] = []
+
+    async def start(self) -> None:
+        return None
+
+    async def stop(self) -> None:
+        self._subscribers.clear()
+
+    async def subscribe(self, event_type: str, handler: EventHandler) -> None:
+        self._subscribers.setdefault(self._topic(event_type), []).append(handler)
+
+    async def publish(self, envelope: EventEnvelope) -> None:
+        """Fan-out is independent: one failing subscriber must never stop the others."""
+        subscribers = self._subscribers.get(self._topic(envelope.type), ())
+        await asyncio.gather(*(self._deliver(handler, envelope) for handler in subscribers))
+
+    @property
+    def dead_lettered(self) -> list[EventEnvelope]:
+        """What a real subscriber would read off the dead-letter topic."""
+        return list(self._dead_lettered)
+
+    async def _deliver(self, handler: EventHandler, envelope: EventEnvelope) -> None:
+        """Retry then dead-letter, because one poison message must not block the topic forever."""
+        for attempt in range(1, self._config.max_delivery_attempts + 1):
+            try:
+                await handler(envelope)
+                return
+            except Exception:
+                if attempt == self._config.max_delivery_attempts:
+                    self._dead_lettered.append(envelope)
+                    _log.exception(
+                        "dead-lettered %s (%s) to %s",
+                        envelope.id,
+                        envelope.type,
+                        self._topic(envelope.type) + self._config.dead_letter_suffix,
+                    )
+
+    def _topic(self, event_type: str) -> str:
+        return f"{self._config.topic_prefix}.{event_type}"

package/templates/architectures/event-driven/files/src/__solutionName.snake__/broker/config.py

@@ -0,0 +1,42 @@
+"""Every broker tunable, one typed default each. Nothing else in the package reads these vars."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+_PREFIX = "EVENT_BROKER_"
+
+
+@dataclass(frozen=True, kw_only=True, slots=True)
+class BrokerConfig:
+    driver: str = "in-memory"
+    url: str = ""
+    topic_prefix: str = "{{ solutionName | kebab }}"
+    consumer_group: str = "{{ solutionName | kebab }}"
+    max_delivery_attempts: int = 5
+    dead_letter_suffix: str = ".dlq"
+
+
+def _positive_int(value: str | None, fallback: int) -> int:
+    try:
+        parsed = int(value) if value is not None else fallback
+    except ValueError:
+        return fallback
+    return parsed if parsed > 0 else fallback
+
+
+def load_broker_config(env: Mapping[str, str] | None = None) -> BrokerConfig:
+    source: Mapping[str, str] = os.environ if env is None else env
+    defaults = BrokerConfig()
+    return BrokerConfig(
+        driver=source.get(_PREFIX + "DRIVER", defaults.driver),
+        url=source.get(_PREFIX + "URL", defaults.url),
+        topic_prefix=source.get(_PREFIX + "TOPIC_PREFIX", defaults.topic_prefix),
+        consumer_group=source.get(_PREFIX + "CONSUMER_GROUP", defaults.consumer_group),
+        max_delivery_attempts=_positive_int(
+            source.get(_PREFIX + "MAX_DELIVERY_ATTEMPTS"), defaults.max_delivery_attempts
+        ),
+        dead_letter_suffix=source.get(_PREFIX + "DEAD_LETTER_SUFFIX", defaults.dead_letter_suffix),
+    )

package/templates/architectures/event-driven/files/src/__solutionName.snake__/broker/factory.py

@@ -0,0 +1,13 @@
+"""The only module that names a concrete adapter. Add a branch per adapter you ship."""
+
+from __future__ import annotations
+
+from .adapters.in_memory import InMemoryEventBroker
+from .config import BrokerConfig
+from .port import EventBroker
+
+
+def create_broker(config: BrokerConfig) -> EventBroker:
+    if config.driver == "in-memory":
+        return InMemoryEventBroker(config)
+    raise ValueError(f'Unknown EVENT_BROKER_DRIVER "{config.driver}"')

package/templates/architectures/event-driven/files/src/__solutionName.snake__/broker/port.py

@@ -0,0 +1,25 @@
+"""The broker port — the seam the whole style hangs on."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from typing import Protocol, runtime_checkable
+
+from ..events import EventEnvelope
+
+EventHandler = Callable[[EventEnvelope], Awaitable[None]]
+
+
+@runtime_checkable
+class EventBroker(Protocol):
+    """Publishers and handlers see only this, so swapping Kafka for NATS changes no handler."""
+
+    async def publish(self, envelope: EventEnvelope) -> None: ...
+
+    async def subscribe(self, event_type: str, handler: EventHandler) -> None:
+        """`event_type` is a versioned catalog name, so a v2 rollout never breaks a v1 subscriber."""
+        ...
+
+    async def start(self) -> None: ...
+
+    async def stop(self) -> None: ...

package/templates/architectures/event-driven/files/src/__solutionName.snake__/eventing.py

@@ -0,0 +1,26 @@
+"""Composition root: the one module that knows every handler exists."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .broker import EventBroker, create_broker, load_broker_config
+from .handlers import {{ firstHandler | snake }}, {{ secondHandler | snake }}
+from .publishers import {{ eventDomain | pascal }}Publisher
+
+
+@dataclass(frozen=True, kw_only=True, slots=True)
+class Eventing:
+    broker: EventBroker
+    {{ eventDomain | snake }}: {{ eventDomain | pascal }}Publisher
+
+
+async def start_eventing() -> Eventing:
+    broker = create_broker(load_broker_config())
+    await broker.start()
+
+    # Subscribe before anything publishes, or the first fan-out has nobody listening.
+    await {{ firstHandler | snake }}.register(broker)
+    await {{ secondHandler | snake }}.register(broker)
+
+    return Eventing(broker=broker, {{ eventDomain | snake }}={{ eventDomain | pascal }}Publisher(broker))

package/templates/architectures/event-driven/files/src/__solutionName.snake__/events/__eventDomain.snake__/__firstEvent.snake__/__init__.py

@@ -0,0 +1,5 @@
+"""Every version of {{ eventDomain | kebab }}.{{ firstEvent | kebab }} lives here, side by side."""
+
+from .v1 import {{ firstEvent | upperSnake }}_V1, {{ firstEvent | pascal }}V1
+
+__all__ = ["{{ firstEvent | upperSnake }}_V1", "{{ firstEvent | pascal }}V1"]

package/templates/architectures/event-driven/files/src/__solutionName.snake__/events/__eventDomain.snake__/__firstEvent.snake__/v1.py

@@ -0,0 +1,34 @@
+"""{{ eventDomain | kebab }}.{{ firstEvent | kebab }} v1 — a published contract. Add v2.py beside it, never edit this."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from ...contract import EventContract, EventSchemaError
+
+NAME = "{{ eventDomain | kebab }}.{{ firstEvent | kebab }}"
+
+
+@dataclass(frozen=True, kw_only=True, slots=True)
+class {{ firstEvent | pascal }}V1:
+    subject_id: str
+    # Denormalised on purpose — a consumer that calls back to the producer is coupled to it.
+    subject_name: str
+
+
+def _parse(value: Any) -> {{ firstEvent | pascal }}V1:
+    if isinstance(value, {{ firstEvent | pascal }}V1):
+        return value
+    if not isinstance(value, dict):
+        raise EventSchemaError(f"{NAME}.v1 payload must be a mapping")
+    try:
+        return {{ firstEvent | pascal }}V1(
+            subject_id=str(value["subject_id"]),
+            subject_name=str(value["subject_name"]),
+        )
+    except KeyError as missing:
+        raise EventSchemaError(f"{NAME}.v1 payload is missing {missing}") from missing
+
+
+{{ firstEvent | upperSnake }}_V1 = EventContract(name=NAME, version=1, parse=_parse)

package/templates/architectures/event-driven/files/src/__solutionName.snake__/events/__eventDomain.snake__/__init__.py

@@ -0,0 +1 @@
+"""Events owned by the {{ eventDomain | kebab }} context."""

package/templates/architectures/event-driven/files/src/__solutionName.snake__/events/__init__.py

@@ -0,0 +1,27 @@
+"""The event catalog: every event this system publishes, by wire type.
+
+Sits at the bottom of the import graph — it imports no handler, publisher, or broker, which is
+what lets any of them depend on it without creating a cycle.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .contract import EventContract, EventSchemaError
+from .envelope import EventEnvelope
+from .{{ eventDomain | snake }}.{{ firstEvent | snake }} import {{ firstEvent | upperSnake }}_V1, {{ firstEvent | pascal }}V1
+
+# Registering here is what makes the folder a catalog, and it is the list you diff at review.
+CATALOG: dict[str, EventContract[Any]] = {
+    {{ firstEvent | upperSnake }}_V1.type: {{ firstEvent | upperSnake }}_V1,
+}
+
+__all__ = [
+    "CATALOG",
+    "EventContract",
+    "EventEnvelope",
+    "EventSchemaError",
+    "{{ firstEvent | upperSnake }}_V1",
+    "{{ firstEvent | pascal }}V1",
+]

package/templates/architectures/event-driven/files/src/__solutionName.snake__/events/contract.py

@@ -0,0 +1,35 @@
+"""Versioned event contracts. A new version is a new contract beside the old one."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any, Generic, TypeVar
+
+from .envelope import EventEnvelope
+
+P = TypeVar("P")
+
+
+class EventSchemaError(ValueError):
+    """Raised when a payload does not match the version it claims to be."""
+
+
+@dataclass(frozen=True, slots=True)
+class EventContract(Generic[P]):
+    """Subscribers of v1 keep receiving v1 until they choose to migrate."""
+
+    name: str
+    version: int
+    parse: Callable[[Any], P]
+
+    @property
+    def type(self) -> str:
+        """Wire identifier. Subscribers key off it, so it is append-only forever."""
+        return f"{self.name}.v{self.version}"
+
+    def envelope(self, payload: P, correlation_id: str | None = None) -> EventEnvelope:
+        parsed = self.parse(payload)
+        if correlation_id is None:
+            return EventEnvelope(type=self.type, payload=parsed)
+        return EventEnvelope(type=self.type, payload=parsed, correlation_id=correlation_id)

package/templates/architectures/event-driven/files/src/__solutionName.snake__/events/envelope.py

@@ -0,0 +1,24 @@
+"""The envelope is the only thing that crosses a boundary."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from typing import Any
+from uuid import uuid4
+
+
+def _identifier() -> str:
+    return uuid4().hex
+
+
+@dataclass(frozen=True, kw_only=True, slots=True)
+class EventEnvelope:
+    """A handler receives this, never another handler's types."""
+
+    type: str
+    payload: Any
+    id: str = field(default_factory=_identifier)
+    occurred_at: datetime = field(default_factory=lambda: datetime.now(UTC))
+    # Stands in for the call stack you gave up — carry it into every event a handler emits.
+    correlation_id: str = field(default_factory=_identifier)

package/templates/architectures/event-driven/files/src/__solutionName.snake__/handlers/__firstHandler.snake__/__init__.py

@@ -0,0 +1,30 @@
+"""Reacts to {{ eventDomain | kebab }}.{{ firstEvent | kebab }} v1.
+
+Registration happens in eventing.py, never from another handler — that is the import the
+boundary check exists to stop.
+"""
+
+from __future__ import annotations
+
+from ...broker import EventBroker
+from ...events import {{ firstEvent | upperSnake }}_V1, EventEnvelope, {{ firstEvent | pascal }}V1
+
+__all__ = ["register"]
+
+
+async def register(broker: EventBroker) -> None:
+    await broker.subscribe({{ firstEvent | upperSnake }}_V1.type, _on_{{ firstEvent | snake }})
+
+
+async def _on_{{ firstEvent | snake }}(envelope: EventEnvelope) -> None:
+    # Validate at the edge: the wire is untyped however careful the publisher was.
+    await _{{ firstHandler | snake }}({{ firstEvent | upperSnake }}_V1.parse(envelope.payload), envelope.correlation_id)
+
+
+async def _{{ firstHandler | snake }}(payload: {{ firstEvent | pascal }}V1, correlation_id: str) -> None:
+    """Must be idempotent.
+
+    At-least-once delivery means this runs twice sooner or later, so key the real work on
+    (subject_id, correlation_id) rather than assuming a single invocation.
+    """
+    _ = (payload.subject_id, correlation_id)

package/templates/architectures/event-driven/files/src/__solutionName.snake__/handlers/__init__.py

@@ -0,0 +1 @@
+"""One package per handler. Handlers never import each other; they only share events."""

package/templates/architectures/event-driven/files/src/__solutionName.snake__/handlers/__secondHandler.snake__/__init__.py

@@ -0,0 +1,25 @@
+"""The second subscriber of the same event.
+
+Two independent reactions to one fact is the whole point of the style, and it is what makes the
+"handlers never import each other" check real rather than vacuous.
+"""
+
+from __future__ import annotations
+
+from ...broker import EventBroker
+from ...events import {{ firstEvent | upperSnake }}_V1, EventEnvelope, {{ firstEvent | pascal }}V1
+
+__all__ = ["register"]
+
+
+async def register(broker: EventBroker) -> None:
+    await broker.subscribe({{ firstEvent | upperSnake }}_V1.type, _on_{{ firstEvent | snake }})
+
+
+async def _on_{{ firstEvent | snake }}(envelope: EventEnvelope) -> None:
+    await _{{ secondHandler | snake }}({{ firstEvent | upperSnake }}_V1.parse(envelope.payload), envelope.correlation_id)
+
+
+async def _{{ secondHandler | snake }}(payload: {{ firstEvent | pascal }}V1, correlation_id: str) -> None:
+    """Must be idempotent — see the note in the {{ firstHandler | kebab }} handler."""
+    _ = (payload.subject_id, correlation_id)

package/templates/architectures/event-driven/files/src/__solutionName.snake__/publishers/__eventDomain.snake__.py

@@ -0,0 +1,17 @@
+"""Publishes {{ eventDomain | kebab }} facts. Knows the catalog and the broker port — never a subscriber."""
+
+from __future__ import annotations
+
+from ..broker import EventBroker
+from ..events import {{ firstEvent | upperSnake }}_V1, {{ firstEvent | pascal }}V1
+
+
+class {{ eventDomain | pascal }}Publisher:
+    def __init__(self, broker: EventBroker) -> None:
+        self._broker = broker
+
+    async def {{ firstEvent | snake }}(
+        self, payload: {{ firstEvent | pascal }}V1, correlation_id: str | None = None
+    ) -> None:
+        # Validate before publishing: a bad payload should fail here, not in every subscriber.
+        await self._broker.publish({{ firstEvent | upperSnake }}_V1.envelope(payload, correlation_id))

package/templates/architectures/event-driven/files/src/__solutionName.snake__/publishers/__init__.py

@@ -0,0 +1,5 @@
+"""Components that emit events. A publisher never imports a handler."""
+
+from .{{ eventDomain | snake }} import {{ eventDomain | pascal }}Publisher
+
+__all__ = ["{{ eventDomain | pascal }}Publisher"]

package/templates/architectures/event-driven/files/src/bootstrap/events.ts

@@ -0,0 +1,24 @@
+import { createBroker, loadBrokerConfig, type EventBroker } from '../broker/index.js';
+import { register{{ firstHandler | pascal }} } from '../handlers/{{ firstHandler | kebab }}/index.js';
+import { register{{ secondHandler | pascal }} } from '../handlers/{{ secondHandler | kebab }}/index.js';
+import {
+  create{{ eventDomain | pascal }}Publisher,
+  type {{ eventDomain | pascal }}Publisher,
+} from '../publishers/{{ eventDomain | kebab }}.publisher.js';
+
+export interface Eventing {
+  readonly broker: EventBroker;
+  readonly {{ eventDomain | camel }}: {{ eventDomain | pascal }}Publisher;
+}
+
+/** Composition root: the one file that knows every handler exists. Call it from your entrypoint. */
+export async function startEventing(): Promise<Eventing> {
+  const broker = createBroker(loadBrokerConfig());
+  await broker.start();
+
+  // Subscribe before anything publishes, or the first fan-out has nobody listening.
+  await register{{ firstHandler | pascal }}(broker);
+  await register{{ secondHandler | pascal }}(broker);
+
+  return { broker, {{ eventDomain | camel }}: create{{ eventDomain | pascal }}Publisher(broker) };
+}

package/templates/architectures/event-driven/files/src/broker/adapters/in-memory-broker.ts

@@ -0,0 +1,63 @@
+import type { EventEnvelope } from '../../events/index.js';
+import type { BrokerConfig } from '../config.js';
+import type { EventBroker, EventHandler } from '../port.js';
+
+/**
+ * Default adapter so a fresh repo runs with no infrastructure. It is deliberately NOT durable:
+ * nothing replays and a crash loses in-flight events — swap it before you depend on delivery.
+ */
+export class InMemoryEventBroker implements EventBroker {
+  readonly #config: BrokerConfig;
+  readonly #subscribers = new Map<string, EventHandler[]>();
+  readonly #deadLettered: EventEnvelope[] = [];
+
+  constructor(config: BrokerConfig) {
+    this.#config = config;
+  }
+
+  start(): Promise<void> {
+    return Promise.resolve();
+  }
+
+  stop(): Promise<void> {
+    this.#subscribers.clear();
+    return Promise.resolve();
+  }
+
+  subscribe(type: string, handler: EventHandler): Promise<void> {
+    const topic = this.#topic(type);
+    this.#subscribers.set(topic, [...(this.#subscribers.get(topic) ?? []), handler]);
+    return Promise.resolve();
+  }
+
+  /** Fan-out is independent: one failing subscriber must never stop the others. */
+  async publish(envelope: EventEnvelope): Promise<void> {
+    const subscribers = this.#subscribers.get(this.#topic(envelope.type)) ?? [];
+    await Promise.all(subscribers.map((handler) => this.#deliver(handler, envelope)));
+  }
+
+  /** What a real subscriber would read off the dead-letter topic. */
+  get deadLettered(): readonly EventEnvelope[] {
+    return this.#deadLettered;
+  }
+
+  /** Retry then dead-letter, because one poison message must not block the topic forever. */
+  async #deliver(handler: EventHandler, envelope: EventEnvelope): Promise<void> {
+    for (let attempt = 1; attempt <= this.#config.maxDeliveryAttempts; attempt += 1) {
+      try {
+        await handler(envelope);
+        return;
+      } catch (error) {
+        if (attempt === this.#config.maxDeliveryAttempts) {
+          this.#deadLettered.push(envelope);
+          const topic = this.#topic(envelope.type) + this.#config.deadLetterSuffix;
+          console.error(`dead-lettered ${envelope.id} (${envelope.type}) to ${topic}`, error);
+        }
+      }
+    }
+  }
+
+  #topic(type: string): string {
+    return `${this.#config.topicPrefix}.${type}`;
+  }
+}

package/templates/architectures/event-driven/files/src/broker/config.ts

@@ -0,0 +1,39 @@
+import process from 'node:process';
+
+/** Every broker tunable, one typed default each. Nothing else in the repo reads these vars. */
+export interface BrokerConfig {
+  readonly driver: string;
+  readonly url: string;
+  readonly topicPrefix: string;
+  readonly consumerGroup: string;
+  readonly maxDeliveryAttempts: number;
+  readonly deadLetterSuffix: string;
+}
+
+const defaults: BrokerConfig = {
+  driver: 'in-memory',
+  url: '',
+  topicPrefix: '{{ solutionName | kebab }}',
+  consumerGroup: '{{ solutionName | kebab }}',
+  maxDeliveryAttempts: 5,
+  deadLetterSuffix: '.dlq',
+};
+
+function positiveInt(value: string | undefined, fallback: number): number {
+  const parsed = Number(value);
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+export function loadBrokerConfig(env: Record<string, string | undefined> = process.env): BrokerConfig {
+  return {
+    driver: env.EVENT_BROKER_DRIVER ?? defaults.driver,
+    url: env.EVENT_BROKER_URL ?? defaults.url,
+    topicPrefix: env.EVENT_BROKER_TOPIC_PREFIX ?? defaults.topicPrefix,
+    consumerGroup: env.EVENT_BROKER_CONSUMER_GROUP ?? defaults.consumerGroup,
+    maxDeliveryAttempts: positiveInt(
+      env.EVENT_BROKER_MAX_DELIVERY_ATTEMPTS,
+      defaults.maxDeliveryAttempts,
+    ),
+    deadLetterSuffix: env.EVENT_BROKER_DEAD_LETTER_SUFFIX ?? defaults.deadLetterSuffix,
+  };
+}

package/templates/architectures/event-driven/files/src/broker/factory.ts

@@ -0,0 +1,13 @@
+import { InMemoryEventBroker } from './adapters/in-memory-broker.js';
+import type { BrokerConfig } from './config.js';
+import type { EventBroker } from './port.js';
+
+/** The only place a concrete adapter is named. Add a case per adapter you ship. */
+export function createBroker(config: BrokerConfig): EventBroker {
+  switch (config.driver) {
+    case 'in-memory':
+      return new InMemoryEventBroker(config);
+    default:
+      throw new Error(`Unknown EVENT_BROKER_DRIVER "${config.driver}"`);
+  }
+}

package/templates/architectures/event-driven/files/src/broker/index.ts

@@ -0,0 +1,6 @@
+// The broker's public surface: the port, its config, and the factory. Adapters are private —
+// `scripts/check-event-boundaries.mjs` fails the build if anything outside src/broker names one.
+export type { EventBroker, EventHandler } from './port.js';
+export type { BrokerConfig } from './config.js';
+export { loadBrokerConfig } from './config.js';
+export { createBroker } from './factory.js';

package/templates/architectures/event-driven/files/src/broker/port.ts

@@ -0,0 +1,15 @@
+import type { EventEnvelope } from '../events/index.js';
+
+export type EventHandler = (envelope: EventEnvelope) => Promise<void> | void;
+
+/**
+ * The seam the whole style hangs on. Publishers and handlers see only this, so moving from the
+ * in-memory adapter to Kafka, RabbitMQ or Service Bus is a new adapter and zero handler changes.
+ */
+export interface EventBroker {
+  publish(envelope: EventEnvelope): Promise<void>;
+  /** `type` is a versioned catalog name, so rolling out a v2 never breaks a v1 subscriber. */
+  subscribe(type: string, handler: EventHandler): Promise<void>;
+  start(): Promise<void>;
+  stop(): Promise<void>;
+}

package/templates/architectures/event-driven/files/src/events/__eventDomain.kebab__/__firstEvent.kebab__/v1.ts

@@ -0,0 +1,20 @@
+import { defineEvent, EventSchemaError } from '../../contract.js';
+
+/** Payload of {{ eventDomain | kebab }}.{{ firstEvent | kebab }} v1. Published contract: add a v2 beside it, never edit this. */
+export interface {{ firstEvent | pascal }}V1 {
+  readonly subjectId: string;
+  /** Denormalised on purpose — a consumer that calls back to the producer is coupled to it. */
+  readonly subjectName: string;
+}
+
+export const {{ firstEvent | camel }}V1 = defineEvent<{{ firstEvent | pascal }}V1>(
+  '{{ eventDomain | kebab }}.{{ firstEvent | kebab }}',
+  1,
+  (value) => {
+    const candidate = value as Partial<{{ firstEvent | pascal }}V1> | null | undefined;
+    if (typeof candidate?.subjectId !== 'string' || typeof candidate.subjectName !== 'string') {
+      throw new EventSchemaError('payload does not match {{ eventDomain | kebab }}.{{ firstEvent | kebab }}.v1');
+    }
+    return { subjectId: candidate.subjectId, subjectName: candidate.subjectName };
+  },
+);

package/templates/architectures/event-driven/files/src/events/contract.ts

@@ -0,0 +1,36 @@
+import { newEnvelope, type EventEnvelope } from './envelope.js';
+
+/** Thrown when a payload does not match the version it claims to be. */
+export class EventSchemaError extends Error {}
+
+/** The narrow view the catalog stores, so one map can hold every version of every event. */
+export interface CatalogEntry {
+  readonly name: string;
+  readonly version: number;
+  readonly type: string;
+  parse(value: unknown): unknown;
+}
+
+export interface EventContract<TPayload> extends CatalogEntry {
+  parse(value: unknown): TPayload;
+  envelope(payload: TPayload, correlationId?: string): EventEnvelope<TPayload>;
+}
+
+/**
+ * A new version is a new contract beside the old one, never an edit to it — subscribers of v1
+ * keep receiving v1 until they choose to migrate.
+ */
+export function defineEvent<TPayload>(
+  name: string,
+  version: number,
+  parse: (value: unknown) => TPayload,
+): EventContract<TPayload> {
+  const type = `${name}.v${version}`;
+  return {
+    name,
+    version,
+    type,
+    parse,
+    envelope: (payload, correlationId) => newEnvelope(type, payload, correlationId),
+  };
+}

package/templates/architectures/event-driven/files/src/events/envelope.ts

@@ -0,0 +1,20 @@
+import { randomUUID } from 'node:crypto';
+
+/** The only thing that crosses a boundary. A handler never receives another handler's types. */
+export interface EventEnvelope<TPayload = unknown> {
+  readonly id: string;
+  /** Catalog wire name including version, e.g. "{{ eventDomain | kebab }}.{{ firstEvent | kebab }}.v1". */
+  readonly type: string;
+  readonly occurredAt: string;
+  /** Stands in for the call stack you gave up — carry it into every event a handler emits. */
+  readonly correlationId: string;
+  readonly payload: TPayload;
+}
+
+export function newEnvelope<TPayload>(
+  type: string,
+  payload: TPayload,
+  correlationId: string = randomUUID(),
+): EventEnvelope<TPayload> {
+  return { id: randomUUID(), type, occurredAt: new Date().toISOString(), correlationId, payload };
+}

package/templates/architectures/event-driven/files/src/events/index.ts

@@ -0,0 +1,17 @@
+import type { CatalogEntry } from './contract.js';
+import { {{ firstEvent | camel }}V1 } from './{{ eventDomain | kebab }}/{{ firstEvent | kebab }}/v1.js';
+
+export { newEnvelope } from './envelope.js';
+export type { EventEnvelope } from './envelope.js';
+export { defineEvent, EventSchemaError } from './contract.js';
+export type { CatalogEntry, EventContract } from './contract.js';
+export { {{ firstEvent | camel }}V1 } from './{{ eventDomain | kebab }}/{{ firstEvent | kebab }}/v1.js';
+export type { {{ firstEvent | pascal }}V1 } from './{{ eventDomain | kebab }}/{{ firstEvent | kebab }}/v1.js';
+
+/**
+ * Every event this system publishes, by wire type. Registering here is what makes the folder a
+ * catalog rather than a pile of interfaces, and it is the list you diff during a version review.
+ */
+export const catalog: Readonly<Record<string, CatalogEntry>> = Object.freeze({
+  [{{ firstEvent | camel }}V1.type]: {{ firstEvent | camel }}V1,
+});