Class: LifecycleEffectRepository

Defined in: server/lifecycle/lifecycle-effect-repository.ts:53

Repository over lifecycle_effects — the transactional outbox. Writes (insert) participate in the engine's transaction via this.tx; the claim / mark methods are called by the dispatcher, typically OUTSIDE the producing transaction.

The claim path increments attempts AT CLAIM TIME so a handler that crashes (never reaching markFailed) still counts toward the dead-letter threshold — a poison row can't be retried forever.

ExtendsCopy Anchor Link

• ReadRepository<PrismaClient, LifecycleEffect, string, Tx<PrismaClient>>

ConstructorsCopy Anchor Link

ConstructorCopy Anchor Link

new LifecycleEffectRepository(prismaClient: PrismaClient, options?: LifecycleRepositoryOptions): LifecycleEffectRepository;

Defined in: server/lifecycle/lifecycle-effect-repository.ts:61

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

LifecycleEffectRepository

OverridesCopy Anchor Link

ReadRepository.constructor

PropertiesCopy Anchor Link

ENTITY_TYPE?Copy Anchor Link

protected readonly optional ENTITY_TYPE?: string;

Defined in: server/persistence/base-repository.ts:61

Set ENTITY_TYPE in child repositories to enable automatic activity logging. When set, create/update/delete operations auto-log unless silenced with .silent. Requires an activity model on the consumer's Prisma schema.

Inherited fromCopy Anchor Link

ReadRepository.ENTITY_TYPE

logger?Copy Anchor Link

protected readonly optional logger?: Logger;

Defined in: server/persistence/base-repository.ts:64

Inherited fromCopy Anchor Link

ReadRepository.logger

prismaClientCopy Anchor Link

protected prismaClient: PrismaClientLike<Tx<PrismaClient<PrismaClientOptions, never, DefaultArgs>>> & PrismaClient<PrismaClientOptions, never, DefaultArgs>;

Defined in: server/persistence/base-repository.ts:69

Inherited fromCopy Anchor Link

ReadRepository.prismaClient

AccessorsCopy Anchor Link

actorIdCopy Anchor Link

Get SignatureCopy Anchor Link

get protected actorId(): string | null | undefined;

Defined in: server/persistence/base-repository.ts:76

ReturnsCopy Anchor Link

string | null | undefined

Inherited fromCopy Anchor Link

ReadRepository.actorId

auditCreateCopy Anchor Link

Get SignatureCopy Anchor Link

get protected auditCreate(): {
  createdBy: string | null | undefined;
  updatedBy: string | null | undefined;
};

Defined in: server/persistence/base-repository.ts:90

ReturnsCopy Anchor Link

{
  createdBy: string | null | undefined;
  updatedBy: string | null | undefined;
}

createdByCopy Anchor Link

createdBy: string | null | undefined = actorId;

updatedByCopy Anchor Link

updatedBy: string | null | undefined = actorId;

Inherited fromCopy Anchor Link

ReadRepository.auditCreate

auditDeleteCopy Anchor Link

Get SignatureCopy Anchor Link

get protected auditDelete(): {
  deletedAt: Date;
  deletedBy: string | null | undefined;
};

Defined in: server/persistence/base-repository.ts:99

ReturnsCopy Anchor Link

{
  deletedAt: Date;
  deletedBy: string | null | undefined;
}

deletedAtCopy Anchor Link

deletedAt: Date;

deletedByCopy Anchor Link

deletedBy: string | null | undefined;

Inherited fromCopy Anchor Link

ReadRepository.auditDelete

auditUpdateCopy Anchor Link

Get SignatureCopy Anchor Link

get protected auditUpdate(): {
  updatedBy: string | null | undefined;
};

Defined in: server/persistence/base-repository.ts:95

ReturnsCopy Anchor Link

{
  updatedBy: string | null | undefined;
}

updatedByCopy Anchor Link

updatedBy: string | null | undefined;

Inherited fromCopy Anchor Link

ReadRepository.auditUpdate

silentCopy Anchor Link

Get SignatureCopy Anchor Link

get silent(): this;

Defined in: server/persistence/base-repository.ts:115

Suppress activity logging for the next mutation call. One-shot: the flag is consumed by the next create/update/delete.

