@vytches/ddd-aggregates 0.30.0 → 0.31.0-alpha.0

package/LLMGUIDE.md

@@ -46,23 +46,39 @@ order.commit(); // clear pending events after saving
 
 ## Key API
 
-| Export                                 | Kind           | Description                                                                                                                                               |
-| -------------------------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `AggregateRoot<TId>`                   | class          | Base aggregate root; manages version, events, capabilities — the _transactional_ root                                                                     |
-| `Entity<TId>`                          | abstract class | Base for **non-root** domain entities (VF-CANON-001) — identity-based equality, no version/event machinery. Use for `OrderLine`, inner aggregate entities |
-| `AggregateBuilder<TId>`                | class          | Fluent builder for constructing aggregates with capabilities                                                                                              |
-| `aggregateBuilder(params)`             | function       | Shorthand factory for `AggregateBuilder.create(params)`                                                                                                   |
-| `AggregateError`                       | class          | Domain error for aggregate-level failures                                                                                                                 |
-| `SnapshotCapability`                   | class          | Enables snapshot creation and restoration                                                                                                                 |
-| `AuditCapability`                      | class          | Attaches an audit log to every event applied                                                                                                              |
-| `VersioningCapability`                 | class          | Registers event upcasters for schema evolution                                                                                                            |
-| `EventSourcingCapability`              | class          | Integrates with `IEventStore` for persistence                                                                                                             |
-| `asSnapshotAggregate(agg)`             | function       | Casts aggregate, throws if no `SnapshotCapability`                                                                                                        |
-| `asAuditAggregate(agg)`                | function       | Casts aggregate, throws if no `AuditCapability`                                                                                                           |
-| `hasAllCapabilities(agg, [...])`       | function       | Returns `true` if aggregate has every listed capability                                                                                                   |
-| `getAggregateCapabilities(agg)`        | function       | Returns string array of capability type names                                                                                                             |
-| `AggregateWithSnapshotCapability<TId>` | type           | Type-safe alias for snapshot-capable aggregates                                                                                                           |
-| `IAggregateRoot<TId>`                  | interface      | Full contract for aggregates                                                                                                                              |
+| Export                                      | Kind           | Description                                                                                                                                                                                                   |
+| ------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `AggregateRoot<TId>`                        | class          | Base aggregate root; manages version, events, capabilities — the _transactional_ root                                                                                                                         |
+| `Entity<TId>`                               | abstract class | Base for **non-root** domain entities (VF-CANON-001) — identity-based equality, no version/event machinery. Use for `OrderLine`, inner aggregate entities                                                     |
+| `AggregateBuilder<TId>`                     | class          | Fluent builder for constructing aggregates with capabilities                                                                                                                                                  |
+| `aggregateBuilder(params)`                  | function       | Shorthand factory for `AggregateBuilder.create(params)`                                                                                                                                                       |
+| `AggregateError`                            | class          | Domain error for aggregate-level failures                                                                                                                                                                     |
+| `SnapshotCapability`                        | class          | Enables snapshot creation and restoration                                                                                                                                                                     |
+| `AuditCapability`                           | class          | Attaches an audit log to every event applied                                                                                                                                                                  |
+| `VersioningCapability`                      | class          | Registers event upcasters for schema evolution                                                                                                                                                                |
+| `EventSourcingCapability`                   | class          | Integrates with `IEventStore` for persistence                                                                                                                                                                 |
+| `asSnapshotAggregate(agg)`                  | function       | Casts aggregate, throws if no `SnapshotCapability`                                                                                                                                                            |
+| `asAuditAggregate(agg)`                     | function       | Casts aggregate, throws if no `AuditCapability`                                                                                                                                                               |
+| `asVersioningAggregate(agg)`                | function       | Casts aggregate, throws if no `VersioningCapability`                                                                                                                                                          |
+| `asEventSourcingAggregate(agg)`             | function       | Casts aggregate, throws if no `EventSourcingCapability`                                                                                                                                                       |
+| `tryAsSnapshotAggregate(agg)`               | function       | Non-throwing sibling of `asSnapshotAggregate`; returns `Result.ok(aggregate)` or `Result.fail(AggregateError)` instead of throwing                                                                            |
+| `tryAsAuditAggregate(agg)`                  | function       | Non-throwing sibling of `asAuditAggregate`; returns a `Result<AggregateWithAuditCapability<TId>, AggregateError>`                                                                                             |
+| `tryAsVersioningAggregate(agg)`             | function       | Non-throwing sibling of `asVersioningAggregate`; returns a `Result<AggregateWithVersioningCapability<TId>, AggregateError>`                                                                                   |
+| `tryAsEventSourcingAggregate(agg)`          | function       | Non-throwing sibling of `asEventSourcingAggregate`; returns a `Result<AggregateWithEventSourcingCapability<TId>, AggregateError>`                                                                             |
+| `hasAllCapabilities(agg, [...])`            | function       | Returns `true` if aggregate has every listed capability                                                                                                                                                       |
+| `getAggregateCapabilities(agg)`             | function       | Returns string array of capability type names                                                                                                                                                                 |
+| `AggregateWithSnapshotCapability<TId>`      | type           | Type-safe alias for snapshot-capable aggregates; return type of `asSnapshotAggregate`/`tryAsSnapshotAggregate`                                                                                                |
+| `AggregateWithAuditCapability<TId>`         | type           | Type-safe alias for audit-capable aggregates; return type of `asAuditAggregate`/`tryAsAuditAggregate`                                                                                                         |
+| `AggregateWithVersioningCapability<TId>`    | type           | Type-safe alias for versioning-capable aggregates; return type of `asVersioningAggregate`/`tryAsVersioningAggregate`                                                                                          |
+| `AggregateWithEventSourcingCapability<TId>` | type           | Type-safe alias for event-sourcing-capable aggregates; return type of `asEventSourcingAggregate`/`tryAsEventSourcingAggregate`                                                                                |
+| `IAggregateRoot<TId>`                       | interface      | Full contract for aggregates                                                                                                                                                                                  |
+| `IAggregateCapability`                      | interface      | Base contract every capability implements: `attach(aggregate)` (required) + `detach?()` (optional). `SnapshotCapability`, `AuditCapability`, `VersioningCapability`, `EventSourcingCapability` all satisfy it |
+| `IAggregateEventHandler<T>`                 | interface      | Callable shape `(payload: T, metadata?) => void` — the handler function type registered via `registerEventHandler(type, fn)`                                                                                  |
+
+> **BREAKING (v0.31.0):** `IAggregateBuilder<TId>` was removed — it was exported
+> but shape-incompatible with the concrete `AggregateBuilder` class. Use
+> `AggregateBuilder` directly for `withSnapshots()`, `withVersioning()`,
+> `withEventSourcing()`, `withAudit()`, `withCustomCapability()`, `build()`.
 
 ### `AggregateRoot` method reference
 
