@quanticjs/core 1.1.1

package/src/cqrs/behaviors/WorkflowBehavior.spec.ts

@@ -0,0 +1,97 @@
+import { WorkflowBehavior } from './WorkflowBehavior';
+import { Workflow } from '../decorators/Workflow.decorator';
+import { Result } from '../../result/Result';
+import { WorkflowEngine, WorkflowStartResult } from '../interfaces/WorkflowEngine';
+
+const mockEngine: jest.Mocked<WorkflowEngine> = {
+  startProcess: jest.fn(),
+  signalProcess: jest.fn(),
+  abortProcess: jest.fn(),
+};
+
+@Workflow('onboarding-process')
+class DecoratedCommand {
+  constructor(public readonly userId: string) {}
+}
+
+@Workflow('guarded-process', { fallback: 'skip' })
+class SkipFallbackCommand {
+  constructor(public readonly id: string) {}
+}
+
+class PlainCommand {
+  constructor(public readonly id: string) {}
+}
+
+describe('WorkflowBehavior', () => {
+  let behavior: WorkflowBehavior;
+  let next: jest.Mock;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    behavior = new WorkflowBehavior(mockEngine);
+    next = jest.fn().mockResolvedValue(Result.success({ done: true }));
+  });
+
+  it('passes through commands without @Workflow decorator', async () => {
+    const cmd = new PlainCommand('123');
+    const result = await behavior.execute(cmd, next);
+
+    expect(next).toHaveBeenCalled();
+    expect(result.isSuccess).toBe(true);
+    expect(mockEngine.startProcess).not.toHaveBeenCalled();
+  });
+
+  it('short-circuits decorated commands and starts a process', async () => {
+    const startResult: WorkflowStartResult = {
+      workflowInstanceId: 'wf-1',
+      processInstanceId: 'pi-1',
+      status: 'STARTED',
+    };
+    mockEngine.startProcess.mockResolvedValue(startResult);
+
+    const cmd = new DecoratedCommand('user-42');
+    const result = await behavior.execute(cmd, next);
+
+    expect(next).not.toHaveBeenCalled();
+    expect(mockEngine.startProcess).toHaveBeenCalledWith(
+      'onboarding-process',
+      cmd,
+      { commandType: 'DecoratedCommand' },
+    );
+    expect(result.isSuccess).toBe(true);
+    expect(result.value).toEqual(startResult);
+  });
+
+  it('passes through when no WorkflowEngine is injected', async () => {
+    const behaviorNoEngine = new WorkflowBehavior(undefined);
+    const cmd = new DecoratedCommand('user-42');
+
+    const result = await behaviorNoEngine.execute(cmd, next);
+
+    expect(next).toHaveBeenCalled();
+    expect(result.isSuccess).toBe(true);
+  });
+
+  it('applies fallback throw on engine error', async () => {
+    mockEngine.startProcess.mockRejectedValue(new Error('connection refused'));
+
+    const cmd = new DecoratedCommand('user-42');
+    const result = await behavior.execute(cmd, next);
+
+    expect(next).not.toHaveBeenCalled();
+    expect(result.isSuccess).toBe(false);
+    expect(result.errorMessage).toContain('Workflow start failed');
+    expect(result.errorMessage).toContain('connection refused');
+  });
+
+  it('applies fallback skip on engine error (calls next)', async () => {
+    mockEngine.startProcess.mockRejectedValue(new Error('timeout'));
+
+    const cmd = new SkipFallbackCommand('123');
+    const result = await behavior.execute(cmd, next);
+
+    expect(next).toHaveBeenCalled();
+    expect(result.isSuccess).toBe(true);
+  });
+});

package/src/cqrs/behaviors/WorkflowBehavior.ts

