@usine/engine/engine

Classes

AttemptCancellationError

The Run is canceled, but interrupting its active Attempt failed.

Extends

• Schema.Class

Constructors

Constructor

new AttemptCancellationError(…args): AttemptCancellationError

Parameters

Parameter	Type
…args	[props: object, options?: MakeOptions]

Returns

AttemptCancellationError

Properties

attemptId

readonly attemptId: string & Brand<"AttemptId">

cause

readonly cause: unknown

---

Claimed

The Event now owns a Run; submitting it again returns the same run id.

Extends

• Schema.Class

Constructors

Constructor

new Claimed(…args): Claimed

Parameters

Parameter	Type
…args	[props: object, options?: MakeOptions]

Returns

Claimed

Properties

eventId

readonly eventId: string & Brand<"EventId">

runId

readonly runId: string & Brand<"RunId">

---

CycleBlocked

No Run opened because this Item requires an explicit cycle-budget reset.

Extends

• Schema.Class

Constructors

Constructor

new CycleBlocked(…args): CycleBlocked

Parameters

Parameter	Type
…args	[props: object, options?: MakeOptions]

Returns

CycleBlocked

Properties

ask

readonly ask: CycleBudgetAsk

eventId

readonly eventId: string & Brand<"EventId">

---

EnginePersistenceError

An operation could not read or update the instance’s durable records.

Extends

• Schema.Class

Constructors

Constructor

new EnginePersistenceError(…args): EnginePersistenceError

Parameters

Parameter	Type
…args	[props: object, options?: MakeOptions]

Returns

EnginePersistenceError

Properties

cause

readonly cause: unknown

operation

readonly operation: string

---

Ignored

The Event stays in the ledger but can no longer open a Run.

Extends

• Schema.Class

Constructors

Constructor

new Ignored(…args): Ignored

Parameters

Parameter	Type
…args	[props: object, options?: MakeOptions]

Returns

Ignored

Properties

eventId

readonly eventId: string & Brand<"EventId">

reason

readonly reason: "superseded" | "revoked"

---

Queued

A running Attempt on the same Item must finish before this Event is reconsidered.

Extends

• Schema.Class

Constructors

Constructor

new Queued(…args): Queued

Parameters

Parameter	Type
…args	[props: object, options?: MakeOptions]

Returns

Queued

Properties

eventId

readonly eventId: string & Brand<"EventId">

---

RunEngine

Records Events and manages their Runs through approval, execution, retry, and cancellation.

Extends

• Context.ServiceClass

Properties

Service

readonly Service: object

The service’s operations: what yield* RunEngine returns.

approve

readonly approve: (runId, approval) => Effect.Effect<void, RunEngineError>

Records the operator’s approval Event and opens the Run’s gate; execution still waits for a Worker slot.

Parameters

Parameter	Type
runId	RunId
approval	Event

Returns

Effect.Effect<void, RunEngineError>

cancel

readonly cancel: (runId) => Effect.Effect<void, RunEngineError>

Cancels an open Run and interrupts its active Attempt. An already closed Run is unchanged.

Parameters

Parameter	Type
runId	RunId

Returns

Effect.Effect<void, RunEngineError>

drain

readonly drain: () => Effect.Effect<void>

Stops admitting Attempts, including retries, and waits for admitted work to settle. Interrupting this wait keeps admission closed until restart.

Returns

Effect.Effect<void>

inspect

readonly inspect: (runId) => Effect.Effect<RunSnapshot, RunEngineError>

Reads the Run’s current state, effective task and Agent, Step result, and Attempt history.

Parameters

Parameter	Type
runId	RunId

Returns

Effect.Effect<RunSnapshot, RunEngineError>

intervene

readonly intervene: (runId, attemptId, intervention) => Effect.Effect<void, RunEngineError>

Addresses one current Attempt explicitly so an old drawer cannot steer its replacement.

Parameters

Parameter	Type
runId	RunId
attemptId	AttemptId
intervention	Intervention

Returns