@@ -136,6 +152,57 @@ if (hasAllCapabilities(order, [AuditCapability])) {
 }
 ```
 
+### Composing multiple capabilities and narrowing with `tryAs*` helpers
+
+Build one aggregate with two capabilities (versioning + event sourcing), then
+narrow it back to each capability-specific type with the non-throwing `tryAs*`
+variants — useful in application-layer code where a missing capability should be
+handled as a `Result`, not an exception.
+
+```typescript
+import {
+  AggregateBuilder,
+  VersioningCapability,
+  EventSourcingCapability,
+  tryAsVersioningAggregate,
+  tryAsEventSourcingAggregate,
+  type AggregateWithVersioningCapability,
+  type AggregateWithEventSourcingCapability,
+} from '@vytches/ddd-aggregates';
+import { EntityId } from '@vytches/ddd-value-objects';
+
+const order = AggregateBuilder.create({ id: EntityId.create() })
+  .withVersioning()
+  .withEventSourcing()
+  .build(Order);
+
+// Narrow to versioning-capable: register an upcaster for an old event shape.
+const versioningResult = tryAsVersioningAggregate(order);
+if (versioningResult.isSuccess) {
+  const versioned: AggregateWithVersioningCapability<string> =
+    versioningResult.value;
+  versioned
+    .getCapability(VersioningCapability)!
+    .registerUpcaster('OrderCreated', 1, {
+      upcast: (payload: { amount: number }) => ({
+        ...payload,
+        currency: 'USD',
+      }),
+    });
+}
+
+// Narrow to event-sourcing-capable: persist to the configured event store.
+const eventSourcingResult = tryAsEventSourcingAggregate(order);
+if (eventSourcingResult.isSuccess) {
+  const sourced: AggregateWithEventSourcingCapability<string> =
+    eventSourcingResult.value;
+  await sourced.getCapability(EventSourcingCapability)!.saveToEventStore();
+} else {
+  // eventSourcingResult.error is an AggregateError — handle without throwing.
+  console.error(eventSourcingResult.error.message);
+}
+```
+
 ## Anti-Patterns
 
 **Mutating state directly instead of using `apply()`.** Assigning

package/README.md

@@ -181,7 +181,11 @@ class OrderLine extends Entity<string> {
 | `IAggregateCapability`             | interface | Base capability contract                   |
 | `IAggregateConstructorParams<TId>` | interface | Constructor parameter shape for aggregates |
 | `IAggregateEventHandler`           | interface | Event handler registration contract        |
-| `IAggregateBuilder`                | interface | Builder contract                           |
+
+> **BREAKING (v0.31.0):** `IAggregateBuilder` was removed. It was
+> shape-incompatible with the concrete `AggregateBuilder` class (a broken public
+> interface is worse than none). Use the `AggregateBuilder` class directly for
+> the builder's fluent contract.
 
 ### Utility Types
 

package/dist/aggregate-interfaces.d.ts

@@ -1,4 +1,4 @@
-import { Capability, CapabilityConstructor, EntityId, IAggregateSnapshot, IAuditEvent, IDomainEvent, IEventMetadata, IEventStore, IEventUpcaster } from '@vytches/ddd-contracts';
+import { Capability, CapabilityConstructor, EntityId, IAggregateSnapshot, IAuditEvent, IDomainEvent, IEventMetadata, IEventUpcaster } from '@vytches/ddd-contracts';
 /**
  * Core interface for aggregate root functionality.
  * Provides the foundation for domain aggregates with event sourcing, versioning, and capability management.
@@ -80,6 +80,21 @@ export interface IAggregateConstructorParams<TId = string> {
      * Leave undefined for "no limit" (preserves backward compatibility).
      */
     maxEvents?: number;
+    /**
+     * VF-023 (D-4, AC6, non-breaking addition): controls what happens when
+     * `apply()` (live) or `loadFromHistory()` (replay) processes an event for
+     * which no handler was registered via `registerEventHandler()`.
+     *
+     * - `"warn"` (default): the event is still recorded/replayed, but a
+     *   warning is logged via the library's internal logger. Preserves the
+     *   previous behavior's intent (missing handlers did not throw) without
+     *   silently swallowing the condition.
+     * - `"throw"`: fail fast instead — useful in tests or strict environments
+     *   where a missing handler indicates a real bug.
+     *
+     * Leave undefined for the default `"warn"` behavior (backward compatible).
+     */
+    onMissingHandler?: 'warn' | 'throw';
 }
 /**
  * Base interface for all aggregate capabilities.
@@ -174,36 +189,6 @@ export interface IMiddlewareCapability extends IAggregateCapability {
      */
     use(middleware: EventAggregateMiddleware): this;
 }
-/**
- * Builder interface for creating aggregates with capabilities.
- * Provides fluent API for configuring aggregate features before construction.
- */
-export interface IAggregateBuilder<TId> {
-    /**
-     * Adds snapshot capability
-     */
-    withSnapshots<TState = unknown, TMeta = unknown>(): this;
-    /**
-     * Adds versioning capability
-     */
-    withVersioning(): this;
-    /**
-     * Adds event sourcing capability
-     */
-    withEventSourcing(eventStore?: IEventStore): this;
-    /**
-     * Adds audit capability
-     */
-    withAudit(): this;
-    /**
-     * Adds custom capability
-     */
-    withCustomCapability<T extends IAggregateCapability>(name: string, capability: T): this;
-    /**
-     * Builds the aggregate with all configured capabilities
-     */
-    build(): IAggregateRoot<TId>;
-}
 /**
  * Handler function for processing aggregate events.
  * Used internally by aggregates to handle domain events.
@@ -243,156 +228,3 @@ export type AggregateIdType<T> = T extends IAggregateRoot<infer TId> ? TId : nev
 export type AggregateWithCapabilities<TId, TCapabilities extends CapabilityName[]> = IAggregateRoot<TId> & {
     [K in TCapabilities[number] as `getCapability`]: (name: K) => K extends 'snapshot' ? ISnapshotCapability : K extends 'versioning' ? IVersioningCapability : K extends 'eventSourcing' ? IEventSourcingCapability : K extends 'audit' ? IAuditCapability : K extends 'middleware' ? IMiddlewareCapability : IAggregateCapability;
 };
-/**
- * Factory interface for creating and rebuilding aggregates.
- * Provides standard methods for aggregate lifecycle management.
- * @template TId - The type of the aggregate ID value (string, number, etc.)
- */
-export interface IAggregateFactory<TId = string, TAggregate extends IAggregateRoot<TId> = IAggregateRoot<TId>> {
-    /**
-     * Creates a new aggregate instance
-     */
-    create(id: EntityId<TId>, ...args: unknown[]): TAggregate;
-    /**
-     * Rebuilds aggregate from events
-     */
-    fromEvents(id: EntityId<TId>, events: IDomainEvent[]): TAggregate;
-    /**
-     * Rebuilds aggregate from snapshot and subsequent events
-     */
-    fromSnapshot<TState, TMeta>(snapshot: IAggregateSnapshot<TState, TMeta>, events: IDomainEvent[]): TAggregate;
-}
-/**
- * Interface for validating aggregate state and operations.
- * Enables business rule validation at the aggregate level.
- */
-export interface IAggregateValidator<TAggregate extends IAggregateRoot<unknown>> {
-    /**
-     * Validates aggregate state
-     */
-    validate(aggregate: TAggregate): ValidationResult;
-    /**
-     * Validates aggregate before applying event
-     */
-    validateBeforeEvent(aggregate: TAggregate, event: IDomainEvent): ValidationResult;
-}
-/**
- * Result of aggregate validation operation.
- * Contains validation status and any error details.
- */
-export interface ValidationResult {
-    /** Whether the validation passed */
-    isValid: boolean;
-    /** List of validation errors if any */
-    errors: IValidationError[];
-}
-/**
- * Represents a single validation error.
- * Provides details about what failed validation and why.
- */
-export interface IValidationError {
-    /** The field or property that failed validation */
-    field: string;
-    /** Human-readable error message */
-    message: string;
-    /** Optional error code for programmatic handling */
-    code?: string;
-}
-/**
- * Capability for caching aggregate data.
- * Provides key-value storage with TTL support for performance optimization.
- */
-export interface ICachingCapability extends IAggregateCapability {
-    /**
-     * Gets cached value
-     */
-    get<T>(key: string): T | undefined;
-    /**
-     * Sets cached value
-     */
-    set<T>(key: string, value: T, ttl?: number): void;
-    /**
-     * Clears all cached values
-     */
-    clear(): void;
-    /**
-     * Invalidates specific cached value
-     */
-    invalidate(key: string): void;
-}
-/**
- * Capability for collecting aggregate metrics.
- * Enables monitoring and observability of aggregate operations.
- */
-export interface IMetricsCapability extends IAggregateCapability {
-    /**
-     * Records a metric
-     */
-    record(name: string, value: number, tags?: Record<string, string>): void;
-    /**
-     * Increments a counter
-     */
-    increment(name: string, tags?: Record<string, string>): void;
-    /**
-     * Records timing information
-     */
-    timing(name: string, duration: number, tags?: Record<string, string>): void;
-    /**
-     * Gets recorded metrics
-     */
-    getMetrics(): MetricData[];
-}
-/**
- * Represents a single metric data point.
- * Contains metric information with optional tags and timestamp.
- */
-export interface MetricData {
-    /** Metric name */
-    name: string;
-    /** Metric value */
-    value: number;
-    /** Type of metric */
-    type: 'counter' | 'gauge' | 'timing';
-    /** Optional tags for metric categorization */
-    tags?: Record<string, string>;
-    /** When the metric was recorded */
-    timestamp: Date;
-}
-/**
- * Capability for security features like encryption and authorization.
- * Provides security controls for sensitive aggregate operations.
- */
-export interface ISecurityCapability extends IAggregateCapability {
-    /**
-     * Encrypts sensitive data
-     */
-    encrypt(data: unknown): string;
-    /**
-     * Decrypts sensitive data
-     */
-    decrypt(encryptedData: string): unknown;
-    /**
-     * Checks if user has permission to perform action
-     */
-    hasPermission(action: string, user?: unknown): boolean;
-    /**
-     * Logs security events
-     */
-    logSecurityEvent(event: SecurityEvent): void;
-}
-/**
- * Represents a security-related event.
- * Used for audit trails and security monitoring.
- */
-export interface SecurityEvent {
-    /** Type of security event */
-    type: 'access' | 'modification' | 'failure';
-    /** Action that was performed */
-    action: string;
-    /** User who performed the action */
-    user?: unknown;
-    /** When the event occurred */
-    timestamp: Date;
-    /** Additional event metadata */
-    metadata?: Record<string, unknown>;
-}

package/dist/capabilities/audit-capability.d.ts

@@ -1,4 +1,4 @@
-import { Capability, IAuditCapability, IAuditEvent, IDomainEvent } from '../../../contracts/src/index.ts';
+import { Capability, IAuditCapability, IAuditEvent, IDomainEvent } from '@vytches/ddd-contracts';
 /**
  * Capability that records every domain event applied to the aggregate as
  * an `IAuditEvent`. Useful for compliance, debugging, behavior analytics,

package/dist/capabilities/event-sourcing-capability.d.ts

@@ -1,4 +1,4 @@
-import { IEventSourcingCapability, IEventStore, Capability } from '../../../contracts/src/index.ts';
+import { IEventSourcingCapability, IEventStore, Capability } from '@vytches/ddd-contracts';
 /**
  * Capability that integrates an aggregate with an external `IEventStore` —
  * the persistence boundary for an event-sourced system. Allows the

package/dist/capabilities/snapshot-capability.d.ts

@@ -1,4 +1,4 @@
-import { IAggregateSnapshot, ISnapshotCapability, Capability } from '../../../contracts/src/index.ts';
+import { IAggregateSnapshot, ISnapshotCapability, Capability } from '@vytches/ddd-contracts';
 /**
  * Capability that enables snapshot creation and restoration on an aggregate
  * — a performance optimization for event-sourced aggregates with long

package/dist/capabilities/versioning-capability.d.ts

@@ -1,4 +1,4 @@
-import { Capability, IVersioningCapability, IDomainEvent, IEventUpcaster } from '../../../contracts/src/index.ts';
+import { Capability, IVersioningCapability, IDomainEvent, IEventUpcaster } from '@vytches/ddd-contracts';
 import { IAggregateEventHandler } from '../aggregate-interfaces';
 /**
  * Capability that handles **event schema evolution** — when a stored event
@@ -63,7 +63,20 @@ export declare class VersioningCapability extends Capability<'versioning'> imple
      */
     registerUpcaster<TFrom = unknown, TTo = unknown>(eventType: string, sourceVersion: number, upcaster: IEventUpcaster<TFrom, TTo>): void;
     /**
-     * @param {IDomainEvent} event - Event to process with version handling
+     * Applies registered upcasters to bring `event` from its stored version up
+     * to the aggregate's current version, then invokes the matching handler.
+     *
+     * **Upcasting only activates if `event.metadata.targetVersion` is set.**
+     * This is NOT inferred automatically from registered upcasters or from
+     * any aggregate-level "current version" — the caller (typically your
+     * event-sourcing replay/load path) must explicitly stamp each historical
+     * event's metadata with `targetVersion` before calling this method. If
+     * `targetVersion` is absent, `currentVersion` falls back to `eventVersion`
+     * (i.e. no upcasting happens — the event is passed through unchanged even
+     * if upcasters are registered for it).
+     *
+     * @param {IDomainEvent} event - Event to process with version handling;
+     *   set `event.metadata.targetVersion` to enable upcasting
      * @param {Map<string, IAggregateEventHandler>} handlers - Map of event handlers
      */
     handleVersionedEvent(event: IDomainEvent, handlers: Map<string, IAggregateEventHandler>): void;

package/dist/core/aggregate-root.builder.d.ts

@@ -1,4 +1,4 @@
-import { Capability, IEventStore, EntityId } from '../../../contracts/src/index.ts';
+import { Capability, IEventStore, EntityId } from '@vytches/ddd-contracts';
 import { IAggregateCapability, IAggregateConstructorParams } from '../aggregate-interfaces';
 import { AggregateRoot } from './aggregate-root';
 /**

package/dist/core/aggregate-root.d.ts

@@ -1,5 +1,22 @@
 import { IAggregateCapability, IAggregateConstructorParams, IAggregateEventHandler, IAggregateRoot } from '../aggregate-interfaces';
-import { Capability, CapabilityConstructor, EntityId, IDomainEvent, IEventMetadata } from '../../../contracts/src/index.ts';
+import { Capability, CapabilityConstructor, EntityId, IDomainEvent, IEventMetadata } from '@vytches/ddd-contracts';
+/**
+ * VF-023 (D-2, AC5, BREAKING, CRITICAL F-H4): module-private gating token
+ * for {@link AggregateRoot._internal_setState}. This is exported from this
+ * module (`./core/aggregate-root`) — NOT from the package's public barrel
+ * (`index.ts`) — so it is reachable only via a deep import within this
+ * package's own source (e.g. `SnapshotCapability`), never via
+ * `@vytches/ddd-aggregates`. Consumers cannot obtain this token, and
+ * therefore cannot call `_internal_setState` at all: TypeScript rejects the
+ * call without it, and even a `as any` cast would need the exact symbol
+ * reference, which is not exported publicly.
+ *
+ * Previously `_internal_setState` was a plain public method reachable via
+ * any `as any`/duck-typed cast — no compile-time or run-time barrier
+ * prevented domain code from bypassing `apply()`/`loadFromHistory()` and
+ * corrupting the version/event-log invariant directly.
+ */
+export declare const INTERNAL_STATE_TOKEN: unique symbol;
 /**
  * Base class for aggregate roots — the *transactional consistency boundary*
  * of a Domain-Driven Design model. Per Eric Evans (Blue Book, ch. 6):
@@ -12,7 +29,7 @@ import { Capability, CapabilityConstructor, EntityId, IDomainEvent, IEventMetada
  *
  * `AggregateRoot<TId>` provides:
  *
- * - **Identity** via `EntityId<TId>` (`getId()`)
+ * - **Identity** via `EntityId<TId>` (`getId()`, `equals()`)
  * - **Versioning** for optimistic locking (`getVersion()`,
  *   `getInitialVersion()`)
  * - **Event emission** via `apply()` — append a `DomainEvent`, increment
@@ -111,28 +128,69 @@ export declare class AggregateRoot<TId = string> implements IAggregateRoot<TId>
      * loops or malicious replay payloads.
      */
     private readonly _maxEvents;
+    /**
+     * VF-023 (D-4, AC6, non-breaking addition): controls what happens when
+     * `apply()` or `loadFromHistory()` processes an event for which no
+     * handler was registered via `registerEventHandler()`. Defaults to
+     * `"warn"` (preserves the previous silent-but-logged-nowhere behavior's
+     * intent without a breaking default) — the event is still recorded /
+     * replayed, but a warning is logged via the library's internal logger.
+     * Set to `"throw"` to fail fast instead, useful in tests or strict
+     * environments where a missing handler indicates a real bug.
+     */
+    private readonly _onMissingHandler;
     constructor(params: IAggregateConstructorParams<TId>);
     /**
      * Get the unique identifier of this aggregate
      */
     getId(): EntityId<TId>;
     /**
+     * Identity-based equality, matching {@link Entity.equals}. Two aggregates
+     * are equal iff they have the same id (compared via `EntityId.equals()`);
+     * attribute/version differences are ignored.
+     *
+     * VF-023 (D-5, AC10, non-breaking addition): `AggregateRoot` does not
+     * extend `Entity` (it implements `IAggregateRoot<TId>` directly), so this
+     * mirrors `Entity.equals()` rather than inheriting it.
+     *
+     * @param other - Aggregate to compare against. May be `null` or `undefined`.
+     * @returns `true` if both aggregates have the same id; `false` otherwise.
+     */
+    equals(other: AggregateRoot<TId> | null | undefined): boolean;
+    /**
+     * The version increments by one each time `apply()` successfully records a
+     * domain event; compare it against the persisted version to detect
+     * concurrent modification (optimistic locking).
      *
      * @returns {number} Current version number for optimistic locking
      */
     getVersion(): number;
     /**
+     * The version this aggregate had when it was loaded (or as of the last
+     * `commit()`), letting callers work out how many events have been applied
+     * since without recomputing from the event log.
      *
      * @returns {number} Initial version when aggregate was loaded
      */
     getInitialVersion(): number;
     /**
+     * Whether this aggregate has recorded domain events since its last
+     * `commit()` — use it to decide whether persistence/dispatch work is
+     * needed at all.
      *
      * @returns {boolean} True if aggregate has uncommitted domain events
      */
     hasChanges(): boolean;
     /**
-     *
+     * VF-023 (D-3, AC11, BREAKING): the returned array and every event object
+     * it contains (including nested `payload`/`metadata`) are now deep-frozen
+     * via `LibUtils.deepFreeze` — the same immutability guarantee applied to
+     * `BaseValueObject` values (see `base-value-object.ts`). Previously this
+     * returned only a shallow array copy: the array itself couldn't be
+     * mutated by callers, but the event objects (and their nested payload
+     * data) inside it could still be mutated in place, silently corrupting
+     * state shared with `_domainEvents` (the same object references are
+     * stored internally — events are never re-cloned after creation).
      * @returns {ReadonlyArray<IDomainEvent>} Array of uncommitted domain events
      */
     getDomainEvents(): ReadonlyArray<IDomainEvent>;
@@ -151,9 +209,28 @@ export declare class AggregateRoot<TId = string> implements IAggregateRoot<TId>
      * @param {string | IDomainEvent<P>} eventTypeOrEvent - Event type string or complete event object
      * @param {P} payload - Event payload data
      * @param {Partial<IEventMetadata>} metadata - Optional event metadata
+     * @throws {Error} when the aggregate's configured maxEvents limit would be exceeded
+     * @example Hitting the maxEvents guard
+     * ```typescript
+     * class Order extends AggregateRoot<string> {
+     *   record(customerId: string, amount: number): void {
+     *     this.apply('OrderCreated', { customerId, amount });
+     *   }
+     * }
+     *
+     * const order = new Order({ id: EntityId.create(), version: 0, maxEvents: 1 });
+     * order.record('c-1', 100); // ok, 1 event recorded
+     * order.record('c-1', 100); // throws: maxEvents limit of 1 exceeded
+     * ```
      */
     protected apply<P = unknown>(eventTypeOrEvent: string | IDomainEvent<P>, payload?: P, metadata?: Partial<IEventMetadata>): void;
     private handleEvent;
+    /**
+     * VF-023 (D-4, AC6): called from `handleEvent()`, which is shared by both
+     * `apply()` (live) and `loadFromHistory()` (replay) — so the missing-
+     * handler policy applies identically to both paths.
+     */
+    private reportMissingHandler;
     /**
      * Reconstruct aggregate state from historical domain events
      * @param {IDomainEvent[]} events - Array of events to replay for state reconstruction
@@ -190,10 +267,20 @@ export declare class AggregateRoot<TId = string> implements IAggregateRoot<TId>
     getCapabilityTypes(): string[];
     private static sanitizeMetadata;
     /**
-     * Internal method for capabilities to access private state
-     * Should only be used by capabilities, not directly by domain code
+     * Internal method for capabilities to access private state.
+     *
+     * VF-023 (D-2, AC5, BREAKING, CRITICAL F-H4): gated by
+     * {@link INTERNAL_STATE_TOKEN}, a module-private `unique symbol` that is
+     * exported only from this module (not from the package's public barrel).
+     * Callers must supply the exact token reference to invoke this method —
+     * consumers of `@vytches/ddd-aggregates` cannot obtain it, so this method
+     * is unreachable from outside this package's own source, even via
+     * `as unknown as {...}` casts (the token value itself, not just its type,
+     * is required and cannot be forged).
+     *
+     * @throws {TypeError} if `token` does not match {@link INTERNAL_STATE_TOKEN}
      */
-    _internal_setState(state: {
+    _internal_setState(token: typeof INTERNAL_STATE_TOKEN, state: {
         version: number;
         initialVersion: number;
         domainEvents: IDomainEvent[];

package/dist/core/aggregate-utilities.d.ts

@@ -1,5 +1,5 @@
-import { Result } from '../../../utils/src/index.ts';
-import { CapabilityConstructor, Capability, IAggregateCapability, IAggregateSnapshot } from '../../../contracts/src/index.ts';
+import { Result } from '@vytches/ddd-utils';
+import { CapabilityConstructor, Capability, IAggregateCapability, IAggregateSnapshot } from '@vytches/ddd-contracts';
 import { AggregateError } from '../aggregate-errors';
 import { SnapshotCapability } from '../capabilities/snapshot-capability';
 import { VersioningCapability } from '../capabilities/versioning-capability';

package/dist/core/entity.d.ts

@@ -1,4 +1,4 @@
-import { EntityId } from '../../../contracts/src/index.ts';
+import { EntityId } from '@vytches/ddd-contracts';
 /**
  * Base class for domain entities — objects with identity that may be
  * referenced from other aggregates but are NOT themselves aggregate roots.