@@ -0,0 +1,62 @@
+import { Injectable, Optional, Inject, Logger } from '@nestjs/common';
+import { getWorkflowMetadata } from '../decorators/Workflow.decorator';
+import { WORKFLOW_ENGINE, WorkflowEngine } from '../interfaces/WorkflowEngine';
+import { Result, ErrorType } from '../../result/Result';
+
+@Injectable()
+export class WorkflowBehavior {
+  private readonly logger = new Logger(WorkflowBehavior.name);
+
+  constructor(
+    @Optional() @Inject(WORKFLOW_ENGINE)
+    private readonly engine?: WorkflowEngine,
+  ) {}
+
+  async execute<T>(
+    command: object,
+    next: () => Promise<Result<T>>,
+  ): Promise<Result<T>> {
+    const metadata = getWorkflowMetadata(command.constructor);
+
+    if (!metadata) {
+      return next();
+    }
+
+    if (!this.engine) {
+      this.logger.debug('No WorkflowEngine provided, skipping workflow behavior');
+      return next();
+    }
+
+    try {
+      const result = await this.engine.startProcess(
+        metadata.processDefinitionId,
+        command,
+        { commandType: command.constructor.name },
+      );
+      return Result.success(result as unknown as T);
+    } catch (error: any) {
+      const fallback = metadata.fallback ?? 'throw';
+
+      this.logger.warn(
+        `Workflow start failed for "${metadata.processDefinitionId}", applying fallback: ${fallback}`,
+        error.message,
+      );
+
+      switch (fallback) {
+        case 'skip':
+          return next();
+        case 'queue':
+          return Result.failure<T>(
+            ErrorType.InternalError,
+            `Workflow queuing not available without companion package: ${error.message}`,
+          );
+        case 'throw':
+        default:
+          return Result.failure<T>(
+            ErrorType.InternalError,
+            `Workflow start failed: ${error.message}`,
+          );
+      }
+    }
+  }
+}

package/src/cqrs/constants.ts

@@ -0,0 +1,2 @@
+/** Injection token for the Redis client (ioredis) */
+export const REDIS_CLIENT = 'REDIS_CLIENT';

package/src/cqrs/decorators/Cache.decorator.ts

@@ -0,0 +1,24 @@
+import 'reflect-metadata';
+
+const CACHE_KEY = 'arex:cache';
+
+export interface CacheOptions {
+  /** Cache key template — use {propName} for interpolation, e.g. 'user:{id}' */
+  key: string;
+  /** TTL in seconds (default: 60) */
+  ttlSeconds?: number;
+}
+
+/**
+ * @Cache('key:{prop}', { ttlSeconds: 60 }) — caches query results in Redis.
+ * Reads from cache on hit; sets on miss with TTL.
+ */
+export function Cache(key: string, options: Omit<CacheOptions, 'key'> = {}): ClassDecorator {
+  return (target: object) => {
+    Reflect.defineMetadata(CACHE_KEY, { key, ttlSeconds: 60, ...options }, target);
+  };
+}
+
+export function getCacheMetadata(target: object): CacheOptions | undefined {
+  return Reflect.getMetadata(CACHE_KEY, target);
+}

package/src/cqrs/decorators/DistributedLock.decorator.ts

@@ -0,0 +1,34 @@
+import 'reflect-metadata';
+
+const LOCK_KEY = 'arex:distributed-lock';
+
+export interface DistributedLockOptions {
+  /** Lock key template — use {propName} for interpolation */
+  key: string;
+  /** Max time to wait for lock acquisition in seconds (default: 5) */
+  acquireTimeoutSeconds?: number;
+  /** Lock auto-release time in seconds (default: 30) */
+  lockTtlSeconds?: number;
+}
+
+/**
+ * @DistributedLock('key:{prop}') — acquires a Redis distributed lock before execution.
+ * Throws ConflictException on timeout.
+ */
+export function DistributedLock(
+  key: string,
+  options: Omit<DistributedLockOptions, 'key'> = {},
+): ClassDecorator {
+  return (target: object) => {
+    Reflect.defineMetadata(LOCK_KEY, {
+      key,
+      acquireTimeoutSeconds: 5,
+      lockTtlSeconds: 30,
+      ...options,
+    }, target);
+  };
+}
+
+export function getDistributedLockMetadata(target: object): DistributedLockOptions | undefined {
+  return Reflect.getMetadata(LOCK_KEY, target);
+}

