Core Reducer

@runlane/core owns run lifecycle semantics. The low-level public primitive is projectRunEvents(), a pure reducer that turns append-only RunEvent values into the RunRecord projection storage adapters persist.

Most application code should never call this directly. Runtime APIs such as trigger(), runNow(), worker(), tick(), and runs.cancel() call it before they ask storage to append lifecycle events. Adapter authors need the contract because storage must persist the supplied events and supplied projection atomically without reimplementing status, counter, lease, retry, release, or cancellation rules.

Short example

The reducer can create a run from its first durable event:

import { asId, contractDefaults, RunEventType } from '@runlane/contracts'
import { projectRunEvents } from '@runlane/core'

const environment = { name: 'production' }
const runId = asId<'run'>('run_123')
const now = new Date()

const projectedRun = projectRunEvents({
  expectedSequence: contractDefaults.run.newEventSequence,
  events: [
    {
      actor: contractDefaults.actor.system,
      environment,
      occurredAt: now,
      payload: { userId: 'user_123' },
      queue: contractDefaults.queue,
      runId,
      taskId: asId<'task'>('emails.send'),
      type: RunEventType.Created,
    },
  ],
})

The returned RunRecord has eventSequence: 1, zeroed counters, status: "queued", and the durable identity fields copied from the created event.

Appending later events starts from the current materialized run:

const updatedRun = projectRunEvents({
  currentRun: projectedRun,
  expectedSequence: projectedRun.eventSequence,
  events: [
    {
      actor: contractDefaults.actor.system,
      delivery: {
        availableAt: now,
        environment,
        queue: contractDefaults.queue,
        requestedAt: now,
        runId,
      },
      environment,
      occurredAt: now,
      runId,
      type: RunEventType.DeliveryRequested,
    },
  ],
})

Sequence contract

expectedSequence must match the current run sequence. Use contractDefaults.run.newEventSequence when creating a run and the current RunRecord.eventSequence when appending to an existing run. A stale sequence throws RunlaneError with ErrorCode.StorageConflict so callers can retry the read-project-append operation.

The reducer assigns projected sequences in memory as expectedSequence + event index + 1. Storage still owns durable event ids and must reject appends if its current sequence no longer matches the command.

Projection failures use two different error classes:

Adapters should preserve this distinction. A stale sequence is a normal lost race. An impossible projection means core, storage, or persisted history is inconsistent.

Lifecycle rules

run.created is the only valid first event. It creates a queued run with zero attempts, failures, retries, and releases. The run projection copies durable identity and creation fields from this event: runId, environment, taskId, queue, payload, runAt, concurrencyKey, idempotencyKey, singletonKey, source, traceCarrier, meta, createdAt, and updatedAt.

Every later event must target the same runId and environment as the current projection. Terminal runs reject all later lifecycle events; rerun and manual retry create new source-linked runs instead of mutating terminal history.

Attempt completion events are run.succeeded, run.failed, run.retry_scheduled, and run.released. They require a running or cancellation_requested run, require at least one started attempt, and must reference the current attempt number. The reducer does not infer attempt numbers from event order.

Projection Fields

RunRecord is the materialized view of durable history. These fields have reducer-owned semantics:

The reducer does not create outbox rows. It only projects fields that storage and runtime code use when deciding whether outbox, dispatch, lease, and operator behavior is valid.

Adapter boundary

Adapters should treat the projected run as caller-supplied truth that must be checked, not silently trusted. A storage adapter should verify the command environment, run id, expected sequence, projected final sequence, and command-specific ownership before committing.

appendRunEvents() must compare the current persisted sequence with expectedSequence before validating projection invariants. If it does not match, reject with ErrorCode.StorageConflict and StorageConflictKind.EventSequence; do not report a stale append as a projection bug.

When an append succeeds, storage commits these records atomically:

• append-only event-history rows with storage-assigned ids and monotonic per-run sequences
• the supplied projectedRun
• storage-owned idempotency or singleton ownership updates
• outbox rows derived from any run.delivery_requested events

reserveRunDispatch(), claimRunLease(), and heartbeatRunLease() also receive core-projected events and projected runs. Storage owns the atomic capacity, dispatch-reservation, lease-ownership, and sequence checks for those operations, but it should not recompute the materialized lifecycle projection.

The returned RunEventRecord values must be the exact rows persisted to history, including ids and sequence numbers. Do not generate one event id for storage and another for the API result.

See Adapter Authoring for the full storage contract and Run Lifecycle Vocabulary for stable status and event names.