ExampleCopy Anchor Link

await repo.silent.update(id, data);   // no activity logged
await repo.update(id, data);          // activity logged normally

ReturnsCopy Anchor Link

this

Inherited fromCopy Anchor Link

ReadRepository.silent

txCopy Anchor Link

Get SignatureCopy Anchor Link

get protected tx(): TTx;

Defined in: server/persistence/base-repository.ts:86

The current Prisma handle: the active transaction if one is running on this async context, otherwise the raw client.

ReturnsCopy Anchor Link

TTx

Inherited fromCopy Anchor Link

ReadRepository.tx

MethodsCopy Anchor Link

_count()Copy Anchor Link

protected _count(): Promise<number>;

Defined in: server/lifecycle/lifecycle-effect-repository.ts:90

ReturnsCopy Anchor Link

Promise<number>

OverridesCopy Anchor Link

ReadRepository._count

_exists()Copy Anchor Link

protected _exists(id: string): Promise<boolean>;

Defined in: server/lifecycle/lifecycle-effect-repository.ts:83

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

Promise<boolean>

OverridesCopy Anchor Link

ReadRepository._exists

_findById()Copy Anchor Link

protected _findById(id: string): Promise<
  | {
  attempts: number;
  claimedBy: string | null;
  createdAt: Date;
  createdBy: string | null;
  dispatchedAt: Date | null;
  effectName: string;
  id: string;
  lastError: string | null;
  lockedUntil: Date | null;
  ordinal: number;
  organizationId: string | null;
  payload: JsonValue;
  status: LifecycleEffectStatus;
  transitionId: string;
  updatedAt: Date;
  updatedBy: string | null;
}
| null>;

Defined in: server/lifecycle/lifecycle-effect-repository.ts:77

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

Promise< | { attempts: number; claimedBy: string | null; createdAt: Date; createdBy: string | null; dispatchedAt: Date | null; effectName: string; id: string; lastError: string | null; lockedUntil: Date | null; ordinal: number; organizationId: string | null; payload: JsonValue; status: LifecycleEffectStatus; transitionId: string; updatedAt: Date; updatedBy: string | null; } | null>

OverridesCopy Anchor Link

ReadRepository._findById

_findMany()Copy Anchor Link

protected _findMany(pagination: {
  page: number;
  pageSize: number;
}): Promise<{
  items: {
     attempts: number;
     claimedBy: string | null;
     createdAt: Date;
     createdBy: string | null;
     dispatchedAt: Date | null;
     effectName: string;
     id: string;
     lastError: string | null;
     lockedUntil: Date | null;
     ordinal: number;
     organizationId: string | null;
     payload: JsonValue;
     status: LifecycleEffectStatus;
     transitionId: string;
     updatedAt: Date;
     updatedBy: string | null;
  }[];
  total: number;
}>;

Defined in: server/lifecycle/lifecycle-effect-repository.ts:94

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

Promise<{ items: { attempts: number; claimedBy: string | null; createdAt: Date; createdBy: string | null; dispatchedAt: Date | null; effectName: string; id: string; lastError: string | null; lockedUntil: Date | null; ordinal: number; organizationId: string | null; payload: JsonValue; status: LifecycleEffectStatus; transitionId: string; updatedAt: Date; updatedBy: string | null; }[]; total: number; }>

OverridesCopy Anchor Link

ReadRepository._findMany

claimBatch()Copy Anchor Link

claimBatch(input: ClaimBatchInput): Promise<{
  attempts: number;
  claimedBy: string | null;
  createdAt: Date;
  createdBy: string | null;
  dispatchedAt: Date | null;
  effectName: string;
  id: string;
  lastError: string | null;
  lockedUntil: Date | null;
  ordinal: number;
  organizationId: string | null;
  payload: JsonValue;
  status: LifecycleEffectStatus;
  transitionId: string;
  updatedAt: Date;
  updatedBy: string | null;
}[]>;

Defined in: server/lifecycle/lifecycle-effect-repository.ts:156

Claim a batch of dispatchable effects: rows that are pending, or processing with an expired lease, AND still under maxAttempts. Claiming marks the row processing, stamps claimedBy + lockedUntil, and bumps attempts.