package/src/cqrs/decorators/FeatureFlag.decorator.ts

@@ -0,0 +1,23 @@
+import 'reflect-metadata';
+
+const FEATURE_FLAG_KEY = 'arex:feature-flag';
+
+export interface FeatureFlagOptions {
+  fallback?: 'throw' | 'skip' | 'default';
+  defaultValue?: unknown;
+}
+
+export function FeatureFlag(
+  flagName: string,
+  options: FeatureFlagOptions = { fallback: 'throw' },
+): ClassDecorator {
+  return (target: object) => {
+    Reflect.defineMetadata(FEATURE_FLAG_KEY, { flagName, ...options }, target);
+  };
+}
+
+export function getFeatureFlagMetadata(
+  target: object,
+): { flagName: string } & FeatureFlagOptions | undefined {
+  return Reflect.getMetadata(FEATURE_FLAG_KEY, target);
+}

package/src/cqrs/decorators/InvalidateCache.decorator.spec.ts

@@ -0,0 +1,20 @@
+import { InvalidateCache, getInvalidateCacheMetadata } from './InvalidateCache.decorator';
+
+@InvalidateCache(['user:{userId}', 'users:list'])
+class DecoratedCommand {}
+
+class PlainCommand {}
+
+describe('InvalidateCache decorator', () => {
+  it('should store metadata on decorated class', () => {
+    const metadata = getInvalidateCacheMetadata(DecoratedCommand);
+
+    expect(metadata).toEqual({ keys: ['user:{userId}', 'users:list'] });
+  });
+
+  it('should return undefined for undecorated class', () => {
+    const metadata = getInvalidateCacheMetadata(PlainCommand);
+
+    expect(metadata).toBeUndefined();
+  });
+});

package/src/cqrs/decorators/InvalidateCache.decorator.ts

@@ -0,0 +1,17 @@
+import 'reflect-metadata';
+
+const INVALIDATE_CACHE_KEY = 'arex:invalidate-cache';
+
+export interface InvalidateCacheOptions {
+  keys: string[];
+}
+
+export function InvalidateCache(keys: string[]): ClassDecorator {
+  return (target: object) => {
+    Reflect.defineMetadata(INVALIDATE_CACHE_KEY, { keys }, target);
+  };
+}
+
+export function getInvalidateCacheMetadata(target: object): InvalidateCacheOptions | undefined {
+  return Reflect.getMetadata(INVALIDATE_CACHE_KEY, target);
+}

package/src/cqrs/decorators/IsolatedTransaction.decorator.ts

@@ -0,0 +1,24 @@
+import 'reflect-metadata';
+
+const ISOLATED_TRANSACTION_KEY = 'arex:isolated-transaction';
+
+/**
+ * @IsolatedTransaction() — forces a command to run in its own dedicated transaction,
+ * even when an outer transaction scope already exists.
+ *
+ * Use for operations that must commit independently of the parent flow:
+ * - Audit logging (must persist even if the business operation rolls back)
+ * - Notifications / side-effects that should not be lost on rollback
+ *
+ * By default all commands share the ambient transaction (UnitOfWork pattern).
+ * This decorator opts out of that behavior.
+ */
+export function IsolatedTransaction(): ClassDecorator {
+  return (target: object) => {
+    Reflect.defineMetadata(ISOLATED_TRANSACTION_KEY, true, target);
+  };
+}
+
+export function isIsolatedTransaction(target: object): boolean {
+  return Reflect.getMetadata(ISOLATED_TRANSACTION_KEY, target) === true;
+}

package/src/cqrs/decorators/Log.decorator.ts

