first commit

docs/api-stack/api/api-schemas/src/events/metadata.md

@@ -0,0 +1,64 @@
+# metadata
+
+## Purpose
+
+Defines the `EventMetadata` Zod schema for the distributed tracing and actor context attached to every domain event in the Suaveplan event-sourcing infrastructure. Metadata fields enable correlation of all events produced by a single user action, causation tracing between commands and their resulting events, and multi-tenant scoping of event streams — all without embedding these concerns in domain event payloads.
+
+## Features
+
+- `EventMetadata` schema — `{correlationId, causationId?, userId?, tenantId?}` with strict non-empty validation on all present string fields
+- `correlationId` required — enables log correlation and distributed trace aggregation across service boundaries
+- `causationId` optional — links this event to the specific command or event that caused it (event sourcing causal chain)
+- `userId` optional — identifies the human or service account that triggered the originating action
+- `tenantId` optional — scopes the event to a tenant in multi-tenant deployments
+- Full TypeScript inference via `z.infer<>` — no manual interface duplication
+- Zod v4 compatible
+
+## Usage: Basic Example
+
+```ts
+import { EventMetadata } from "@suaveplan/api-schemas/events";
+
+const meta = EventMetadata.parse({
+  correlationId: "corr_01J8ZGCZ7ECTFAKEUID123456",
+  userId: "user_abc",
+});
+```
+
+## Usage: Advanced Example
+
+```ts
+import { EventMetadata } from "@suaveplan/api-schemas/events";
+
+// Build metadata for an event triggered by a command
+function buildEventMetadata(
+  command: { correlationId: string; id: string },
+  ctx: { userId?: string; tenantId?: string }
+): EventMetadata {
+  return EventMetadata.parse({
+    correlationId: command.correlationId,
+    causationId: command.id,
+    userId: ctx.userId,
+    tenantId: ctx.tenantId,
+  });
+}
+```
+
+## API Reference
+
+### `EventMetadata`
+
+Zod object schema — event tracing and actor context.
+
+| Field           | Type               | Description                                             |
+|-----------------|--------------------|----------------------------------------------------------|
+| `correlationId` | `string` (min 1)   | Ties all events from one user action together           |
+| `causationId`   | `string` (optional)| ID of the command/event that caused this event          |
+| `userId`        | `string` (optional)| Actor who triggered the originating action              |
+| `tenantId`      | `string` (optional)| Tenant scope for multi-tenant deployments               |
+
+**Type export:** `type EventMetadata = z.infer<typeof EventMetadata>`
+
+## Implementation Notes
+
+`correlationId` is the only required field because it is the primary key for grouping related events in log aggregation and tracing systems. All other fields are optional because not every event originates from an identifiable user action (e.g. scheduled jobs, system-initiated events) or requires tenant scoping. Optional fields that are present are validated as non-empty strings to prevent accidentally storing blank identifiers that would pollute trace data.