@arki/event-sourcing 0.1.0 → 0.1.2

package/dist/dot.d.ts

@@ -37,9 +37,20 @@
  * load — that is intentional: the adapter only makes sense in a DOT app.
  */
 import type { EventStore, MessageBus } from '@event-driven-io/emmett';
-import type { DotPip } from '@arki/dot/pip';
+import type { EmptyShape, Pip } from '@arki/dot/pip';
 import type { CommandHandlerRegistration } from './command.js';
 import type { PostgreSQLProjectionInput } from './event-sourcing-features.js';
+/**
+ * Stable error codes thrown by the event-sourcing pip. Exported so consumers
+ * and coding agents can match against them — never parse the message.
+ *
+ * @see packages/dot/docs/principles.md — principle 1.3 ("errors are part
+ * of the API") and principle 4 ("agent-discoverable everywhere").
+ */
+export declare const EVENT_SOURCING_PIP_ERROR_CODES: {
+    /** boot was called without a configured event-store URL. */
+    readonly dbUrlNotConfigured: "EVENT_SOURCING_PIP_E001";
+};
 /**
  * Options for the event-sourcing DOT adapter.
  */
@@ -64,11 +75,6 @@ export type EventSourcingDotOptions = {
      * `process.env`. If none are set, `boot` throws.
      */
     readonly dbUrl?: string;
-    /**
-     * Pip name override. Defaults to `'event-sourcing'`. Use this only
-     * when composing multiple event-sourcing scopes inside the same app.
-     */
-    readonly name?: string;
 };
 /** Services published by the event-sourcing adapter. */
 export type EventSourcingServices = {
@@ -83,8 +89,8 @@ export type EventSourcingServices = {
 /**
  * Build a DOT pip that opens the event store, wires command handlers
  * into an in-memory message bus, and publishes both as services. The
- * kernel calls `dispose` in reverse-topological order to release the
+ * kernel calls `dispose` in reverse declaration order to release the
  * underlying PG pool.
  */
-export declare function eventSourcing(options: EventSourcingDotOptions): DotPip<EventSourcingServices>;
+export declare function eventSourcing(options: EventSourcingDotOptions): Pip<EmptyShape, EventSourcingServices>;
 //# sourceMappingURL=dot.d.ts.map

package/dist/dot.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dot.d.ts","sourceRoot":"","sources":["../src/dot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAEtE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAG5C,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAC;AAC/D,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,8BAA8B,CAAC;AAG9E;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAAG;IACpC;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,SAAS,yBAAyB,EAAE,CAAC;IAC3D;;;;;;OAMG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,0BAA0B,EAAE,CAAC;IACjE;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,wDAAwD;AACxD,MAAM,MAAM,qBAAqB,GAAG;IAClC,mEAAmE;IACnE,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;CACjC,CAAC;AAgBF;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,uBAAuB,GAAG,MAAM,CAAC,qBAAqB,CAAC,CA8B7F"}
+{"version":3,"file":"dot.d.ts","sourceRoot":"","sources":["../src/dot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAEtE,OAAO,KAAK,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,eAAe,CAAC;AAGrD,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAC;AAC/D,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,8BAA8B,CAAC;AAG9E;;;;;;GAMG;AACH,eAAO,MAAM,8BAA8B;IACzC,4DAA4D;;CAEpD,CAAC;AAEX;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAAG;IACpC;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,SAAS,yBAAyB,EAAE,CAAC;IAC3D;;;;;;OAMG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,0BAA0B,EAAE,CAAC;IACjE;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF,wDAAwD;AACxD,MAAM,MAAM,qBAAqB,GAAG;IAClC,mEAAmE;IACnE,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;CACjC,CAAC;AAgBF;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,uBAAuB,GAAG,GAAG,CAAC,UAAU,EAAE,qBAAqB,CAAC,CA2CtG"}

package/dist/dot.js

@@ -36,8 +36,19 @@
  * Importing this adapter without `@arki/dot` installed will fail at module
  * load — that is intentional: the adapter only makes sense in a DOT app.
  */
-import { defineDotPip } from '@arki/dot/pip';
+import { pip, DotPipError } from '@arki/dot/pip';
 import { EVENT_STORE_URL_VARIANTS, eventSourcingFeatures } from './event-sourcing-features.js';
+/**
+ * Stable error codes thrown by the event-sourcing pip. Exported so consumers
+ * and coding agents can match against them — never parse the message.
+ *
+ * @see packages/dot/docs/principles.md — principle 1.3 ("errors are part
+ * of the API") and principle 4 ("agent-discoverable everywhere").
+ */
+export const EVENT_SOURCING_PIP_ERROR_CODES = {
+    /** boot was called without a configured event-store URL. */
+    dbUrlNotConfigured: 'EVENT_SOURCING_PIP_E001',
+};
 /**
  * Resolve the event-store connection URL from explicit options first, then
  * from the recognised env vars in priority order. Returns `undefined` when
@@ -56,29 +67,40 @@ function resolveDbUrl(explicit) {
 /**
  * Build a DOT pip that opens the event store, wires command handlers
  * into an in-memory message bus, and publishes both as services. The
- * kernel calls `dispose` in reverse-topological order to release the
+ * kernel calls `dispose` in reverse declaration order to release the
  * underlying PG pool.
  */
 export function eventSourcing(options) {
-    const name = options.name ?? 'event-sourcing';
     const commandHandlers = options.commandHandlers ?? [];
     // Captured at boot so dispose can call it without re-reading services
     // (dispose is allowed to run even when services failed to publish).
     let closeStore;
-    return defineDotPip({
-        name,
+    return pip({
+        name: 'event-sourcing',
         version: '0.1.0',
-        provides: ['event-store', 'message-bus'],
         configure(ctx) {
             ctx.registerService('eventStore', 'event-store');
             ctx.registerService('messageBus', 'message-bus');
+            ctx.declareProvides('event-store', 'message-bus');
         },
         boot() {
+            // Validate at the pip boundary so the DOT lifecycle gets a coded
+            // error. `eventSourcingFeatures.initEventSourcing` still throws raw
+            // `Error` for non-DOT consumers (its public contract is unchanged);
+            // the check here makes sure we never reach it without a URL.
             const dbUrl = resolveDbUrl(options.dbUrl);
+            if (dbUrl === undefined) {
+                throw new DotPipError({
+                    code: EVENT_SOURCING_PIP_ERROR_CODES.dbUrlNotConfigured,
+                    message: '[event-sourcing] Event Store database URL is not configured.',
+                    remediation: `Pass options.dbUrl to eventSourcing(...) or set one of ${EVENT_STORE_URL_VARIANTS.join(', ')} in the environment before booting the app.`,
+                    docsUrl: 'https://arki.dev/dot/errors/event-sourcing-pip-e001',
+                });
+            }
             const { eventStore, close } = eventSourcingFeatures.initEventSourcing(options.projections, dbUrl);
             closeStore = close;
             const messageBus = eventSourcingFeatures.initMessageBus(eventStore, [...commandHandlers]);
-            return { services: { eventStore, messageBus } };
+            return { eventStore, messageBus };
         },
         async dispose() {
             if (closeStore !== undefined) {

package/dist/dot.js.map

@@ -1 +1 @@
-{"version":3,"file":"dot.js","sourceRoot":"","sources":["../src/dot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAKH,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAI7C,OAAO,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AA4C/F;;;;GAIG;AACH,SAAS,YAAY,CAAC,QAA4B;IAChD,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,KAAK,EAAE;QAAE,OAAO,QAAQ,CAAC;IAC/D,KAAK,MAAM,IAAI,IAAI,wBAAwB,EAAE,CAAC;QAC5C,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAChC,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,EAAE;YAAE,OAAO,KAAK,CAAC;IACxD,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,OAAgC;IAC5D,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,gBAAgB,CAAC;IAC9C,MAAM,eAAe,GAAG,OAAO,CAAC,eAAe,IAAI,EAAE,CAAC;IAEtD,sEAAsE;IACtE,oEAAoE;IACpE,IAAI,UAA6C,CAAC;IAElD,OAAO,YAAY,CAAwB;QACzC,IAAI;QACJ,OAAO,EAAE,OAAO;QAChB,QAAQ,EAAE,CAAC,aAAa,EAAE,aAAa,CAAC;QACxC,SAAS,CAAC,GAAG;YACX,GAAG,CAAC,eAAe,CAAC,YAAY,EAAE,aAAa,CAAC,CAAC;YACjD,GAAG,CAAC,eAAe,CAAC,YAAY,EAAE,aAAa,CAAC,CAAC;QACnD,CAAC;QACD,IAAI;YACF,MAAM,KAAK,GAAG,YAAY,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;YAC1C,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,GAAG,qBAAqB,CAAC,iBAAiB,CAAC,OAAO,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC;YAClG,UAAU,GAAG,KAAK,CAAC;YACnB,MAAM,UAAU,GAAG,qBAAqB,CAAC,cAAc,CAAC,UAAU,EAAE,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC;YAC1F,OAAO,EAAE,QAAQ,EAAE,EAAE,UAAU,EAAE,UAAU,EAAE,EAAE,CAAC;QAClD,CAAC;QACD,KAAK,CAAC,OAAO;YACX,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;gBAC7B,MAAM,UAAU,EAAE,CAAC;gBACnB,UAAU,GAAG,SAAS,CAAC;YACzB,CAAC;QACH,CAAC;KACF,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"dot.js","sourceRoot":"","sources":["../src/dot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAKH,OAAO,EAAE,GAAG,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAIjD,OAAO,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAE/F;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAG;IAC5C,4DAA4D;IAC5D,kBAAkB,EAAE,yBAAyB;CACrC,CAAC;AAuCX;;;;GAIG;AACH,SAAS,YAAY,CAAC,QAA4B;IAChD,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,KAAK,EAAE;QAAE,OAAO,QAAQ,CAAC;IAC/D,KAAK,MAAM,IAAI,IAAI,wBAAwB,EAAE,CAAC;QAC5C,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAChC,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,EAAE;YAAE,OAAO,KAAK,CAAC;IACxD,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,OAAgC;IAC5D,MAAM,eAAe,GAAG,OAAO,CAAC,eAAe,IAAI,EAAE,CAAC;IAEtD,sEAAsE;IACtE,oEAAoE;IACpE,IAAI,UAA6C,CAAC;IAElD,OAAO,GAAG,CAAC;QACT,IAAI,EAAE,gBAAgB;QACtB,OAAO,EAAE,OAAO;QAChB,SAAS,CAAC,GAAG;YACX,GAAG,CAAC,eAAe,CAAC,YAAY,EAAE,aAAa,CAAC,CAAC;YACjD,GAAG,CAAC,eAAe,CAAC,YAAY,EAAE,aAAa,CAAC,CAAC;YACjD,GAAG,CAAC,eAAe,CAAC,aAAa,EAAE,aAAa,CAAC,CAAC;QACpD,CAAC;QACD,IAAI;YACF,iEAAiE;YACjE,oEAAoE;YACpE,oEAAoE;YACpE,6DAA6D;YAC7D,MAAM,KAAK,GAAG,YAAY,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;YAC1C,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;gBACxB,MAAM,IAAI,WAAW,CAAC;oBACpB,IAAI,EAAE,8BAA8B,CAAC,kBAAkB;oBACvD,OAAO,EAAE,8DAA8D;oBACvE,WAAW,EAAE,0DAA0D,wBAAwB,CAAC,IAAI,CAClG,IAAI,CACL,6CAA6C;oBAC9C,OAAO,EAAE,qDAAqD;iBAC/D,CAAC,CAAC;YACL,CAAC;YACD,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,GAAG,qBAAqB,CAAC,iBAAiB,CAAC,OAAO,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC;YAClG,UAAU,GAAG,KAAK,CAAC;YACnB,MAAM,UAAU,GAAG,qBAAqB,CAAC,cAAc,CAAC,UAAU,EAAE,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC;YAC1F,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,CAAC;QACpC,CAAC;QACD,KAAK,CAAC,OAAO;YACX,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;gBAC7B,MAAM,UAAU,EAAE,CAAC;gBACnB,UAAU,GAAG,SAAS,CAAC;YACzB,CAAC;QACH,CAAC;KACF,CAAC,CAAC;AACL,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arki/event-sourcing",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Event sourcing primitives — event store, message bus, projections, process managers — built on Emmett for ARKI.",
   "license": "MIT",
   "repository": {
@@ -74,20 +74,26 @@
   },
   "files": [
     "dist/**",
+    "src/**",
+    "!src/**/*.test.*",
+    "!src/**/*.spec.*",
+    "!src/**/tests/**",
+    "!src/**/test/**",
+    "!src/**/__tests__/**",
     "README.md",
     "LICENSE",
     "package.json"
   ],
   "dependencies": {
-    "@arki/contracts": "0.0.1",
-    "@arki/log": "0.0.1",
+    "@arki/contracts": "0.0.2",
+    "@arki/log": "0.0.2",
     "@event-driven-io/emmett": "^0.41.0",
     "@event-driven-io/emmett-postgresql": "^0.41.0",
     "ansis": "^3.3.2",
     "drizzle-orm": "1.0.0-rc.1"
   },
   "peerDependencies": {
-    "@arki/dot": "^0.1.0"
+    "@arki/dot": "^0.1.2"
   },
   "peerDependenciesMeta": {
     "@arki/dot": {

package/src/builders/command-handler.ts

@@ -0,0 +1,77 @@
+import {
+  DeciderCommandHandler
+  
+  
+  
+  
+  
+} from '@event-driven-io/emmett';
+import type {Command, CommandHandlerResult, Event, EventStore, HandleOptions} from '@event-driven-io/emmett';
+
+import { debugBuilder } from '../debug.js';
+
+type DeciderConfig<State, CommandType, StreamEvent> = {
+  initialState: () => State;
+  evolve: (state: State, event: StreamEvent) => State;
+  decide: (command: CommandType, state: State) => StreamEvent | StreamEvent[];
+};
+
+/**
+ * Store-connected command handler function type.
+ *
+ * Given an event store, stream id, and one or more commands, it loads the
+ * current aggregate state from the stream, applies the decider's `decide`
+ * function, and appends the resulting events.
+ */
+export type CommandHandler<State, CommandType, StreamEvent extends Event> = <Store extends EventStore>(
+  eventStore: Store,
+  id: string,
+  commands: CommandType | CommandType[],
+  handleOptions?: HandleOptions<Store>,
+) => Promise<CommandHandlerResult<State, StreamEvent, Store>>;
+
+/**
+ * Creates a store-connected command handler from a decider configuration.
+ *
+ * This is the recommended way to create command handlers. It wraps Emmett's
+ * `DeciderCommandHandler` while lifting the `CommandType extends Command`
+ * constraint that prevents commands with custom metadata from type-checking.
+ *
+ * Emmett's `Command` type uses a conditional type for metadata:
+ * - When metadata is `undefined`, the `metadata` property is optional.
+ * - When metadata is defined, it becomes required.
+ *
+ * TypeScript cannot prove that a concrete command (with custom metadata)
+ * satisfies `extends Command` across these conditional branches. This wrapper
+ * bridges that gap with a single, localised type assertion — keeping all
+ * call sites fully type-safe.
+ *
+ * @example
+ * ```typescript
+ * const handler = defineCommandHandler({
+ *   initialState,
+ *   evolve,
+ *   decide,
+ * });
+ *
+ * export const bookCommandHandlers = BookCommands.map(commandType => ({
+ *   commandType,
+ *   handler,
+ *   getStreamName,
+ * }));
+ * ```
+ */
+export function defineCommandHandler<State, CommandType, StreamEvent extends Event>(
+  config: DeciderConfig<State, CommandType, StreamEvent>,
+): CommandHandler<State, CommandType, StreamEvent> {
+  debugBuilder('[command-handler] Creating command handler');
+
+  // DeciderCommandHandler constrains CommandType extends Command. At runtime
+  // the decide/evolve functions are called with the concrete command values —
+  // no metadata shape is enforced. We bridge the compile-time gap here.
+  type EmmettConfig = Parameters<typeof DeciderCommandHandler<State, Command, StreamEvent>>[0];
+  const emmettHandler = DeciderCommandHandler(config as EmmettConfig);
+
+  debugBuilder('[command-handler] Command handler created successfully');
+  return emmettHandler as CommandHandler<State, CommandType, StreamEvent>;
+}

package/src/builders/command.ts

@@ -0,0 +1,72 @@
+import type { z } from '@arki/contracts';
+
+import type { Command, DefaultCommandMetadata } from '../command.js';
+import type { DefaultRecord } from '../types.js';
+
+/**
+ * Configuration for defining a domain command factory.
+ */
+export type CommandConfig<
+  TType extends string,
+  TInput extends DefaultRecord,
+  TMetadata extends DefaultCommandMetadata | undefined = undefined,
+> = {
+  /** The command type string (e.g., 'CreateUser') */
+  type: TType;
+  /** Zod schema for validating command input */
+  inputSchema: z.ZodType<TInput>;
+  /** Optional Zod schema for validating command metadata */
+  metadataSchema?: z.ZodType<TMetadata>;
+};
+
+/**
+ * Creates a strongly-typed command factory function.
+ *
+ * This factory validates input and metadata using Zod schemas before
+ * creating commands that can be dispatched through a command flow or aggregate.
+ *
+ * @param config - Configuration object containing type, input schema, and optional metadata schema
+ * @returns A factory function that validates and creates commands
+ *
+ * @example
+ * ```ts
+ * const createUserCommand = defineCommand({
+ *   type: 'CreateUser',
+ *   inputSchema: z.object({ name: z.string(), email: z.email() }),
+ *   metadataSchema: z.object({ now: z.date(), issuedBy: z.string().uuid() }),
+ * });
+ *
+ * const command = createUserCommand(
+ *   { name: 'Ada', email: 'ada@example.org' },
+ *   { now: new Date(), issuedBy: 'usr_123' },
+ * );
+ * ```
+ */
+export function defineCommand<
+  TType extends string,
+  TInput extends DefaultRecord,
+  TMetadata extends DefaultCommandMetadata | undefined = undefined,
+>(
+  config: CommandConfig<TType, TInput, TMetadata>,
+): (input: TInput, metadata?: TMetadata) => Command<TType, TInput, TMetadata> {
+  const { type, inputSchema, metadataSchema } = config;
+
+  return (input: TInput, metadata?: TMetadata) => {
+    const validatedInput = inputSchema.parse(input);
+    const validatedMetadata = metadataSchema ? metadataSchema.parse(metadata) : metadata;
+
+    // Conditionally construct the command object based on whether metadata is provided
+    return (validatedMetadata === undefined
+      ? {
+          type,
+          data: validatedInput,
+          kind: 'Command' as const,
+        }
+      : {
+          type,
+          data: validatedInput,
+          metadata: validatedMetadata,
+          kind: 'Command' as const,
+        }) as unknown as Command<TType, TInput, TMetadata>;
+  };
+}

package/src/builders/decider.ts

@@ -0,0 +1,288 @@
+import type { Event as EmmettEvent } from '@event-driven-io/emmett';
+import type { z } from '@arki/contracts';
+
+import type { AnyEvent, Event } from '../event.js';
+import { debugBuilder } from '../debug.js';
+import { defineCommandHandler  } from './command-handler.js';
+import type {CommandHandler} from './command-handler.js';
+
+/**
+ * Applies a domain event to the current aggregate state and produces the next state.
+ */
+type Evolve<State, StreamEvent extends AnyEvent> = (state: State, event: StreamEvent) => State;
+
+/**
+ * Computes the domain events that should be emitted for an incoming command,
+ * based on the aggregate's current state.
+ */
+type Decide<State, Command, StreamEvent extends AnyEvent> = (command: Command, state: State) => StreamEvent[];
+
+/**
+ * Fluent builder for aggregate behaviour (aka "decider") definitions.
+ *
+ * In many event-sourcing texts this role is called an *aggregate*: an object that owns
+ * the authoritative state, knows how to rebuild itself from events (`evolve`), and
+ * decides which new events should be recorded when commands arrive (`decide`).
+ *
+ * We keep the historical Emmett name `Decider` to match upstream types, but the builder
+ * intentionally documents the aggregate semantics so domain code can align on that
+ * mental model.
+ *
+ * Capabilities:
+ * - Type safety through TypeScript generics
+ * - Optional Zod schemas to validate state evolution at runtime
+ * - Chainable configuration that terminates with `.handler()`, returning the executed aggregate contract
+ *
+ * @example
+ * ```typescript
+ * const cartAggregate = defineDecider()
+ *   .stateSchema(z.object({ items: z.array(z.string()), total: z.number() }))
+ *   .initialState(() => ({ items: [], total: 0 }))
+ *   .evolve((state, event) => {
+ *     if (event.type === 'ItemAdded') {
+ *       return {
+ *         items: [...state.items, event.data.item],
+ *         total: state.total + event.data.price,
+ *       };
+ *     }
+ *     return state;
+ *   })
+ *   .decide((command, state) => {
+ *     if (command.type === 'AddItem') {
+ *       return [
+ *         {
+ *           type: 'ItemAdded',
+ *           data: { item: command.data.item, price: command.data.price },
+ *         },
+ *       ];
+ *     }
+ *     return [];
+ *   })
+ *   .handler();
+ *
+ * const initial = cartAggregate.initialState();
+ * const events = cartAggregate.decide(addItemCommand, initial);
+ * const next = cartAggregate.evolve(initial, events[0]);
+ * ```
+ */
+class DeciderBuilder<State = never, Command = never, StreamEvent extends AnyEvent = never> {
+  private _stateSchema?: z.ZodType<State>;
+  private _initialStateFn?: () => State;
+  private _evolveFn?: Evolve<State, StreamEvent>;
+  private _decideFn?: Decide<State, Command, StreamEvent>;
+
+  /**
+   * Creates a deep copy of the builder to ensure immutability
+   * @private
+   */
+  private clone(): DeciderBuilder<State, Command, StreamEvent> {
+    const builder = new DeciderBuilder<State, Command, StreamEvent>();
+    builder._stateSchema = this._stateSchema;
+    builder._initialStateFn = this._initialStateFn;
+    builder._evolveFn = this._evolveFn;
+    builder._decideFn = this._decideFn;
+    return builder;
+  }
+
+  /**
+   * Sets the state schema for state validation
+   * @param schema - Zod schema for validating state
+   * @returns A new DeciderBuilder instance with the state schema set
+   */
+  stateSchema<TNewState>(schema: z.ZodType<TNewState>): DeciderBuilder<TNewState, Command, StreamEvent> {
+    const builder = new DeciderBuilder<TNewState, Command, StreamEvent>();
+    builder._stateSchema = schema;
+    builder._initialStateFn = this._initialStateFn as (() => TNewState) | undefined;
+    builder._evolveFn = this._evolveFn as Evolve<TNewState, StreamEvent> | undefined;
+    builder._decideFn = this._decideFn as Decide<TNewState, Command, StreamEvent> | undefined;
+    debugBuilder('[decider] Set state schema');
+    return builder;
+  }
+
+  /**
+   * Sets the initial state function
+   * @param fn - Function that returns the initial state for a new aggregate
+   * @returns A new DeciderBuilder instance with the initial state function set
+   */
+  initialState(fn: () => State): DeciderBuilder<State, Command, StreamEvent> {
+    const builder = this.clone();
+    builder._initialStateFn = fn;
+    debugBuilder('[decider] Set initial state function');
+    return builder;
+  }
+
+  /**
+   * Sets the evolve function
+   *
+   * This method is generic and will infer the StreamEvent type from the function parameter,
+   * allowing TypeScript to properly infer complex discriminated union types.
+   *
+   * @template TStreamEvent - The union type of all events (inferred from fn parameter)
+   * @param fn - Function that applies an event to state to compute the next state
+   * @returns A new DeciderBuilder instance with the evolve function and inferred event types set
+   */
+  evolve<TStreamEvent extends AnyEvent>(fn: Evolve<State, TStreamEvent>): DeciderBuilder<State, Command, TStreamEvent> {
+    const builder = new DeciderBuilder<State, Command, TStreamEvent>();
+    builder._stateSchema = this._stateSchema;
+    builder._initialStateFn = this._initialStateFn;
+    builder._evolveFn = fn;
+    builder._decideFn = this._decideFn as Decide<State, Command, TStreamEvent> | undefined;
+    debugBuilder('[decider] Set evolve function');
+    return builder;
+  }
+
+  /**
+   * Sets the decide function
+   *
+   * This method is generic and will infer the Command type from the function parameter,
+   * allowing TypeScript to properly infer complex discriminated union types.
+   *
+   * @template TCommand - The union type of all commands (inferred from fn parameter)
+   * @param fn - Function that determines which events to emit for a given command and state
+   * @returns A new DeciderBuilder instance with the decide function and inferred command types set
+   */
+  decide<TCommand>(fn: Decide<State, TCommand, StreamEvent>): DeciderBuilder<State, TCommand, StreamEvent> {
+    const builder = new DeciderBuilder<State, TCommand, StreamEvent>();
+    builder._stateSchema = this._stateSchema;
+    builder._initialStateFn = this._initialStateFn;
+    builder._evolveFn = this._evolveFn;
+    builder._decideFn = fn;
+    debugBuilder('[decider] Set decide function');
+    return builder;
+  }
+
+  /**
+   * Terminal method that creates the decider
+   *
+   * Validates that all required functions are set and returns an object
+   * with three validated functions:
+   * - initialState: Returns the validated initial state
+   * - evolve: Applies an event to state with validation
+   * - decide: Determines events to emit with validation
+   *
+   * @returns An object containing the three core decider functions
+   * @throws Error if state schema, initial state function, evolve function, or decide function are not defined
+   */
+  handler(): {
+    initialState: () => State;
+    evolve: Evolve<State, StreamEvent>;
+    decide: Decide<State, Command, StreamEvent>;
+  } {
+    if (!this._stateSchema || !this._initialStateFn || !this._evolveFn || !this._decideFn) {
+      debugBuilder('[decider] ERROR: Missing required properties');
+      throw new Error(
+        'Decider must have state schema, initial state function, evolve function, and decide function defined',
+      );
+    }
+
+    const stateSchema = this._stateSchema;
+    const initialStateFn = this._initialStateFn;
+    const evolveFn = this._evolveFn;
+    const decideFn = this._decideFn;
+
+    debugBuilder('[decider] Building decider handler');
+
+    return {
+      initialState: () => {
+        debugBuilder('[decider] Getting initial state');
+        const state = initialStateFn();
+        return stateSchema.parse(state);
+      },
+      evolve: (state: State, event: StreamEvent) => {
+        debugBuilder('[decider] Evolving state with event: %s', (event as Event).type);
+        const validatedState = stateSchema.parse(state);
+        const nextState = evolveFn(validatedState, event);
+        return stateSchema.parse(nextState);
+      },
+      decide: (command: Command, state: State) => {
+        debugBuilder('[decider] Deciding events for command: %s', (command as { type: string }).type);
+        const validatedState = stateSchema.parse(state);
+        const events = decideFn(command, validatedState);
+        debugBuilder('[decider] Generated %d event(s)', events.length);
+        return events;
+      },
+    };
+  }
+
+  /**
+   * Terminal method that creates a store-connected command handler.
+   *
+   * Unlike `.handler()`, this does **not** require a state schema — it creates
+   * a handler that can be registered directly with an event store. Internally
+   * it delegates to `defineCommandHandler`, which bridges the Emmett type
+   * constraint on command metadata.
+   *
+   * Use this when you need a handler that reads/writes events from a store
+   * (the common case for aggregates), rather than the raw decider functions.
+   *
+   * @returns A store-connected command handler function
+   * @throws Error if initial state, evolve, or decide functions are not defined
+   *
+   * @example
+   * ```typescript
+   * const handler = defineDecider()
+   *   .initialState(() => null as BookState)
+   *   .evolve(evolve)
+   *   .decide(decide)
+   *   .commandHandler();
+   * ```
+   */
+  commandHandler(): StreamEvent extends EmmettEvent ? CommandHandler<State, Command, StreamEvent> : never {
+    if (!this._initialStateFn || !this._evolveFn || !this._decideFn) {
+      debugBuilder('[decider] ERROR: Missing required properties for command handler');
+      throw new Error(
+        'Decider must have initial state function, evolve function, and decide function defined to create a command handler',
+      );
+    }
+
+    debugBuilder('[decider] Building store-connected command handler');
+    return defineCommandHandler({
+      initialState: this._initialStateFn,
+      evolve: this._evolveFn,
+      decide: this._decideFn,
+    }) as StreamEvent extends EmmettEvent ? CommandHandler<State, Command, StreamEvent> : never;
+  }
+}
+
+/**
+ * Factory function to create a new DeciderBuilder
+ *
+ * **Recommended API**: This builder API supports complex discriminated unions
+ * through parameter-based type inference. The `.evolve()` and `.decide()` methods
+ * are generic and will automatically infer types from your function parameters.
+ *
+ * **Use cases:**
+ * - ✅ All cases (simple and complex)
+ * - ✅ Complex discriminated unions (10+ command/event types)
+ * - ✅ Fluent, chainable API preference
+ * - ✅ Automatic type inference from function parameters
+ *
+ * @example
+ * ```typescript
+ * // Works for both simple and complex union types
+ * const decider = defineDecider()
+ *   .stateSchema(myStateSchema)
+ *   .initialState(() => ({ ... }))
+ *   .evolve((state, event) => {
+ *     // TypeScript infers event type from this function
+ *     switch (event.type) {
+ *       case 'EventA': return { ... };
+ *       case 'EventB': return { ... };
+ *       // ... handles 10+ event types correctly
+ *     }
+ *   })
+ *   .decide((command, state) => {
+ *     // TypeScript infers command type from this function
+ *     switch (command.type) {
+ *       case 'CommandA': return [{ type: 'EventA', ... }];
+ *       case 'CommandB': return [{ type: 'EventB', ... }];
+ *       // ... handles 10+ command types correctly
+ *     }
+ *   })
+ *   .handler();
+ * ```
+ */
+export function defineDecider(): DeciderBuilder {
+  debugBuilder('[decider] Creating new decider builder');
+  return new DeciderBuilder();
+}

package/src/builders/event.ts

@@ -0,0 +1,68 @@
+import type { z } from '@arki/contracts';
+
+import type { Event } from '../event.js';
+import type { DefaultRecord } from '../types.js';
+
+/**
+ * Configuration for defining a domain event factory.
+ */
+export type EventConfig<
+  TType extends string,
+  TData extends DefaultRecord,
+  TMetadata extends DefaultRecord | undefined = undefined,
+> = {
+  /** The event type string (e.g., 'UserCreated') */
+  type: TType;
+  /** Zod schema for validating event data */
+  dataSchema: z.ZodType<TData>;
+  /** Optional Zod schema for validating event metadata */
+  metadataSchema?: z.ZodType<TMetadata>;
+};
+
+/**
+ * Creates a strongly-typed event factory function.
+ *
+ * This factory validates data and metadata using Zod schemas before
+ * creating events that can be appended to Emmett's event store.
+ *
+ * @param config - Configuration object containing type, data schema, and optional metadata schema
+ * @returns A factory function that validates and creates events
+ *
+ * @example
+ * ```ts
+ * const userCreatedEvent = defineEvent({
+ *   type: 'UserCreated',
+ *   dataSchema: z.object({ userId: z.string().uuid(), name: z.string() }),
+ *   metadataSchema: z.object({ now: z.date(), correlationId: z.string().uuid() }),
+ * });
+ *
+ * const event = userCreatedEvent(
+ *   { userId: 'usr_123', name: 'Ada' },
+ *   { now: new Date(), correlationId: 'corr_456' },
+ * );
+ * ```
+ */
+export function defineEvent<
+  TType extends string,
+  TData extends DefaultRecord,
+  TMetadata extends DefaultRecord | undefined = undefined,
+>(config: EventConfig<TType, TData, TMetadata>): (data: TData, metadata?: TMetadata) => Event<TType, TData, TMetadata> {
+  const { type, dataSchema, metadataSchema } = config;
+
+  return (data: TData, metadata?: TMetadata) => {
+    const validatedData = dataSchema.parse(data);
+    const validatedMetadata = metadataSchema ? metadataSchema.parse(metadata) : metadata;
+
+    // Conditionally construct the event object based on whether metadata is provided
+    return (validatedMetadata === undefined
+      ? {
+          type,
+          data: validatedData,
+        }
+      : {
+          type,
+          data: validatedData,
+          metadata: validatedMetadata,
+        }) as unknown as Event<TType, TData, TMetadata>;
+  };
+}