Exhausted rows (attempts >= maxAttempts) are dead-lettered (failed) in a SEPARATE step that does NOT consume the claim budget — otherwise a batch of poison rows could starve real pending work and make drain report claimed === 0 while dispatchable effects remain, stalling the "loop until claimed === 0" driver. Invariant: claimBatch returns > 0 whenever any dispatchable row (pending or expired-lease, attempts < maxAttempts) exists.

The claim is a single updateManyAndReturn whose where re-checks claimability (still pending, or still-expired lease), so a row another worker grabbed concurrently no longer matches — two workers never claim the same row, and there is no per-row N+1. Ordered by (transitionId, ordinal) to preserve per-transition dispatch order.

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

Promise<{ attempts: number; claimedBy: string | null; createdAt: Date; createdBy: string | null; dispatchedAt: Date | null; effectName: string; id: string; lastError: string | null; lockedUntil: Date | null; ordinal: number; organizationId: string | null; payload: JsonValue; status: LifecycleEffectStatus; transitionId: string; updatedAt: Date; updatedBy: string | null; }[]>

consumeSilent()Copy Anchor Link

protected consumeSilent(): boolean;

Defined in: server/persistence/base-repository.ts:128

Consume and reset the silent flag. Called by template methods.

ReturnsCopy Anchor Link

boolean

Inherited fromCopy Anchor Link

ReadRepository.consumeSilent

count()Copy Anchor Link

count(): Promise<number>;

Defined in: server/persistence/base-repository.ts:191

ReturnsCopy Anchor Link

Promise<number>

Inherited fromCopy Anchor Link

ReadRepository.count

exists()Copy Anchor Link

exists(id: string): Promise<boolean>;

Defined in: server/persistence/base-repository.ts:187

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

Promise<boolean>

Inherited fromCopy Anchor Link

ReadRepository.exists

findById()Copy Anchor Link

findById(id: string): Promise<
  | {
  attempts: number;
  claimedBy: string | null;
  createdAt: Date;
  createdBy: string | null;
  dispatchedAt: Date | null;
  effectName: string;
  id: string;
  lastError: string | null;
  lockedUntil: Date | null;
  ordinal: number;
  organizationId: string | null;
  payload: JsonValue;
  status: LifecycleEffectStatus;
  transitionId: string;
  updatedAt: Date;
  updatedBy: string | null;
}
| null>;

Defined in: server/persistence/base-repository.ts:177

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

Promise< | { attempts: number; claimedBy: string | null; createdAt: Date; createdBy: string | null; dispatchedAt: Date | null; effectName: string; id: string; lastError: string | null; lockedUntil: Date | null; ordinal: number; organizationId: string | null; payload: JsonValue; status: LifecycleEffectStatus; transitionId: string; updatedAt: Date; updatedBy: string | null; } | null>

Inherited fromCopy Anchor Link

ReadRepository.findById

findByIdOrThrow()Copy Anchor Link

findByIdOrThrow(id: string): Promise<{
  attempts: number;
  claimedBy: string | null;
  createdAt: Date;
  createdBy: string | null;
  dispatchedAt: Date | null;
  effectName: string;
  id: string;
  lastError: string | null;
  lockedUntil: Date | null;
  ordinal: number;
  organizationId: string | null;
  payload: JsonValue;
  status: LifecycleEffectStatus;
  transitionId: string;
  updatedAt: Date;
  updatedBy: string | null;
}>;

Defined in: server/persistence/base-repository.ts:181

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

Promise<{ attempts: number; claimedBy: string | null; createdAt: Date; createdBy: string | null; dispatchedAt: Date | null; effectName: string; id: string; lastError: string | null; lockedUntil: Date | null; ordinal: number; organizationId: string | null; payload: JsonValue; status: LifecycleEffectStatus; transitionId: string; updatedAt: Date; updatedBy: string | null; }>

Inherited fromCopy Anchor Link

ReadRepository.findByIdOrThrow

findByTransitionId()Copy Anchor Link

findByTransitionId(transitionId: string): Promise<{
  attempts: number;
  claimedBy: string | null;
  createdAt: Date;
  createdBy: string | null;
  dispatchedAt: Date | null;
  effectName: string;
  id: string;
  lastError: string | null;
  lockedUntil: Date | null;
  ordinal: number;
  organizationId: string | null;
  payload: JsonValue;
  status: LifecycleEffectStatus;
  transitionId: string;
  updatedAt: Date;
  updatedBy: string | null;
}[]>;