@@ -0,0 +1,22 @@
+import 'reflect-metadata';
+
+const LOG_KEY = 'arex:log';
+
+export interface LogOptions {
+  /** Whether to log the command/query payload (default: true) */
+  logPayload?: boolean;
+}
+
+/**
+ * @Log() — marks a command/query for automatic entry/exit logging.
+ * Applied globally by QuanticCommandBus/QuanticQueryBus when no explicit decorator is present.
+ */
+export function Log(options: LogOptions = {}): ClassDecorator {
+  return (target: object) => {
+    Reflect.defineMetadata(LOG_KEY, { logPayload: true, ...options }, target);
+  };
+}
+
+export function getLogMetadata(target: object): LogOptions | undefined {
+  return Reflect.getMetadata(LOG_KEY, target);
+}

package/src/cqrs/decorators/Validate.decorator.ts

@@ -0,0 +1,39 @@
+import 'reflect-metadata';
+import type { ICommandValidator } from '../validation/ICommandValidator';
+
+const VALIDATE_KEY = 'arex:validate';
+const VALIDATOR_CLASS_KEY = 'arex:validator-class';
+
+type ValidatorClass = new () => ICommandValidator;
+
+/**
+ * @Validate(ValidatorClass) — links a command/query to its Zod-based validator.
+ *
+ * The ValidationBehavior instantiates the validator and calls validate()
+ * before the handler runs. Returns Result.validationError() on failure.
+ *
+ * Usage:
+ * ```typescript
+ * @Validate(BlockUserValidator)
+ * export class BlockUserCommand {
+ *   constructor(
+ *     public readonly blockerId: string,
+ *     public readonly blockedUserId: string,
+ *   ) {}
+ * }
+ * ```
+ */
+export function Validate(validatorClass: ValidatorClass): ClassDecorator {
+  return (target: object) => {
+    Reflect.defineMetadata(VALIDATE_KEY, true, target);
+    Reflect.defineMetadata(VALIDATOR_CLASS_KEY, validatorClass, target);
+  };
+}
+
+export function shouldValidate(target: object): boolean {
+  return Reflect.getMetadata(VALIDATE_KEY, target) === true;
+}
+
+export function getValidatorClass(target: object): ValidatorClass | undefined {
+  return Reflect.getMetadata(VALIDATOR_CLASS_KEY, target);
+}

package/src/cqrs/decorators/Workflow.decorator.ts

@@ -0,0 +1,22 @@
+import 'reflect-metadata';
+
+const WORKFLOW_KEY = 'arex:workflow';
+
+export interface WorkflowOptions {
+  fallback?: 'throw' | 'skip' | 'queue';
+}
+
+export function Workflow(
+  processDefinitionId: string,
+  options?: WorkflowOptions,
+): ClassDecorator {
+  return (target: object) => {
+    Reflect.defineMetadata(WORKFLOW_KEY, { processDefinitionId, ...options }, target);
+  };
+}
+
+export function getWorkflowMetadata(
+  target: object,
+): { processDefinitionId: string } & WorkflowOptions | undefined {
+  return Reflect.getMetadata(WORKFLOW_KEY, target);
+}

package/src/cqrs/interfaces/WorkflowEngine.ts

@@ -0,0 +1,19 @@
+export const WORKFLOW_ENGINE = Symbol('WORKFLOW_ENGINE');
+
+export interface WorkflowStartResult {
+  workflowInstanceId: string;
+  processInstanceId: string;
+  status: 'STARTED';
+}
+
+export interface WorkflowEngine {
+  startProcess(
+    processDefinitionId: string,
+    command: object,
+    metadata: { commandType: string; correlationId?: string },
+  ): Promise<WorkflowStartResult>;
+
+  signalProcess(processInstanceId: string, signal: string, data?: unknown): Promise<void>;
+
+  abortProcess(processInstanceId: string): Promise<void>;
+}