Effect.Effect<void, RunEngineError>

reconcile

readonly reconcile: () => Effect.Effect<void, RunEngineError>

Starts a fiber for every open Run without one in this process, except Runs waiting for their approval, and opens the queued Events no closed Run continued. Also runs when the engine starts, then every ReconcileInterval.

Returns

Effect.Effect<void, RunEngineError>

resolveFailure

readonly resolveFailure: (runId, attemptId) => Effect.Effect<void, RunEngineError>

Resolves the current failed Attempt’s attention without changing its outcome or starting work.

Parameters

Parameter	Type
runId	RunId
attemptId	AttemptId

Returns

Effect.Effect<void, RunEngineError>

retry

readonly retry: (runId, amendment?) => Effect.Effect<void, RunEngineError>

Requests another Attempt for a failed Run using its existing Event and effective task and Agent.

Parameters

Parameter	Type
runId	RunId
amendment?	Option.Option<AttemptContext>

Returns

Effect.Effect<void, RunEngineError>

revoke

readonly revoke: (loop, itemKey) => Effect.Effect<ReadonlyArray<RunId>, RunEngineError>

Cancels unstarted Runs and discards queued Events for a Loop’s Item when it stops matching; running Attempts continue.

Parameters

Parameter	Type
loop	LoopName
itemKey	ItemKey

Returns

Effect.Effect<ReadonlyArray<RunId>, RunEngineError>

submit

readonly submit: (submission) => Effect.Effect<SubmissionResult, RunEngineError>

Records a matching Event and claims its Run, or queues it behind the Item’s running Attempt. Repeated Events are deduplicated; execution continues separately.

Parameters

Parameter	Type
submission	Submission

Returns

Effect.Effect<SubmissionResult, RunEngineError>

transcript

readonly transcript: (query) => Effect.Effect<ReadonlyArray<TranscriptEntry>, RunEngineError>

Reads the requested portion of an Attempt’s persisted transcript in append order.

Parameters

Parameter	Type
query	TranscriptQuery

Returns

Effect.Effect<ReadonlyArray<TranscriptEntry>, RunEngineError>

---

RunEngineShutdown

Optional host-owned shutdown latch, provided before building an engine runtime. Completing it closes Attempt admission even while startup recovery is running. After startup, RunEngine.drain waits for admitted Attempts to persist their outcomes. Allocate a fresh latch for each runtime; it cannot be reopened (ADR 0023).

Extends

• Context.ServiceClass

Properties

Service

readonly Service: Deferred.Deferred<void, never>

The service’s operations: what yield* RunEngineShutdown returns.

---

RunInterventionRejectedError

The requested Attempt is no longer live, or its channel could not accept operator input.

Extends

• Schema.Class

Constructors

Constructor

new RunInterventionRejectedError(…args): RunInterventionRejectedError

Parameters

Parameter	Type
…args	[props: object, options?: MakeOptions]

Returns

RunInterventionRejectedError

Properties

attemptId

readonly attemptId: string & Brand<"AttemptId">

message

readonly message: string

runId

readonly runId: string & Brand<"RunId">

---

RunNotFoundError

No Run with the requested identity exists in this instance’s records.

Extends

• Schema.Class

Constructors

Constructor

new RunNotFoundError(…args): RunNotFoundError

Parameters

Parameter	Type
…args	[props: object, options?: MakeOptions]

Returns

RunNotFoundError

Properties

runId

readonly runId: string & Brand<"RunId">

---

RunOperationRejectedError

The Run’s current state does not allow the requested operator action.

Extends

• Schema.Class

Constructors

Constructor

new RunOperationRejectedError(…args): RunOperationRejectedError

Parameters

Parameter	Type
…args	[props: object, options?: MakeOptions]

Returns

RunOperationRejectedError

Properties

operation

readonly operation: "approve" | "retry" | "resolveFailure"

runId

readonly runId: string & Brand<"RunId">

state

readonly state: string

---

Submission

A matched Event with the Loop, Item, and execution choices that determine the work owed.

