RunStore
@forge/monorepo / backend/src / RunStore
Interface: RunStore
Defined in: backend/src/persistence/index.ts:229
The run's durable lifecycle store. Beyond read/claim it owns lease keepalive, guarded status
transitions, durable cancellation and stale-lease reaping — the primitives the durable worker
(createDurableWorker) needs for crash recovery without duplicate work. Verified by the shared
runStoreConformance harness so every adapter agrees on claim/lease/transition semantics.
Methods
claim()
claim(
input):Promise<Run|null>
Defined in: backend/src/persistence/index.ts:237
Atomic lease-based claim. Succeeds for a queued run, or for a running run whose lease has
expired (crash recovery). Returns null when another worker holds a live lease or the run is
terminal — so two workers never process one run.
Parameters
input
TenantScope & object
Returns
Promise<Run | null>
countLive()
countLive(
input):Promise<number>
Defined in: backend/src/persistence/index.ts:271
How many of a tenant's runs hold a live lease right now.
Not the enforcement path — claim is, because only claim can be atomic with the decision. This
exists for two honest uses: telling an operator why a tenant's work is waiting, and letting the worker
label a refused claim. A slightly stale answer costs a wrong log line, never a wrong admission.
Parameters
input
TenantScope & object
Returns
Promise<number>
create()
create(
input):Promise<Run>
Defined in: backend/src/persistence/index.ts:230
Parameters
input
Returns
Promise<Run>
findById()
findById(
input):Promise<Run|null>
Defined in: backend/src/persistence/index.ts:231
Parameters
input
TenantScope & object
Returns
Promise<Run | null>
keepalive()
keepalive(
input):Promise<boolean>
Defined in: backend/src/persistence/index.ts:273
Extend the lease. Returns false when the claim was lost (reaped/stolen) so the worker aborts.
Parameters
input
TenantScope & object
Returns
Promise<boolean>
reapExpired()
reapExpired(
input):Promise<readonlyRun[]>
Defined in: backend/src/persistence/index.ts:292
Maintenance sweep for runs whose lease expired — recovery candidates. Cross-tenant by design
(a background reaper has no tenant); each returned run carries its own tenantId for re-claim.
Parameters
input
limit
number
now
string
Returns
Promise<readonly Run[]>
requestCancel()
requestCancel(
input):Promise<Run|null>
Defined in: backend/src/persistence/index.ts:287
Persist a cancellation request. The owning worker observes it and stops cooperatively.
Parameters
input
TenantScope & object
Returns
Promise<Run | null>
transition()
transition(
input):Promise<Run>
Defined in: backend/src/persistence/index.ts:277
Guarded transition by the claiming worker; rejects moves absent from RUN_TRANSITIONS.
Parameters
input
TenantScope & object
Returns
Promise<Run>