package/src/cqrs/pipeline/QuanticCommandBus.ts

@@ -0,0 +1,69 @@
+import { Inject, Injectable, Logger, OnModuleInit, Optional } from '@nestjs/common';
+import { CommandBus } from '@nestjs/cqrs';
+import { Result } from '../../result/Result';
+import { LogBehavior } from '../behaviors/LogBehavior';
+import { FeatureFlagBehavior } from '../behaviors/FeatureFlagBehavior';
+import { ValidationBehavior } from '../behaviors/ValidationBehavior';
+import { CacheBehavior } from '../behaviors/CacheBehavior';
+import { DistributedLockBehavior } from '../behaviors/DistributedLockBehavior';
+import { TransactionalBehavior } from '../behaviors/TransactionalBehavior';
+import { PerformanceBehavior } from '../behaviors/PerformanceBehavior';
+import { WorkflowBehavior } from '../behaviors/WorkflowBehavior';
+import { InvalidateCacheBehavior } from '../behaviors/InvalidateCacheBehavior';
+import { BehaviorFn, runPipeline } from './runPipeline';
+
+/**
+ * QuanticCommandBus — wraps the @nestjs/cqrs CommandBus with a behavior pipeline.
+ *
+ * Pipeline order:
+ *   InvalidateCache → Log → Performance → FeatureFlag → Validate → Workflow → Cache → DistributedLock → Transactional → Handler
+ *
+ * Controllers inject the standard CommandBus from @nestjs/cqrs.
+ * This class patches its execute() in onModuleInit so the pipeline is transparent.
+ */
+@Injectable()
+export class QuanticCommandBus implements OnModuleInit {
+  private readonly logger = new Logger(QuanticCommandBus.name);
+  private behaviors: BehaviorFn[] = [];
+  private originalExecute!: CommandBus['execute'];
+
+  constructor(
+    private readonly commandBus: CommandBus,
+    private readonly logBehavior: LogBehavior,
+    private readonly performanceBehavior: PerformanceBehavior,
+    @Optional() @Inject(FeatureFlagBehavior) private readonly featureFlagBehavior: FeatureFlagBehavior | undefined,
+    private readonly validationBehavior: ValidationBehavior,
+    @Optional() @Inject(WorkflowBehavior) private readonly workflowBehavior: WorkflowBehavior | undefined,
+    private readonly cacheBehavior: CacheBehavior,
+    private readonly distributedLockBehavior: DistributedLockBehavior,
+    private readonly transactionalBehavior: TransactionalBehavior,
+    private readonly invalidateCacheBehavior: InvalidateCacheBehavior,
+  ) {}
+
+  onModuleInit() {
+    const optional = (behavior: { execute: BehaviorFn } | undefined): BehaviorFn[] =>
+      behavior ? [(cmd, next) => behavior.execute(cmd, next)] : [];
+
+    this.behaviors = [
+      (cmd, next) => this.invalidateCacheBehavior.execute(cmd, next),
+      (cmd, next) => this.logBehavior.execute(cmd, next),
+      (cmd, next) => this.performanceBehavior.execute(cmd, next),
+      ...optional(this.featureFlagBehavior),
+      (cmd, next) => this.validationBehavior.execute(cmd, next),
+      ...optional(this.workflowBehavior),
+      (cmd, next) => this.cacheBehavior.execute(cmd, next),
+      (cmd, next) => this.distributedLockBehavior.execute(cmd, next),
+      (cmd, next) => this.transactionalBehavior.execute(cmd, next),
+    ];
+
+    this.originalExecute = this.commandBus.execute.bind(this.commandBus);
+
+    const self = this;
+    this.commandBus.execute = <T>(command: object): Promise<T> => {
+      const handler = () => self.originalExecute(command) as Promise<Result<T>>;
+      return runPipeline(command, handler, self.behaviors) as Promise<T>;
+    };
+
+    this.logger.log(`Command pipeline initialized — ${this.behaviors.length} behaviors`);
+  }
+}