Extends

• Schema.Class

Constructors

Constructor

new Submission(…args): Submission

Parameters

Parameter	Type
…args	[props: object, options?: MakeOptions]

Returns

Submission

Properties

agent

readonly agent: Agent

approval

readonly approval: "required" | "none"

cycleGeneration

readonly cycleGeneration: number & Brand<"CycleGeneration">

Capture before fetching trigger input. A reset supersedes older observations.

cycleLimit

readonly cycleLimit: Option<number & Brand<"CycleLimit">>

Item Runs default to three rounds; schedule adapters explicitly supply None.

event

readonly event: Event

itemKey

readonly itemKey: string & Brand<"ItemKey">

loop

readonly loop: string & Brand<"LoopName">

parentModel

readonly parentModel: Option<string & Brand<"ModelId">>

repository

readonly repository: string & Brand<"RepositoryName">

revision

readonly revision: string & Brand<"RepositoryRevision">

step

readonly step: string & Brand<"StepName">

task

readonly task: string & Brand<"AttemptTask">

Type Aliases

IgnoreReason

IgnoreReason = typeof IgnoreReason.Type

---

RunEngineError

RunEngineError = typeof RunEngineError.Type

The store’s failures plus the cancellation handshake failure only the engine raises.

---

RunStoreError

RunStoreError = typeof RunStoreError.Type

Everything the store itself can fail with.

---

SubmissionResult

SubmissionResult = typeof SubmissionResult.Type

Whether a recorded Event owns a Run, waits behind running work, or can no longer open a Run.

Variables

IgnoreReason

const IgnoreReason: Schema.Literals<readonly ["superseded", "revoked"]>

---

layerWithDatabase

const layerWithDatabase: <DatabaseError, DatabaseRequirements>(database) => Layer.Layer<CursorStore | CycleBudgets | ItemProjectionReader | ItemProjectionWriter | LoopControl | RepositoryLabelProjectionReader | RepositoryLabelProjectionWriter | RunEngine | RunReader, RunEngineError | DatabaseError, Crypto.Crypto | StepExecutor | TriggerCondition | DatabaseRequirements>

Provides Run execution and recovery on the supplied database, whose run tables are the only durable state of the Run lifecycle. The deployment supplies Crypto, which hashes dedup keys into Run ids, the Worker implementation through StepExecutor, and the trigger re-check for queued Events through TriggerCondition.

Type Parameters

Type Parameter
DatabaseError
DatabaseRequirements

Parameters

Parameter	Type
database	Layer.Layer<RunDatabase, DatabaseError, DatabaseRequirements>

Returns

Layer.Layer<CursorStore | CycleBudgets | ItemProjectionReader | ItemProjectionWriter | LoopControl | RepositoryLabelProjectionReader | RepositoryLabelProjectionWriter | RunEngine | RunReader, RunEngineError | DatabaseError, Crypto.Crypto | StepExecutor | TriggerCondition | DatabaseRequirements>

---

ReconcileInterval

const ReconcileInterval: Context.Reference<Duration.Input>

How long the engine waits between reconciles after the one at startup, so an open Run whose fiber stopped, as on a store failure that outlasted its retries, is driven again without a restart. Provide another value to change it.

---

RunEngineError

const RunEngineError: Schema.Union<readonly [typeof RunNotFoundError, typeof RunOperationRejectedError, typeof EnginePersistenceError, typeof AttemptCancellationError, typeof RunInterventionRejectedError]>

The store’s failures plus the cancellation handshake failure only the engine raises.

---

RunStoreError

const RunStoreError: Schema.Union<readonly [typeof RunNotFoundError, typeof RunOperationRejectedError, typeof EnginePersistenceError]>

Everything the store itself can fail with.

---

SubmissionResult

const SubmissionResult: Schema.Union<readonly [typeof Claimed, typeof Queued, typeof Ignored, typeof CycleBlocked]>

Whether a recorded Event owns a Run, waits behind running work, or can no longer open a Run.