The Run model in QM represents a queued task carrying identity, session affiliation, execution status, request/result payloads, deduplication key, attempt tracking, lease expiration, and timestamps — enabling the store to route, deduplicate, retry, and track lifecycle. In src/sessions/postgres-session-store.ts, the entry search function is marked parallel-unsafe to prevent race conditions when multiple callers query session entries simultaneously under concurrent Postgres planner execution.
src/runs/run-store.ts defines the Run data model, which carries id, sessionId, status ("pending" | "running" | "done" | "failed"), request, result, deliveryState, dedupKey, attempts, errorAttempts, maxAttempts, leaseToken, leaseExpiresAt, workerId, createdAt, startedAt, and finishedAt.[1]
RunStore.enqueue accepts an EnqueueInput that includes an optional dedupKey; it returns an EnqueueResult whose deduped: boolean flag indicates whether the run was matched against an existing one rather than newly created.[1]
leaseLapsed considers a run's lease expired when its status is "running", leaseExpiresAt is non-null, and leaseExpiresAt <= asOf.[1] errorParks returns true — meaning the run will be parked rather than requeued — when either errorAttempts + 1 >= maxAttempts or when an optional maxClaims value is defined and attempts >= maxClaims.[1] A lease is a time-bounded claim on a run granted to a worker; if the worker does not complete or renew it before leaseExpiresAt, the run is considered abandoned and becomes eligible for reaping and requeueing. Parking a run moves it to a permanent failure state rather than requeueing it for another attempt, preventing infinite retry loops when a run repeatedly errors.
RunStore.reapExpired returns a { requeued, parked } count, accepts an optional onReap callback that receives a ReapEvent for each reaped run, and an optional async onRetired hook called with the session IDs of fully-retired runs.[1] RunStore.waitFor polls or waits for a run to reach terminal status and accepts an optional timeoutMs to bound the wait.[1]
Sources