package/src/cqrs/pipeline/QuanticQueryBus.ts

@@ -0,0 +1,56 @@
+import { Inject, Injectable, Logger, OnModuleInit, Optional } from '@nestjs/common';
+import { QueryBus } from '@nestjs/cqrs';
+import { Result } from '../../result/Result';
+import { LogBehavior } from '../behaviors/LogBehavior';
+import { FeatureFlagBehavior } from '../behaviors/FeatureFlagBehavior';
+import { ValidationBehavior } from '../behaviors/ValidationBehavior';
+import { CacheBehavior } from '../behaviors/CacheBehavior';
+import { PerformanceBehavior } from '../behaviors/PerformanceBehavior';
+import { BehaviorFn, runPipeline } from './runPipeline';
+
+/**
+ * QuanticQueryBus — wraps the @nestjs/cqrs QueryBus with a behavior pipeline.
+ *
+ * Pipeline order:
+ *   Log → Performance → FeatureFlag → Validate → Cache → Handler
+ *
+ * Queries skip Workflow, DistributedLock, and Transactional — they are read-only.
+ */
+@Injectable()
+export class QuanticQueryBus implements OnModuleInit {
+  private readonly logger = new Logger(QuanticQueryBus.name);
+  private behaviors: BehaviorFn[] = [];
+  private originalExecute!: QueryBus['execute'];
+
+  constructor(
+    private readonly queryBus: QueryBus,
+    private readonly logBehavior: LogBehavior,
+    private readonly performanceBehavior: PerformanceBehavior,
+    @Optional() @Inject(FeatureFlagBehavior) private readonly featureFlagBehavior: FeatureFlagBehavior | undefined,
+    private readonly validationBehavior: ValidationBehavior,
+    private readonly cacheBehavior: CacheBehavior,
+  ) {}
+
+  onModuleInit() {
+    const optional = (behavior: { execute: BehaviorFn } | undefined): BehaviorFn[] =>
+      behavior ? [(cmd, next) => behavior.execute(cmd, next)] : [];
+
+    this.behaviors = [
+      (cmd, next) => this.logBehavior.execute(cmd, next),
+      (cmd, next) => this.performanceBehavior.execute(cmd, next),
+      ...optional(this.featureFlagBehavior),
+      (cmd, next) => this.validationBehavior.execute(cmd, next),
+      (cmd, next) => this.cacheBehavior.execute(cmd, next),
+    ];
+
+    this.originalExecute = this.queryBus.execute.bind(this.queryBus);
+
+    const self = this;
+    this.queryBus.execute = <T>(query: object): Promise<T> => {
+      const handler = () => self.originalExecute(query) as Promise<Result<T>>;
+      return runPipeline(query, handler, self.behaviors) as Promise<T>;
+    };
+
+    this.logger.log(`Query pipeline initialized — ${this.behaviors.length} behaviors`);
+  }
+}

package/src/cqrs/pipeline/runPipeline.ts

@@ -0,0 +1,22 @@
+import { Result } from '../../result/Result';
+
+export type BehaviorFn = <T>(
+  command: object,
+  next: () => Promise<Result<T>>,
+) => Promise<Result<T>>;
+
+export function runPipeline<T>(
+  command: object,
+  handler: () => Promise<Result<T>>,
+  behaviors: BehaviorFn[],
+): Promise<Result<T>> {
+  let next = handler;
+
+  for (let i = behaviors.length - 1; i >= 0; i--) {
+    const behavior = behaviors[i]!;
+    const currentNext = next;
+    next = () => behavior(command, currentNext);
+  }
+
+  return next();
+}

package/src/cqrs/transaction/TransactionContext.ts

