first commit

docs/networking/events/event-sourcing/src/schemas/event-sourcing.schemas.md

@@ -0,0 +1,66 @@
+# event-sourcing.schemas
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+Provides Zod validation schemas for all public wire-format types in `@suaveplan/event-sourcing`. These schemas are used at integration boundaries — when deserialising events from persistence layers, validating snapshot data, and parsing upcaster registrations — to ensure structural integrity before domain logic runs.
+
+## Features
+
+- `DomainEventSchema` — validates the full event envelope including version, metadata, and typed occurredAt
+- `SnapshotSchema` — validates aggregate snapshots before loading into aggregates
+- `EventMetadataSchema` — validates event metadata with passthrough for unknown keys
+- `MemoryEventStoreOptionsSchema` — validates store construction options
+- `UpcasterOptionsSchema` — validates upcaster registration including the migration function
+
+## Usage: Basic Example
+
+```ts
+import { DomainEventSchema } from "@suaveplan/event-sourcing";
+
+const raw = JSON.parse(storedJson);
+const event = DomainEventSchema.parse({ ...raw, occurredAt: new Date(raw.occurredAt) });
+```
+
+## Usage: Advanced Example
+
+```ts
+import { SnapshotSchema } from "@suaveplan/event-sourcing";
+import z from "zod";
+
+const MyStateSchema = z.object({ balance: z.number() });
+
+const snapshot = SnapshotSchema.extend({
+  state: MyStateSchema,
+}).parse(rawSnapshot);
+
+// snapshot.state is typed as { balance: number }
+```
+
+## API Reference
+
+### `DomainEventSchema`
+
+Validates `{ id, aggregateId, aggregateType, type, version, payload, metadata, occurredAt }`. Version must be a positive integer. `occurredAt` must be a `Date`.
+
+### `SnapshotSchema`
+
+Validates `{ aggregateId, aggregateType, version, state, takenAt }`. Version is non-negative integer.
+
+### `EventMetadataSchema`
+
+Validates optional `causationId`, `correlationId`, `actor` and passes through unknown keys.
+
+### `MemoryEventStoreOptionsSchema`
+
+Optional schema; validates `maxStreamLength` as positive integer if present.
+
+### `UpcasterOptionsSchema`
+
+Validates `{ eventType, fromVersion, toVersion, upcast }`. `fromVersion` must be non-negative; `toVersion` must be positive.
+
+## Implementation Notes
+
+All schemas use `.passthrough()` on metadata to avoid stripping custom keys. The `payload` and `state` fields use `z.unknown()` since the concrete shape depends on the event type — callers may extend the schema for stricter validation.