Defined in: server/lifecycle/lifecycle-effect-repository.ts:129

All effect rows for a transition, in declared (ordinal) order.

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

Promise<{ attempts: number; claimedBy: string | null; createdAt: Date; createdBy: string | null; dispatchedAt: Date | null; effectName: string; id: string; lastError: string | null; lockedUntil: Date | null; ordinal: number; organizationId: string | null; payload: JsonValue; status: LifecycleEffectStatus; transitionId: string; updatedAt: Date; updatedBy: string | null; }[]>

findMany()Copy Anchor Link

findMany(pagination: {
  page: number;
  pageSize: number;
}): Promise<OffsetPaginatedResult<{
  attempts: number;
  claimedBy: string | null;
  createdAt: Date;
  createdBy: string | null;
  dispatchedAt: Date | null;
  effectName: string;
  id: string;
  lastError: string | null;
  lockedUntil: Date | null;
  ordinal: number;
  organizationId: string | null;
  payload: JsonValue;
  status: LifecycleEffectStatus;
  transitionId: string;
  updatedAt: Date;
  updatedBy: string | null;
}>>;

Defined in: server/persistence/base-repository.ts:195

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

Promise<OffsetPaginatedResult<{ attempts: number; claimedBy: string | null; createdAt: Date; createdBy: string | null; dispatchedAt: Date | null; effectName: string; id: string; lastError: string | null; lockedUntil: Date | null; ordinal: number; organizationId: string | null; payload: JsonValue; status: LifecycleEffectStatus; transitionId: string; updatedAt: Date; updatedBy: string | null; }>>

Inherited fromCopy Anchor Link

ReadRepository.findMany

insertMany()Copy Anchor Link

insertMany(inputs: InsertEffectInput[]): Promise<number>;

Defined in: server/lifecycle/lifecycle-effect-repository.ts:110

Insert a batch of pending effect rows for a transition (audit-threaded).

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

Promise<number>

logActivity()Copy Anchor Link

protected logActivity(
   _entityId: string, 
   _action: string, 
   _metadata?: Record<string, unknown>
): Promise<void>;

Defined in: server/persistence/base-repository.ts:140

Log an activity entry.

NOTE: This is not implemented because there's no activity model implemented in taproot yet! https://linear.app/kaizenlabs/issue/ENG-7846/add-activity-log-tables

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

Promise<void>

Inherited fromCopy Anchor Link

ReadRepository.logActivity

markDispatched()Copy Anchor Link

markDispatched(effect: ClaimedEffect): Promise<boolean>;

Defined in: server/lifecycle/lifecycle-effect-repository.ts:236

Mark a claimed effect dispatched and release its lease. This is the at-least-once delivery boundary: a handler may have succeeded but this write (or the process) crashed before recording it, so the row's lease expires and the effect is redelivered. Handlers MUST therefore be idempotent.

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

Promise<boolean>

markFailed()Copy Anchor Link

markFailed(
   effect: ClaimedEffect, 
   lastError: string, 
   maxAttempts: number
): Promise<boolean>;

Defined in: server/lifecycle/lifecycle-effect-repository.ts:275

Mark a claimed effect's dispatch outcome a failure: back to pending for retry, or failed (dead-letter) when it has now reached maxAttempts. Releases the lease either way.

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

Promise<boolean>

notFoundError()Copy Anchor Link

protected notFoundError(id: string): Error;

Defined in: server/lifecycle/lifecycle-effect-repository.ts:73

Create a not-found error. Override to provide custom error types.

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

Error

OverridesCopy Anchor Link

ReadRepository.notFoundError

release()Copy Anchor Link

release(effect: ClaimedEffect): Promise<boolean>;

Defined in: server/lifecycle/lifecycle-effect-repository.ts:256

Release a claimed-but-not-dispatched effect back to pending, clearing its lease. Used when a caller deliberately does not invoke the handler. Refunds the claim-time attempt because the effect was never delivered.

ParametersCopy Anchor Link

ReturnsCopy Anchor Link

Promise<boolean>