@usine/durable/harness

Classes

DurableHarness

The orchestrator’s pi-durable Harness over one storage. A commit that fails after storage admission poisons the whole Session; the harness detects it, closes the Session, opens the storage again, and resumes its tasks. A step pi-durable keeps retrying without progress is handled the same way, and stops the harness for good when the reopened harness gets stuck again.

Extends

• Context.ServiceClass

Properties

Service

readonly Service: object

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

defaultModel

readonly defaultModel: Option.Option<ModelRef>

install

readonly install: (extension) => Effect.Effect<void>

Installs or replaces an extension; conversations that select it by name use the new code from their next phase.

Parameters

Parameter	Type
extension	Extension

Returns

Effect.Effect<void>

models

readonly models: Models

resume

readonly resume: (beforeResume) => Effect.Effect<void, DurableHarnessError>

Runs beforeResume on the open harness, then starts the task scheduler; every reopen does both again. Call it once every extension is installed: a generation resumed earlier would be prepared without the tools its conversation selects.

Parameters

Parameter	Type
beforeResume	BeforeResume

Returns

Effect.Effect<void, DurableHarnessError>

subscribe

readonly subscribe: (listener) => Effect.Effect<void, never, Scope.Scope>

Observes commits, reopens, and the stop while the scope is open.

Parameters

Parameter	Type
listener	HarnessListener

Returns

Effect.Effect<void, never, Scope.Scope>

use

readonly use: <A>(operation, run) => Effect.Effect<A, DurableHarnessError>

Runs one call against the open harness. A call that fails because the Session was poisoned or replaced runs once more on the reopened harness, so it must be safe to repeat. Once the harness has stopped, every call fails with the reason it stopped.

Type Parameters

Type Parameter
A

Parameters

Parameter	Type
operation	string
run	(harness, context) => Promise<A>

Returns

Effect.Effect<A, DurableHarnessError>

---

DurableHarnessError

A pi-durable call failed: the harness could not open, commit, read, or wait.

Extends

• Schema.Class

Constructors

Constructor

new DurableHarnessError(…args): DurableHarnessError

Parameters

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

Returns

DurableHarnessError

Properties

cause

readonly cause: unknown

message

readonly message: string

operation

readonly operation: string

Interfaces

DurableHarnessOptions

What the harness runs on.

Properties

defaultModel

readonly defaultModel: Option<ModelRef>

The parent model when an Attempt names none; absent means the first model with a configured credential.

models

readonly models: Models

pi-ai model access for generation and parent model resolution.

openStorage

readonly openStorage: Effect<Storage, DurableHarnessError>

Opens the storage; run again to reopen after a poisoned or stuck Session.

---

HarnessListener

Observes the open harness, across reopens.

Properties

onCommit

readonly onCommit: (publication) => void

Runs synchronously after every adopted commit; it must not block, throw, or call the harness.

Parameters

Parameter	Type
publication	CommitPublication

Returns

void

onReopen

readonly onReopen: () => void

Runs once a poisoned or stuck Session has been replaced by a freshly opened and resumed harness.

Returns

void

onStop

readonly onStop: () => void

Runs once the harness has stopped for good; every later call fails with the reason.

Returns

void

Type Aliases

BeforeResume

BeforeResume = (harness) => Effect.Effect<void>

Repairs storage through a freshly opened harness before its tasks run; it logs its own failures and never fails.

Parameters

Parameter	Type
harness	Harness

Returns

Effect.Effect<void>

Variables

durableError

const durableError: (operation, cause) => DurableHarnessError

Wraps a failed pi-durable call, naming what it was doing.

Parameters

Parameter	Type
operation	string
cause	unknown

Returns

DurableHarnessError

---

layer

const layer: (options) => Layer.Layer<DurableHarness, DurableHarnessError>

Opens the harness for the layer’s lifetime; it is closed, without writing any task outcome, when the layer ends.

Parameters

Parameter	Type
options	DurableHarnessOptions

Returns

Layer.Layer<DurableHarness, DurableHarnessError>

---

StuckStepReports

const StuckStepReports: Context.Reference<number>

How many reports of one failure, with no commit adopted between them, mean pi-durable keeps retrying a step that cannot succeed. Its scheduler retries such a step at once, in microtasks, so until the harness closes the process runs no timer and no I/O. Provide another value to change it.