@shirudo/ddd-kit 3.0.0-rc.8 → 3.0.0-rc.9

package/dist/index.d.ts

@@ -1422,6 +1422,11 @@ interface PersistenceModel<TAggregate, TBaseline, TChangeSet> {
    * `Set` members and `Map` keys by reference (JS `SameValueZero`
    * semantics): a capture that re-materializes object Set members or Map
    * keys on every call must supply {@link captureEquals}.
+   *
+   * A column that the store owns stays out of the capture, for example an
+   * `updatedAt` that the adapter stamps; `flush` writes it. A captured store
+   * column pushes a stale value back on the next write, or it marks every
+   * row as changed.
    */
   capture(aggregate: TAggregate): TBaseline;
   /**
@@ -1505,8 +1510,10 @@ type UnitOfWorkIdentityMap = Pick<IdentityMap, "get" | "has" | "isDeleted">;
  *   `tracking.trackLoaded(aggregate)` after hydration. This captures the
  *   expected version before application code can mutate the instance.
  * - Adapter objects do not need lifecycle methods; the facade installs the
- *   Unit-of-Work-owned `add`, `update`, and optional `remove`. If a concrete
- *   adapter has same-named methods anyway, the facade masks them.
+ *   Unit-of-Work-owned `add`, `update` unless the definition is append-only,
+ *   and `remove` with `physicalRemoval`. If a concrete adapter has a method
+ *   named `add`, `update`, or `remove` anyway, the facade masks it, installed
+ *   or not.
  * - Other repository methods are reads. A custom method that performs a write
  *   would bypass the Unit of Work and violates the adapter contract.
  */
@@ -1629,7 +1636,9 @@ declare class AggregateTrackingError extends KitWiringError<"AGGREGATE_TRACKING"
   readonly operation: AggregateWriteIntent | "load" | "commit";
   readonly reason: AggregateTrackingFailure;
   readonly registeredIntent?: AggregateWriteIntent | undefined;
-  constructor(aggregateId: string, operation: AggregateWriteIntent | "load" | "commit", reason: AggregateTrackingFailure, registeredIntent?: AggregateWriteIntent | undefined);
+  constructor(aggregateId: string, operation: AggregateWriteIntent | "load" | "commit", reason: AggregateTrackingFailure, registeredIntent?: AggregateWriteIntent | undefined, options?: {
+    readonly appendOnly?: boolean;
+  });
 }
 /**
  * The unit of work failed AFTER the work callback completed
@@ -1736,7 +1745,7 @@ interface RunOptions {
 }
 declare const repositoryDefinitionBrand: unique symbol;
 /** Adapter wiring accepted by {@link defineRepository}. */