@@ -0,0 +1,26 @@
+import { AsyncLocalStorage } from 'async_hooks';
+import type { QueryRunner } from 'typeorm';
+
+/**
+ * Ambient transaction context using AsyncLocalStorage.
+ *
+ * Node.js is single-threaded — each async chain (HTTP request, Bull job,
+ * event consumer) gets its own isolated storage. Two concurrent requests
+ * never share a QueryRunner.
+ *
+ * The TransactionalBehavior creates the context for the outermost command;
+ * nested commands join automatically.
+ */
+export class TransactionContext {
+  private static readonly storage = new AsyncLocalStorage<QueryRunner>();
+
+  /** Returns the active QueryRunner for this async scope, or undefined. */
+  static get(): QueryRunner | undefined {
+    return this.storage.getStore();
+  }
+
+  /** Runs `fn` with `queryRunner` as the ambient transaction for all nested calls. */
+  static run<T>(queryRunner: QueryRunner, fn: () => Promise<T>): Promise<T> {
+    return this.storage.run(queryRunner, fn);
+  }
+}

package/src/cqrs/transaction/getTransactionalRepo.ts

@@ -0,0 +1,23 @@
+import type { Repository, ObjectLiteral, EntityTarget } from 'typeorm';
+import { TransactionContext } from './TransactionContext';
+
+/**
+ * Returns a repository bound to the ambient transaction's QueryRunner,
+ * or the original repository if no transaction context exists.
+ *
+ * Usage in command handlers:
+ * ```typescript
+ * async execute(cmd: CreateUserCommand): Promise<Result<UserDto>> {
+ *   const repo = getTransactionalRepo(this.userRepo);
+ *   const user = repo.create({ email: cmd.email });
+ *   await repo.save(user);
+ *   return Result.success(toDto(user));
+ * }
+ * ```
+ */
+export function getTransactionalRepo<T extends ObjectLiteral>(
+  repo: Repository<T>,
+): Repository<T> {
+  const qr = TransactionContext.get();
+  return qr ? qr.manager.getRepository(repo.target as EntityTarget<T>) : repo;
+}

package/src/cqrs/validation/ICommandValidator.ts

@@ -0,0 +1,55 @@
+import { Result } from '../../result/Result';
+
+/**
+ * Interface for Zod-based command/query validators.
+ *
+ * Each command that needs validation gets a separate validator class
+ * with a Zod schema. The `@Validate(ValidatorClass)` decorator links
+ * the command to its validator.
+ *
+ * Usage:
+ * ```typescript
+ * export class BlockUserValidator implements ICommandValidator<BlockUserCommand> {
+ *   schema = z.object({
+ *     blockerId: z.string().uuid(),
+ *     blockedUserId: z.string().uuid(),
+ *   }).refine(d => d.blockerId !== d.blockedUserId, 'Cannot block yourself');
+ *
+ *   validate(command: BlockUserCommand): Result<void> {
+ *     return validateCommand(this.schema, command);
+ *   }
+ * }
+ * ```
+ */
+export interface ICommandValidator<T = any> {
+  validate(command: T): Result<void>;
+}
+
+/**
+ * A schema that can safeParse — matches Zod's ZodType without importing it.
+ * This avoids Zod v3/v4 compatibility issues across packages.
+ */
+interface SafeParseable {
+  safeParse(data: unknown): { success: true } | { success: false; error: { issues: Array<{ path: PropertyKey[]; message: string }> } };
+}
+
+/**
+ * Helper: run a Zod schema against a command and return Result<void>.
+ * Formats all Zod issues into a single error message.
+ */
+export function validateCommand(schema: SafeParseable, command: unknown): Result<void> {
+  const result = schema.safeParse(command);
+
+  if (result.success) {
+    return Result.success(undefined);
+  }
+
+  const messages = result.error.issues
+    .map((issue) => {
+      const path = issue.path.length > 0 ? `${issue.path.map(String).join('.')}: ` : '';
+      return `${path}${issue.message}`;
+    })
+    .join('; ');
+
+  return Result.validationError(messages);
+}