-interface RepositoryDefinitionOptions<TCtx, TRepositoryPort extends object, TAggregate extends Aggregate<Id<string>, AnyDomainEvent>, TBaseline, TChangeSet, TRemoval extends boolean = false> {
+interface RepositoryDefinitionOptions<TCtx, TRepositoryPort extends object, TAggregate extends Aggregate<Id<string>, AnyDomainEvent>, TBaseline, TChangeSet, TRemoval extends boolean = false, TAppendOnly extends boolean = false> {
   /**
    * Concrete aggregate class used as the Identity Map key, and for nothing
    * else. The read adapter passes the same class to `identityMap.get`, so
@@ -1748,7 +1757,8 @@ interface RepositoryDefinitionOptions<TCtx, TRepositoryPort extends object, TAgg
   readonly persistence: PersistenceModel<TAggregate, TBaseline, TChangeSet>;
   /**
    * Creates the transaction-bound adapter for the port's non-lifecycle
-   * methods. The Unit of Work supplies `add`, `update`, and optional `remove`.
+   * methods. The Unit of Work supplies `add`, `update` unless the definition
+   * is append-only, and `remove` with `physicalRemoval`.
    */
   readonly create: (transaction: TCtx, tracking: RepositoryTracking<TAggregate>) => Omit<TRepositoryPort, "add" | "update" | "remove">;
   /**
@@ -1767,19 +1777,83 @@ interface RepositoryDefinitionOptions<TCtx, TRepositoryPort extends object, TAgg
   readonly mapError: (error: unknown, write: AggregatePersistenceWrite<TAggregate, TChangeSet>) => InfrastructureError;
   /** Adds Unit-of-Work-owned `remove` to the application-facing repository. */
   readonly physicalRemoval?: TRemoval;
+  /**
+   * Leaves `update` out of the application-facing repository. An append-only
+   * aggregate is a fact that the domain never changes after `add`, for
+   * example a ledger entry or an audit record. The port then declares no
+   * `update`, and the Unit of Work installs none.
+   */
+  readonly appendOnly?: TAppendOnly;
 }
 /** Complete, helper-created definition for one Unit-of-Work repository. */
-interface RepositoryDefinition<TCtx, TRepositoryPort extends object, TAggregate extends Aggregate<Id<string>, AnyDomainEvent>, TBaseline, TChangeSet, TRemoval extends boolean = false> extends RepositoryDefinitionOptions<TCtx, TRepositoryPort, TAggregate, TBaseline, TChangeSet, TRemoval> {
+interface RepositoryDefinition<TCtx, TRepositoryPort extends object, TAggregate extends Aggregate<Id<string>, AnyDomainEvent>, TBaseline, TChangeSet, TRemoval extends boolean = false, TAppendOnly extends boolean = false> extends RepositoryDefinitionOptions<TCtx, TRepositoryPort, TAggregate, TBaseline, TChangeSet, TRemoval, TAppendOnly> {
   /** Nominal marker installed by {@link defineRepository}. */
   readonly [repositoryDefinitionBrand]: true;
 }
 /** @inline */
 type CallableValue = (...args: never[]) => unknown;
+/**
+ * The compile-time report for a port that violates one constraint of
+ * {@link defineRepository}. No definition can carry a property of type
+ * `never`, so the compiler rejects the call. Its message names the violated
+ * constraint instead of the bare "parameter of type never".
+ * @inline
+ */
+type RepositoryPortViolation<TConstraint extends string> = { readonly [constraint in `defineRepository: ${TConstraint}`]: never; };
+/**
+ * Continues with the next constraint when the checked one passed, and
+ * otherwise reports the violation of the checked one.
+ * @inline
+ */
+type Then<TChecked, TNext> = unknown extends TChecked ? TNext : TChecked;
+/** @inline */
+type IsUnion<T, TEach = T> = T extends unknown ? [TEach] extends [T] ? false : true : never;
+/** @inline */
+type PortShapeConstraint<TRepositoryPort> = [Extract<TRepositoryPort, CallableValue>] extends [never] ? true extends IsUnion<TRepositoryPort> ? RepositoryPortViolation<"the port must be one object type, not a union"> : unknown : RepositoryPortViolation<"the port must be an object type, not a function">;
+/**
+ * Checks a lifecycle member that the port declares: it is required, and it
+ * accepts the definition's aggregate. An optional member is the trap of a
+ * port that extends a type with `update?` or `remove?`, so it gets its own
+ * message.
+ * @inline
+ */
+type MemberAcceptsAggregate<TRepositoryPort, TMember extends "add" | "update" | "remove", TAggregate extends Aggregate<Id<string>, AnyDomainEvent>> = undefined extends TRepositoryPort[TMember & keyof TRepositoryPort] ? RepositoryPortViolation<`the port's ${TMember} must not be optional`> : [TRepositoryPort] extends [Pick<AggregateWriteRegistration<TAggregate> & PhysicalRemovalRegistration<TAggregate>, TMember>] ? unknown : RepositoryPortViolation<`the port's ${TMember} must accept the definition's aggregate`>;
+/** @inline */
+type AddConstraint<TRepositoryPort, TAggregate extends Aggregate<Id<string>, AnyDomainEvent>> = "add" extends keyof TRepositoryPort ? MemberAcceptsAggregate<TRepositoryPort, "add", TAggregate> : RepositoryPortViolation<"the port must declare add(aggregate): void">;
+/** @inline */
+type UpdateConstraint<TRepositoryPort, TAggregate extends Aggregate<Id<string>, AnyDomainEvent>, TAppendOnly extends boolean> = "update" extends keyof TRepositoryPort ? boolean extends TAppendOnly ? RepositoryPortViolation<"the port declares update, so the definition must not set appendOnly"> : [TAppendOnly] extends [true] ? RepositoryPortViolation<"appendOnly is true, so the port must not declare update"> : MemberAcceptsAggregate<TRepositoryPort, "update", TAggregate> : [TAppendOnly] extends [true] ? unknown : RepositoryPortViolation<"the port declares no update, so the definition must set appendOnly: true">;
+/** @inline */
+type RemovalConstraint<TRepositoryPort, TAggregate extends Aggregate<Id<string>, AnyDomainEvent>, TRemoval extends boolean> = "remove" extends keyof TRepositoryPort ? [TRemoval] extends [true] ? MemberAcceptsAggregate<TRepositoryPort, "remove", TAggregate> : RepositoryPortViolation<"the port declares remove, so the definition must set physicalRemoval: true"> : [TRemoval] extends [true] ? RepositoryPortViolation<"physicalRemoval is true, so the port must declare remove(aggregate): void"> : unknown;
+/**
+ * Checks the port against every constraint of {@link defineRepository}, one
+ * at a time, so the report names the first violated constraint. Resolves to
+ * `unknown` when the port satisfies all of them. A port typed `any` opts out
+ * of the check, as it does everywhere else. Under the `object` bound of the
+ * builder only `any` satisfies `unknown extends TRepositoryPort`; the usual
+ * `0 extends 1 & T` probe misses an `any` that passed through that bound.
+ * @inline
+ */
+type RepositoryPortConstraint<TRepositoryPort, TAggregate extends Aggregate<Id<string>, AnyDomainEvent>, TRemoval extends boolean, TAppendOnly extends boolean> = unknown extends TRepositoryPort ? unknown : Then<PortShapeConstraint<TRepositoryPort>, Then<AddConstraint<TRepositoryPort, TAggregate>, Then<UpdateConstraint<TRepositoryPort, TAggregate, TAppendOnly>, RemovalConstraint<TRepositoryPort, TAggregate, TRemoval>>>>;
 /** @inline */
-type RepositoryDefinitionBuilder<TRepositoryPort extends object> = <TAggregate extends Aggregate<Id<string>, AnyDomainEvent>, TCreate extends (transaction: never, tracking: RepositoryTracking<TAggregate>) => Omit<TRepositoryPort, "add" | "update" | "remove">, TBaseline, TChangeSet, TRemoval extends boolean = false>(definition: RepositoryDefinitionOptions<Parameters<TCreate>[0], TRepositoryPort, TAggregate, TBaseline, TChangeSet, TRemoval> & {
+type RepositoryDefinitionBuilder<TRepositoryPort extends object> = <TAggregate extends Aggregate<Id<string>, AnyDomainEvent>, TCreate extends (transaction: never, tracking: RepositoryTracking<TAggregate>) => Omit<TRepositoryPort, "add" | "update" | "remove">, TBaseline, TChangeSet, TRemoval extends boolean = false, TAppendOnly extends boolean = false>(definition: RepositoryDefinitionOptions<Parameters<TCreate>[0], TRepositoryPort, TAggregate, TBaseline, TChangeSet, TRemoval, TAppendOnly> & {
   readonly create: TCreate;
-} & (TRepositoryPort extends AggregateWriteRegistration<TAggregate> ? TRemoval extends true ? TRepositoryPort extends PhysicalRemovalRegistration<TAggregate> ? unknown : never : TRepositoryPort extends PhysicalRemovalRegistration<TAggregate> ? never : unknown : never)) => RepositoryDefinition<Parameters<TCreate>[0], TRepositoryPort, TAggregate, TBaseline, TChangeSet, TRemoval>;
-declare function defineRepository<TRepositoryPort extends object>(): Extract<TRepositoryPort, CallableValue> extends never ? RepositoryDefinitionBuilder<TRepositoryPort> : never;
+} & RepositoryPortConstraint<TRepositoryPort, TAggregate, TRemoval, TAppendOnly>) => RepositoryDefinition<Parameters<TCreate>[0], TRepositoryPort, TAggregate, TBaseline, TChangeSet, TRemoval, TAppendOnly>;
+/**
+ * Defines repository wiring for an application-owned driven port.
+ *
+ * The first call makes the port explicit; the second infers the transaction,
+ * aggregate, persistence, event, and lifecycle types from the adapter wiring.
+ * The port must declare `add` for the aggregate. It declares `update` unless
+ * the definition sets `appendOnly: true`. If it declares `remove`, the
+ * definition must set `physicalRemoval: true`. A violated constraint fails
+ * the call with a compiler error that names the constraint. The adapter
+ * created by the definition implements only the remaining methods because
+ * lifecycle writes are installed by the Unit of Work.
+ * The returned definition is the only form accepted by {@link UnitOfWork}; a
+ * raw adapter-shaped object cannot silently turn its concrete surface into the
+ * application contract.
+ */
+declare function defineRepository<TRepositoryPort extends object>(): RepositoryDefinitionBuilder<TRepositoryPort>;
 /** Application-facing repositories inferred from their adapter definitions. */
 type RepositoriesOf<TDefinitions> = { [K in keyof TDefinitions]: RepositoryFacadeOf<TDefinitions[K]>; };
 /**
@@ -1787,12 +1861,15 @@ type RepositoriesOf<TDefinitions> = { [K in keyof TDefinitions]: RepositoryFacad
  * entries, callable adapter results, and definitions whose transaction context
  * or aggregate event family does not belong to the Unit of Work that owns them.
  */
-type CompatibleRepositoryDefinitions<Evt extends AnyDomainEvent, TCtx, TDefinitions> = { [K in keyof TDefinitions]: TDefinitions[K] extends RepositoryDefinition<infer TDefinitionContext, infer _TRepositoryPort, infer TAggregate, infer _TBaseline, infer _TChangeSet, infer _TRemoval> ? TAggregate extends Aggregate<Id<string>, infer TDefinitionEvent> ? [TDefinitionEvent] extends [Evt] ? TCtx extends TDefinitionContext ? TDefinitions[K] : never : never : never : never; };
+type CompatibleRepositoryDefinitions<Evt extends AnyDomainEvent, TCtx, TDefinitions> = { [K in keyof TDefinitions]: TDefinitions[K] extends RepositoryDefinition<infer TDefinitionContext, infer _TRepositoryPort, infer TAggregate, infer _TBaseline, infer _TChangeSet, infer _TRemoval, infer _TAppendOnly> ? TAggregate extends Aggregate<Id<string>, infer TDefinitionEvent> ? [TDefinitionEvent] extends [Evt] ? TCtx extends TDefinitionContext ? TDefinitions[K] : never : never : never : never; };
 /** @inline */
-type RepositoryFacadeOf<TDefinition> = TDefinition extends RepositoryDefinition<infer _TCtx, infer TRepositoryPort, infer _TAggregate, infer _TBaseline, infer _TChangeSet, infer _TRemoval> ? TRepositoryPort : never;
-/** Unit-of-Work-owned writes added to every application repository facade. */
-interface AggregateWriteRegistration<TAggregate extends Aggregate<Id<string>, AnyDomainEvent>> {
+type RepositoryFacadeOf<TDefinition> = TDefinition extends RepositoryDefinition<infer _TCtx, infer TRepositoryPort, infer _TAggregate, infer _TBaseline, infer _TChangeSet, infer _TRemoval, infer _TAppendOnly> ? TRepositoryPort : never;
+/** The one Unit-of-Work-owned write of an append-only repository facade. */
+interface AppendOnlyWriteRegistration<TAggregate extends Aggregate<Id<string>, AnyDomainEvent>> {
   add(aggregate: TAggregate): void;
+}
+/** Unit-of-Work-owned writes of a repository facade that is not append-only. */
+interface AggregateWriteRegistration<TAggregate extends Aggregate<Id<string>, AnyDomainEvent>> extends AppendOnlyWriteRegistration<TAggregate> {
   update(aggregate: TAggregate): void;
 }
 /** Optional physical removal added only by an explicit repository definition. */
@@ -4274,5 +4351,5 @@ declare function captureAggregateSnapshot<TAggregate extends SnapshotAggregate,
  */
 declare function reconstituteAggregateFromSnapshot<TAggregate extends SnapshotAggregate, TSnapshotState>(model: SnapshotModel<TAggregate, TSnapshotState>, id: TAggregate["id"], snapshot: AggregateSnapshot<unknown>): TAggregate;
 //#endregion
-export { type Aggregate, type AggregateAddress, type AggregateAddressMismatchOptions, type AggregateClass, type AggregateCommitToken, type AggregateConfig, AggregateDeletedError, AggregateNotFoundError, type AggregateNotFoundErrorOptions, type AggregatePersistence, type AggregatePersistenceWrite, type AggregateSnapshot, AggregateTrackingError, type AggregateTrackingFailure, type AggregateWriteIntent, type AggregateWriteRegistration, type AnyDomainEvent, type AnyUncommittedDomainEvent, CapabilityRegistryConflictError, type ClockFactory, type Command, CommandBus, type CommandBusOptions, type CommandCommitOriginCandidate, type CommandHandler, type CommandMessageContent, type CommandMessageRelationships, type CommandOutboxCommitCandidate, type CommandOutboxMapper, type CommandOutboxWriter, type CommitEnrollment, type CommitEnrollmentOptions, CommitError, type CommitPosition, type CommittedDomainEvent, type CompatibleRepositoryDefinitions, ConcurrencyConflictError, type ConcurrencyConflictErrorOptions, type CreateDomainEventFromFactsOptions, type CreateDomainEventOptions, type CreateDomainEventStampOptions, type CreateUncommittedDomainEventOptions, type DeadLetterDeadline, type DeadLetterRecord, DeadlineProcessor, type DeadlineProcessorObservers, type DeadlineProcessorOptions, type DeadlineStore, type DeepEqualExceptOptions, type DeepOmitKey, type DeepOmitOptions, type DeepOmitPathSegment, type DeliveryFailureAssessment, type DeliveryFailureClassifier, type DeliveryFailureKind, DirectStateMutationError, type DispatchTrackingOutbox, DomainError, type DomainErrorClass, type DomainEvent, type DomainEventFactory, type DomainEventFactoryOptions, type DomainEventStamp, type DomainEventStampFactory, type DomainEventStampProvider, type DomainEventValidationCode, DomainEventValidationError, type DomainEventValidationField, type DomainMachineDefinition, type DomainMachineDefinitionAnalysis, type DomainMachineDefinitionDiagnostic, type DomainMachineInput, type DomainMachineReadonly, type DomainMachineSnapshot, type DomainMachineTransitionDescription, DomainStateMachine, type DomainStateNode, type DomainTransition, DomainTransitionGuardRejectedError, type DomainTransitionGuardResult, type DomainTransitionOutcome, type DomainTransitionResult, type DueDeadline, DuplicateAggregateError, type DuplicateAggregateErrorOptions, DuplicateEventIdError, DuplicateHandlerRegistrationError, type DuplicateHandlerRegistrationErrorOptions, type DurableCommandMessage, Entity, type EntityConfig, ErrorMapperFailedError, type ErrorMapperFailedErrorOptions, type EventBus, EventBusClosedError, EventBusImpl, type EventBusObservers, type EventBusOptions, type EventCommitCandidate, type EventCommitCandidatePosition, type EventHandler, EventHarvestError, type EventIdFactory, type EventMetadata, EventSourcedAggregate, type EventStore, type EventStoreAppendOptions, type ExecutionContext, FoldReturnedNoStateError, ForeignEventError, type HandlerFailureReport, HostileStateKeyError, type ICommandBus, type IEntity, type IQueryBus, type IValueObject, type Id, type IdGenerator, type IdempotencyClaim, type IdempotencyClaimHandle, IdempotencyClaimLostError, type IdempotencyClaimLostErrorOptions, IdempotencyCompletionWithoutClaimError, IdempotencyInFlightError, type IdempotencyInFlightErrorOptions, IdempotencyKeyReuseError, type IdempotencyKeyReuseErrorOptions, type IdempotencyLease, type IdempotencyOperationErrorContext, type IdempotencyReconciliation, type IdempotencyReconciliationDecision, IdempotencyReconciliationRequiredError, type IdempotencyReconciliationRequiredErrorOptions, type IdempotencyStore, type IdempotentCommitRequest, type IdempotentCommitResult, type IdempotentExecution, type Identifiable, IdentityMap, InMemoryCapacityExceededError, type InMemoryCapacityExceededErrorOptions, InMemoryDeadlineStore, type InMemoryDeadlineStoreOptions, InMemoryEventStore, type InMemoryEventStoreOptions, InMemoryIdempotencyStore, type InMemoryIdempotencyStoreOptions, InMemoryOutbox, type InMemoryOutboxOptions, InMemoryProjectionCheckpointStore, type InMemoryProjectionCheckpointStoreOptions, InMemorySnapshotStore, type InMemorySnapshotStoreOptions, InfrastructureError, type IntegrationMessage, type IntegrationMessageContent, type IntegrationMessageMapper, type IntegrationMessageRelationships, InvalidCommandMessageError, InvalidDomainMachineContextError, InvalidDomainMachineDefinitionError, InvalidDomainMachineInputError, InvalidDomainMachineSnapshotError, InvalidDomainTransitionError, InvalidDomainTransitionGuardResultError, InvalidDomainTransitionResultError, InvalidIntegrationMessageError, InvalidRepositoryAdapterError, InvalidRepositoryDefinitionError, InvalidVersionError, type JsonObject, type JsonPrimitive, type JsonValue, type KitErrorCode, type KitErrorOptions, MisaddressedEventError, MissingEntityIdError, MissingFoldError, MissingHandlerError, NestedUnitOfWorkError, NonProgressingEventStreamPageError, type NonProgressingEventStreamPageErrorOptions, type OnceOptions, type Outbox, OutboxDispatcher, type OutboxDispatcherObservers, type OutboxDispatcherOptions, type OutboxRecord, type OutboxSink, type OutboxWriter, type PendingDomainEvent, PendingEventBatchMismatchError, PendingEventLimitExceededError, type PendingEventLimitExceededErrorOptions, type PersistenceBaseline, type PersistenceChanges, type PersistenceLifecycle, type PersistenceModel, type PhysicalRemovalRegistration, type PreparedDomainMachineDefinition, type ProjectOptions, type Projection, type ProjectionBatchResult, type ProjectionCheckpoint, type ProjectionCheckpointStore, type ProjectionEventHandler, type ProjectionFromHandlersOptions, ProjectionGapError, type ProjectionHandlers, ProjectionIdentityViolationError, ProjectionOrderViolationError, type ProjectionPosition, ProjectionReceiptViolationError, Projector, type ProjectorOptions, type PublishAbortedReport, type PublishChainState, type PublishChainStore, PublishDepthExceededError, type PublishOptions, type PublishedCommand, type Query, QueryBus, type QueryBusOptions, type QueryHandler, type ReadStreamOptions, ReentrantDomainStateMachineEvaluationError, ReentrantEventRecordingError, ReplayHeadMismatchError, type ReplayHeadMismatchErrorOptions, type ReplayableAggregate, type RepositoriesOf, type Repository, type RepositoryDefinition, type RepositoryDefinitionOptions, RepositoryErrorMappingFailedError, type RepositoryTracking, type RetryPolicy, RetryingTransactionScope, RollbackError, type RunOptions, type SharedDomainEventStampOptions, SnapshotCorruptedError, type SnapshotModel, SnapshotSchemaMismatchError, type SnapshotSchemaMismatchErrorOptions, type SnapshotStore, SnapshotTimeValidationError, SnapshotVersionNotRestoredError, type SnapshotVersionNotRestoredErrorOptions, Specification, type SpecificationComposite, StateStoredAggregate, type StateValidator, type StreamReadResult, type SubscriptionThresholdReport, TransactionClosedError, type TransactionScope, type TransactionalOptions, type UncommittedDomainEvent, type UncommittedDomainEventOf, UnenrolledChangesError, UnitOfWork, type UnitOfWorkContext, type UnitOfWorkDeps, type UnitOfWorkIdentityMap, UnmanagedInstanceError, UnmintedEventError, UnprojectableEventError, UnregisteredHandlerError, type UnregisteredHandlerErrorOptions, UnreplayableAggregateError, type VO, ValueObject, type Version, type WithCommitDeps, type WithCommitWorkResult, type WithIdempotentCommitDeps, analyzeDomainMachineDefinition, canTransitionDomainState, captureAggregateSnapshot, capturePersistenceBaseline, copyMetadata, createDomainEvent, createDomainEventFactory, createDomainEventFromFacts, createInitialDomainMachineSnapshot, createIntegrationMessage, createUncommittedDomainEvent, decodeIntegrationMessage, deepEqual, deepEqualExcept, deepFreeze, deepOmit, defaultDomainEventFactory, defineRepository, defineSnapshotModel, derivePersistenceChanges, detachState, domainErrorToResult, encodeIntegrationMessage, entityIds, eventBusSink, findEntityById, freezeShallow, hasEntityId, ignoreProjectionEvent, insertPersistenceBaseline, integrationMessageToCommittedEvent, isDomainErrorLike, isInfrastructureErrorLike, isPositionAfter, mergeMetadata, outboxWriterAcceptingEventLoss, persistenceProjectionDrifted, prepareDomainMachineDefinition, projectionFromHandlers, recapturePersistenceBaseline, reconstituteAggregateFromHistory, reconstituteAggregateFromSnapshot, recordDomainEvent, recordPendingEvents, removeEntityById, replaceEntityById, routeEventsToCommandOutbox, sameEntity, sameVersion, specification, toVersion, transitionDomainState, updateEntityById, vo, voEquals, voEqualsExcept, voValidated, voWithValidation, withCommit, withIdempotentCommit };
+export { type Aggregate, type AggregateAddress, type AggregateAddressMismatchOptions, type AggregateClass, type AggregateCommitToken, type AggregateConfig, AggregateDeletedError, AggregateNotFoundError, type AggregateNotFoundErrorOptions, type AggregatePersistence, type AggregatePersistenceWrite, type AggregateSnapshot, AggregateTrackingError, type AggregateTrackingFailure, type AggregateWriteIntent, type AggregateWriteRegistration, type AnyDomainEvent, type AnyUncommittedDomainEvent, type AppendOnlyWriteRegistration, CapabilityRegistryConflictError, type ClockFactory, type Command, CommandBus, type CommandBusOptions, type CommandCommitOriginCandidate, type CommandHandler, type CommandMessageContent, type CommandMessageRelationships, type CommandOutboxCommitCandidate, type CommandOutboxMapper, type CommandOutboxWriter, type CommitEnrollment, type CommitEnrollmentOptions, CommitError, type CommitPosition, type CommittedDomainEvent, type CompatibleRepositoryDefinitions, ConcurrencyConflictError, type ConcurrencyConflictErrorOptions, type CreateDomainEventFromFactsOptions, type CreateDomainEventOptions, type CreateDomainEventStampOptions, type CreateUncommittedDomainEventOptions, type DeadLetterDeadline, type DeadLetterRecord, DeadlineProcessor, type DeadlineProcessorObservers, type DeadlineProcessorOptions, type DeadlineStore, type DeepEqualExceptOptions, type DeepOmitKey, type DeepOmitOptions, type DeepOmitPathSegment, type DeliveryFailureAssessment, type DeliveryFailureClassifier, type DeliveryFailureKind, DirectStateMutationError, type DispatchTrackingOutbox, DomainError, type DomainErrorClass, type DomainEvent, type DomainEventFactory, type DomainEventFactoryOptions, type DomainEventStamp, type DomainEventStampFactory, type DomainEventStampProvider, type DomainEventValidationCode, DomainEventValidationError, type DomainEventValidationField, type DomainMachineDefinition, type DomainMachineDefinitionAnalysis, type DomainMachineDefinitionDiagnostic, type DomainMachineInput, type DomainMachineReadonly, type DomainMachineSnapshot, type DomainMachineTransitionDescription, DomainStateMachine, type DomainStateNode, type DomainTransition, DomainTransitionGuardRejectedError, type DomainTransitionGuardResult, type DomainTransitionOutcome, type DomainTransitionResult, type DueDeadline, DuplicateAggregateError, type DuplicateAggregateErrorOptions, DuplicateEventIdError, DuplicateHandlerRegistrationError, type DuplicateHandlerRegistrationErrorOptions, type DurableCommandMessage, Entity, type EntityConfig, ErrorMapperFailedError, type ErrorMapperFailedErrorOptions, type EventBus, EventBusClosedError, EventBusImpl, type EventBusObservers, type EventBusOptions, type EventCommitCandidate, type EventCommitCandidatePosition, type EventHandler, EventHarvestError, type EventIdFactory, type EventMetadata, EventSourcedAggregate, type EventStore, type EventStoreAppendOptions, type ExecutionContext, FoldReturnedNoStateError, ForeignEventError, type HandlerFailureReport, HostileStateKeyError, type ICommandBus, type IEntity, type IQueryBus, type IValueObject, type Id, type IdGenerator, type IdempotencyClaim, type IdempotencyClaimHandle, IdempotencyClaimLostError, type IdempotencyClaimLostErrorOptions, IdempotencyCompletionWithoutClaimError, IdempotencyInFlightError, type IdempotencyInFlightErrorOptions, IdempotencyKeyReuseError, type IdempotencyKeyReuseErrorOptions, type IdempotencyLease, type IdempotencyOperationErrorContext, type IdempotencyReconciliation, type IdempotencyReconciliationDecision, IdempotencyReconciliationRequiredError, type IdempotencyReconciliationRequiredErrorOptions, type IdempotencyStore, type IdempotentCommitRequest, type IdempotentCommitResult, type IdempotentExecution, type Identifiable, IdentityMap, InMemoryCapacityExceededError, type InMemoryCapacityExceededErrorOptions, InMemoryDeadlineStore, type InMemoryDeadlineStoreOptions, InMemoryEventStore, type InMemoryEventStoreOptions, InMemoryIdempotencyStore, type InMemoryIdempotencyStoreOptions, InMemoryOutbox, type InMemoryOutboxOptions, InMemoryProjectionCheckpointStore, type InMemoryProjectionCheckpointStoreOptions, InMemorySnapshotStore, type InMemorySnapshotStoreOptions, InfrastructureError, type IntegrationMessage, type IntegrationMessageContent, type IntegrationMessageMapper, type IntegrationMessageRelationships, InvalidCommandMessageError, InvalidDomainMachineContextError, InvalidDomainMachineDefinitionError, InvalidDomainMachineInputError, InvalidDomainMachineSnapshotError, InvalidDomainTransitionError, InvalidDomainTransitionGuardResultError, InvalidDomainTransitionResultError, InvalidIntegrationMessageError, InvalidRepositoryAdapterError, InvalidRepositoryDefinitionError, InvalidVersionError, type JsonObject, type JsonPrimitive, type JsonValue, type KitErrorCode, type KitErrorOptions, MisaddressedEventError, MissingEntityIdError, MissingFoldError, MissingHandlerError, NestedUnitOfWorkError, NonProgressingEventStreamPageError, type NonProgressingEventStreamPageErrorOptions, type OnceOptions, type Outbox, OutboxDispatcher, type OutboxDispatcherObservers, type OutboxDispatcherOptions, type OutboxRecord, type OutboxSink, type OutboxWriter, type PendingDomainEvent, PendingEventBatchMismatchError, PendingEventLimitExceededError, type PendingEventLimitExceededErrorOptions, type PersistenceBaseline, type PersistenceChanges, type PersistenceLifecycle, type PersistenceModel, type PhysicalRemovalRegistration, type PreparedDomainMachineDefinition, type ProjectOptions, type Projection, type ProjectionBatchResult, type ProjectionCheckpoint, type ProjectionCheckpointStore, type ProjectionEventHandler, type ProjectionFromHandlersOptions, ProjectionGapError, type ProjectionHandlers, ProjectionIdentityViolationError, ProjectionOrderViolationError, type ProjectionPosition, ProjectionReceiptViolationError, Projector, type ProjectorOptions, type PublishAbortedReport, type PublishChainState, type PublishChainStore, PublishDepthExceededError, type PublishOptions, type PublishedCommand, type Query, QueryBus, type QueryBusOptions, type QueryHandler, type ReadStreamOptions, ReentrantDomainStateMachineEvaluationError, ReentrantEventRecordingError, ReplayHeadMismatchError, type ReplayHeadMismatchErrorOptions, type ReplayableAggregate, type RepositoriesOf, type Repository, type RepositoryDefinition, type RepositoryDefinitionOptions, RepositoryErrorMappingFailedError, type RepositoryTracking, type RetryPolicy, RetryingTransactionScope, RollbackError, type RunOptions, type SharedDomainEventStampOptions, SnapshotCorruptedError, type SnapshotModel, SnapshotSchemaMismatchError, type SnapshotSchemaMismatchErrorOptions, type SnapshotStore, SnapshotTimeValidationError, SnapshotVersionNotRestoredError, type SnapshotVersionNotRestoredErrorOptions, Specification, type SpecificationComposite, StateStoredAggregate, type StateValidator, type StreamReadResult, type SubscriptionThresholdReport, TransactionClosedError, type TransactionScope, type TransactionalOptions, type UncommittedDomainEvent, type UncommittedDomainEventOf, UnenrolledChangesError, UnitOfWork, type UnitOfWorkContext, type UnitOfWorkDeps, type UnitOfWorkIdentityMap, UnmanagedInstanceError, UnmintedEventError, UnprojectableEventError, UnregisteredHandlerError, type UnregisteredHandlerErrorOptions, UnreplayableAggregateError, type VO, ValueObject, type Version, type WithCommitDeps, type WithCommitWorkResult, type WithIdempotentCommitDeps, analyzeDomainMachineDefinition, canTransitionDomainState, captureAggregateSnapshot, capturePersistenceBaseline, copyMetadata, createDomainEvent, createDomainEventFactory, createDomainEventFromFacts, createInitialDomainMachineSnapshot, createIntegrationMessage, createUncommittedDomainEvent, decodeIntegrationMessage, deepEqual, deepEqualExcept, deepFreeze, deepOmit, defaultDomainEventFactory, defineRepository, defineSnapshotModel, derivePersistenceChanges, detachState, domainErrorToResult, encodeIntegrationMessage, entityIds, eventBusSink, findEntityById, freezeShallow, hasEntityId, ignoreProjectionEvent, insertPersistenceBaseline, integrationMessageToCommittedEvent, isDomainErrorLike, isInfrastructureErrorLike, isPositionAfter, mergeMetadata, outboxWriterAcceptingEventLoss, persistenceProjectionDrifted, prepareDomainMachineDefinition, projectionFromHandlers, recapturePersistenceBaseline, reconstituteAggregateFromHistory, reconstituteAggregateFromSnapshot, recordDomainEvent, recordPendingEvents, removeEntityById, replaceEntityById, routeEventsToCommandOutbox, sameEntity, sameVersion, specification, toVersion, transitionDomainState, updateEntityById, vo, voEquals, voEqualsExcept, voValidated, voWithValidation, withCommit, withIdempotentCommit };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -2212,18 +2212,18 @@ var AggregateTrackingError = class extends KitWiringError {
 	operation;
 	reason;
 	registeredIntent;
-	constructor(aggregateId, operation, reason, registeredIntent) {
-		super("AGGREGATE_TRACKING", trackingFailureMessage(aggregateId, operation, reason, registeredIntent));
+	constructor(aggregateId, operation, reason, registeredIntent, options = {}) {
+		super("AGGREGATE_TRACKING", trackingFailureMessage(aggregateId, operation, reason, registeredIntent, options));
 		this.aggregateId = aggregateId;
 		this.operation = operation;
 		this.reason = reason;
 		this.registeredIntent = registeredIntent;
 	}
 };
-function trackingFailureMessage(aggregateId, operation, reason, registeredIntent) {
+function trackingFailureMessage(aggregateId, operation, reason, registeredIntent, options) {
 	switch (reason) {
 		case "not_loaded": return `Aggregate ${aggregateId} cannot be registered for ${operation}: it was not loaded into this unit of work. Load it through the repository before updating or removing it.`;
-		case "loaded_as_new": return `Aggregate ${aggregateId} cannot be added as new because it was loaded by this unit of work. Use update for a loaded aggregate.`;
+		case "loaded_as_new": return `Aggregate ${aggregateId} cannot be added as new because it was loaded by this unit of work. ` + (options.appendOnly ? "Its repository is append-only, so a loaded aggregate is already persisted and must not change." : "Use update for a loaded aggregate.");
 		case "different_repository": return `Aggregate ${aggregateId} cannot be registered for ${operation} through a different repository in the same unit of work. One aggregate instance must remain owned by the repository definition that first tracked it.`;
 		case "conflicting_intent": return `Aggregate ${aggregateId} is already registered for ${registeredIntent ?? "another write"}; ${operation} would create conflicting persistence intent in one unit of work. Decide the final lifecycle outcome before registering it.`;
 		case "mutated_after_registration": return `Aggregate ${aggregateId} changed after ${registeredIntent ?? "write"} was registered. Make domain decisions first and call add, update, or remove last so persisted state and recorded events cannot diverge.`;
@@ -2386,9 +2386,14 @@ function defineForwardedRepositoryProperty(state, property, descriptor) {
 	});
 	state.forwardedOwnProperties.add(property);
 }
+function installedLifecycleOperations(definition) {
+	const operations = ["add"];
+	if (!definition.appendOnly) operations.push("update");
+	if (definition.physicalRemoval) operations.push("remove");
+	return operations;
+}
 function installRepositoryLifecycleOperations(state) {
-	const operations = state.definition.physicalRemoval ? REPOSITORY_LIFECYCLE_OPERATIONS : REPOSITORY_LIFECYCLE_OPERATIONS.slice(0, 2);
-	for (const operation of operations) {
+	for (const operation of installedLifecycleOperations(state.definition)) {
 		state.writes.add(operation);
 		Object.defineProperty(state.target, operation, {
 			configurable: false,
@@ -2414,13 +2419,13 @@ function createRepositoryFacadeHandler(state) {
 			if (!hasMemberBelowObjectPrototype(target, property) && !hasMemberBelowObjectPrototype(state.source, property)) return Reflect.get(target, property, receiver);
 			state.session.assertOpen(repositoryOperationName(property));
 			if (Reflect.getOwnPropertyDescriptor(target, property)) return Reflect.get(target, property, receiver);
-			if (property === "remove") return void 0;
+			if (isRepositoryLifecycleOperation(property)) return void 0;
 			return readRepositorySource(state, property);
 		},
 		set: (target, property, value, receiver) => setRepositoryFacadeProperty(state, target, property, value, receiver),
 		has: (target, property) => {
 			state.session.assertOpen(repositoryOperationName(property));
-			return state.writes.has(property) || property !== "remove" && (Reflect.has(target, property) || Reflect.has(state.source, property));
+			return state.writes.has(property) || !isRepositoryLifecycleOperation(property) && (Reflect.has(target, property) || Reflect.has(state.source, property));
 		},
 		defineProperty: (target, property, descriptor) => defineRepositoryFacadeProperty(state, target, property, descriptor),
 		deleteProperty: (target, property) => deleteRepositoryFacadeProperty(state, target, property)
@@ -2771,7 +2776,7 @@ var Session = class {
 		this.assertNotRemoved(aggregate, definition);
 		const existing = this._trackingByAggregate.get(aggregate);
 		if (existing && existing.definition !== definition) throw new AggregateTrackingError(String(aggregate.id), "add", "different_repository", existing.registration?.intent);
-		if (existing?.lifecycle === "loaded") throw new AggregateTrackingError(String(aggregate.id), "add", "loaded_as_new", existing.registration?.intent);
+		if (existing?.lifecycle === "loaded") throw new AggregateTrackingError(String(aggregate.id), "add", "loaded_as_new", existing.registration?.intent, { appendOnly: definition.appendOnly === true });
 		let entry = existing;
 		const newlyTracked = !entry;
 		if (!entry) {
@@ -2888,12 +2893,12 @@ var Session = class {
 				this.assertUnchangedAfterRegistration(entry);
 				continue;
 			}
-			if (entry.lifecycle === "loaded" && (entry.aggregate.version !== entry.expectedVersion || persistenceProjectionDrifted(entry.baseline, entry.aggregate))) throw new UnenrolledChangesError(String(entry.aggregate.id));
+			if (entry.lifecycle === "loaded" && (entry.aggregate.version !== entry.expectedVersion || persistenceProjectionDrifted(entry.baseline, entry.aggregate))) throw new UnenrolledChangesError(String(entry.aggregate.id), { appendOnly: entry.definition.appendOnly === true });
 		}
 		for (const instance of this._identityMap.instancesWithNewPendingEvents()) {
 			if (instance !== null && typeof instance === "object" && this.registrationOf(instance) !== void 0) continue;
 			const id = instance.id;
-			throw new UnenrolledChangesError(String(id));
+			throw new UnenrolledChangesError(String(id), { appendOnly: this._trackingByAggregate.get(instance)?.definition.appendOnly === true });
 		}
 	}
 	/** Flushes every registered receipt in deterministic registration order. */
@@ -2954,20 +2959,7 @@ function mapRepositoryPersistenceError(definition, error, write) {
 
 //#endregion
 //#region src/application/unit-of-work/unit-of-work.ts
-const repositoryDefinitionBrand = Symbol.for("@shirudo/ddd-kit/repository-definition/v1");
-/**
-* Defines repository wiring for an application-owned driven port.
-*
-* The first call makes the port explicit; the second infers the transaction,
-* aggregate, persistence, event, and removal types from the adapter wiring.
-* The port must declare `add` and `update`; if it declares `remove`, the
-* definition must set `physicalRemoval: true`. The adapter created by the
-* definition implements only the remaining methods because lifecycle writes
-* are installed by the Unit of Work.
-* The returned definition is the only form accepted by {@link UnitOfWork}; a
-* raw adapter-shaped object cannot silently turn its concrete surface into the
-* application contract.
-*/
+const repositoryDefinitionBrand = Symbol.for("@shirudo/ddd-kit/repository-definition/v2");
 function assertRepositoryDefinitionMembers(definition) {
 	for (const key of [
 		"create",
@@ -2977,6 +2969,21 @@ function assertRepositoryDefinitionMembers(definition) {
 	if (typeof definition.aggregate !== "function") throw new TypeError("defineRepository: \"aggregate\" is missing or not a class reference on the definition. Pass a plain object literal with own enumerable properties.");
 	if (definition.persistence === null || typeof definition.persistence !== "object") throw new TypeError("defineRepository: \"persistence\" is missing or not a PersistenceModel on the definition. Pass a plain object literal with own enumerable properties.");
 }
+/**
+* Defines repository wiring for an application-owned driven port.
+*
+* The first call makes the port explicit; the second infers the transaction,
+* aggregate, persistence, event, and lifecycle types from the adapter wiring.
+* The port must declare `add` for the aggregate. It declares `update` unless
+* the definition sets `appendOnly: true`. If it declares `remove`, the
+* definition must set `physicalRemoval: true`. A violated constraint fails
+* the call with a compiler error that names the constraint. The adapter
+* created by the definition implements only the remaining methods because
+* lifecycle writes are installed by the Unit of Work.
+* The returned definition is the only form accepted by {@link UnitOfWork}; a
+* raw adapter-shaped object cannot silently turn its concrete surface into the
+* application contract.
+*/
 function defineRepository() {
 	const builder = (definition) => {
 		const branded = { ...definition };