machineInstanceId(value): MachineInstanceId

Defined in: packages/core/src/MachineStore.ts:95

Brands a validated or reconstructed machine instance identity.

When to use

Use at trusted persistence and migration boundaries. New application identities should normally come from deriveMachineInstanceId or a machine definition's instanceId operation.

dispatchId()

dispatchId(value): DispatchId

Defined in: packages/core/src/MachineStore.ts:104

Brands a validated or reconstructed dispatch identity.

entryId()

entryId(value): EntryId

Defined in: packages/core/src/MachineStore.ts:112

Brands a validated or reconstructed entry identity.

executionId()

executionId(value): ExecutionId

Defined in: packages/core/src/MachineStore.ts:120

Brands a validated or reconstructed work execution identity.

revision()

revision(value): Revision

Defined in: packages/core/src/MachineStore.ts:128

Brands a validated aggregate revision.

fence()

fence(value): Fence

Defined in: packages/core/src/MachineStore.ts:136

Brands a validated claim fence.

deriveMachineInstanceId()

deriveMachineInstanceId(definitionId, idempotencyKey): MachineInstanceId

Defined in: packages/core/src/MachineStore.ts:165

Derives a total, versioned machine identity from definition and logical input identity.

Details

Both components use a length-prefixed encoding, so arbitrary Unicode and delimiter-like input remain collision-safe. The same pair always produces the same identity.

deriveEntryId()

deriveEntryId(instanceId, sequence): EntryId

Defined in: packages/core/src/MachineStore.ts:177

Derives a stable entry identity from one machine instance and entry sequence.

deriveChildMachineInstanceId()

deriveChildMachineInstanceId(parentInstanceId, parentEntryId, childName): MachineInstanceId

Defined in: packages/core/src/MachineStore.ts:191

Derives a child runtime identity scoped to its parent instance and owning parent entry.

Details

Re-entering the parent creates a different entry identity and therefore a different child identity, while redelivery within the same entry reconstructs the same child.

deriveExecutionId()

deriveExecutionId(instanceId, entry, ownerPath, invocationName, laneName?): ExecutionId

Defined in: packages/core/src/MachineStore.ts:250

Derives one stable work identity for an invocation lane owned by an entry.

Details

The identity separates instance, entry, owner path, invocation name, and optional lane. It stays stable across retries and redelivery until the owning entry is replaced.

Parameters

documentMetadata()

documentMetadata(checkpoint, input?, children?): Pick<MachineDocument, "definition" | "input" | "status" | "runtime" | "timers" | "executions" | "migration">

Defined in: packages/core/src/MachineStore.ts:570

Derives the canonical aggregate envelopes mirrored from one validated runtime checkpoint.

Engine code uses this constructor so adapters never need to interpret machine state. Nested child records may be supplied when planning a complete runtime-tree replacement.

When to use

Use in engine integrations, migrations, and store fixtures that must rebuild the aggregate envelopes corresponding to a validated checkpoint.

Parameters

checkpoint

status

"running" | "completed" | "defected" = ...

defect

{ category: ... | ... | ... | ... | ... | ...; name: string; message: string; } | null = ...

Returns

makeMemory

const makeMemory: () => Effect.Effect<Service>

Defined in: packages/core/src/MachineStore.ts:767

Creates a process-local store whose state lives for the returned service lifetime.

When to use

Use for isolated tests, examples, and custom Layer composition that deliberately accepts process-local persistence.

Gotchas

Every call creates a new empty database. The service uses Effect's clock, so TestClock can deterministically exercise compare-and-set deadlines.

See

layerMemory for Layer-based provisioning.

decoding

parseChildMachineInstanceId()

parseChildMachineInstanceId(value): ChildMachineIdentity | undefined

Defined in: packages/core/src/MachineStore.ts:223

Parses identities produced by deriveChildMachineInstanceId.

Gotchas

Returns undefined for another identity version, malformed length prefixes, or trailing data. It does not accept arbitrary application-authored strings as child identities.

errors

MachineStoreError

Defined in: packages/core/src/MachineStore.ts:684

Expected failure from a machine-store adapter boundary.

Details

operation identifies the stable service operation and cause retains diagnostic ancestry for adapter, Schema, or serialization failures.

Extends

YieldableError<this> & object & Readonly<{ operation: ...; message: ...; cause?: ...; }>

Constructors

Constructor

new MachineStoreError(args): MachineStoreError

Defined in: node_modules/.pnpm/effect@4.0.0-rc.110/node_modules/effect/dist/Data.d.ts:966

operation

"now" | "load" | "compareAndSet" | "decode" | "encode"

Inherited from

Data.TaggedError("MachineStoreError")<{ readonly operation: "now" | "load" | "compareAndSet" | "decode" | "encode" readonly message: string readonly cause?: unknown }>.constructor

Properties

operation

readonly operation: "now" | "load" | "compareAndSet" | "decode" | "encode"

Defined in: packages/core/src/MachineStore.ts:685

Inherited from

Data.TaggedError("MachineStoreError").operation

cause?

optional cause?: unknown

Defined in: node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es2022.error.d.ts:24

Inherited from

Data.TaggedError("MachineStoreError").cause

message

message: string

Defined in: node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1075

Inherited from

Data.TaggedError("MachineStoreError").message

layers

layerMemory

const layerMemory: Layer.Layer<MachineStore>

Defined in: packages/core/src/MachineStore.ts:823

Layer providing a fresh process-local machine store.

Gotchas

Building the Layer again creates a separate empty database. Share one Layer value across every engine that must load the same machine instances.

See

makeMemory for direct service construction.

models

MachineInstanceId

MachineInstanceId = string & object

Defined in: packages/core/src/MachineStore.ts:32

Stable identity of one logical machine instance.

Type Declaration

[MachineInstanceIdTypeId]

readonly [MachineInstanceIdTypeId]: typeof MachineInstanceIdTypeId

DispatchId

DispatchId = string & object

Defined in: packages/core/src/MachineStore.ts:42

Stable identity of one external dispatch attempt.

Type Declaration

[DispatchIdTypeId]

readonly [DispatchIdTypeId]: typeof DispatchIdTypeId

EntryId

EntryId = string & object

Defined in: packages/core/src/MachineStore.ts:50

Stable identity of one active state entry.

Type Declaration

[EntryIdTypeId]

readonly [EntryIdTypeId]: typeof EntryIdTypeId

ExecutionId

ExecutionId = string & object

Defined in: packages/core/src/MachineStore.ts:63

Stable identity supplied to one entry-owned work execution.

Gotchas

The engine preserves this identity across at-least-once redelivery, but an external system must honor it to make its own side effect idempotent.

Type Declaration

[ExecutionIdTypeId]

readonly [ExecutionIdTypeId]: typeof ExecutionIdTypeId

Revision

Revision = number & object

Defined in: packages/core/src/MachineStore.ts:71

Monotonic aggregate revision used by compare-and-set.

Type Declaration

[RevisionTypeId]

readonly [RevisionTypeId]: typeof RevisionTypeId

Fence

Fence = number & object

Defined in: packages/core/src/MachineStore.ts:79

Monotonic claim fence used to reject stale workers.

Type Declaration

[FenceTypeId]

readonly [FenceTypeId]: typeof FenceTypeId

ChildMachineIdentity

Defined in: packages/core/src/MachineStore.ts:206

Persisted ownership decoded from a derived child-machine identity.

Properties

parentInstanceId

readonly parentInstanceId: MachineInstanceId

Defined in: packages/core/src/MachineStore.ts:207

parentEntryId

readonly parentEntryId: EntryId

Defined in: packages/core/src/MachineStore.ts:208

childName

readonly childName: string

Defined in: packages/core/src/MachineStore.ts:209

PersistedValue

PersistedValue = Json

Defined in: packages/core/src/MachineStore.ts:267

Canonical JSON-compatible value crossing a machine-store boundary.

PersistedTerminalStatus

PersistedTerminalStatus = Schema.Schema.Type<typeof PersistedTerminalStatus>

Defined in: packages/core/src/MachineStore.ts:275

Persisted lifecycle of a root or nested runtime node.

PersistedRuntimeNode

PersistedRuntimeNode = Schema.Schema.Type<typeof PersistedRuntimeNode>

Defined in: packages/core/src/MachineStore.ts:296

Root or nested runtime record stored inside one machine aggregate.

PersistedRuntimeTree

PersistedRuntimeTree = Schema.Schema.Type<typeof PersistedRuntimeTree>

Defined in: packages/core/src/MachineStore.ts:333

Flattened root and nested runtime tree.

PersistedTimer

PersistedTimer = Schema.Schema.Type<typeof PersistedTimer>

Defined in: packages/core/src/MachineStore.ts:351

Persisted entry-owned timer.

Details

dueAtEpochMillis is resolved from store time when entry commits. Resumption compares that same absolute deadline instead of restarting the authored duration.

PersistedExecution

PersistedExecution = Schema.Schema.Type<typeof PersistedExecution>

Defined in: packages/core/src/MachineStore.ts:379

Persisted stable work execution record.

PersistedMigrationState

PersistedMigrationState = Schema.Schema.Type<typeof PersistedMigrationState>

Defined in: packages/core/src/MachineStore.ts:404

Application-version state exposed to a definition migration.

StoredMachineDelivery

StoredMachineDelivery = Schema.Schema.Type<typeof StoredMachineDelivery>

Defined in: packages/core/src/MachineStore.ts:424

Stored machine-mailbox delivery.

StoredActivityDelivery

StoredActivityDelivery = Schema.Schema.Type<typeof StoredActivityDelivery>

Defined in: packages/core/src/MachineStore.ts:447

Stored activity-command delivery.

StoredDispatch

StoredDispatch = Schema.Schema.Type<typeof StoredDispatch>

Defined in: packages/core/src/MachineStore.ts:470

Stored dispatch idempotency record.

MachineDocument

MachineDocument = Schema.Schema.Type<typeof MachineDocument>

Defined in: packages/core/src/MachineStore.ts:527

Complete revisioned aggregate for one root machine instance.

CompareAndSetRequest

Defined in: packages/core/src/MachineStore.ts:623

Expected state and replacement document for one atomic compare-and-set write.

Details

An absent expectedRevision means the aggregate must not exist. notAfter, when present, is an exclusive store-time deadline checked atomically with the revision and replacement.

Properties

instanceId

readonly instanceId: MachineInstanceId

Defined in: packages/core/src/MachineStore.ts:624

expectedRevision

readonly expectedRevision: Revision | undefined

Defined in: packages/core/src/MachineStore.ts:625

document

readonly document: object

Defined in: packages/core/src/MachineStore.ts:626

revision

readonly revision: number = Schema.Number

instanceId

readonly instanceId: string = Schema.String

definition.id

readonly id: string = Schema.String

definition.version

readonly version: string = Schema.String

input

readonly input: Json = Schema.Json

status

readonly status: "running" | "completed" | "defected" | "cancelled" = PersistedTerminalStatus

runtime

readonly runtime: object = PersistedRuntimeTree

runtime.nodes

readonly nodes: readonly object[]

checkpoint

readonly checkpoint: object = Checkpoint

checkpoint.formatVersion

readonly formatVersion: number = Schema.Number

checkpoint.definitionId

readonly definitionId: string = Schema.String

checkpoint.persistenceVersion

readonly persistenceVersion: string = Schema.String

checkpoint.instanceId

readonly instanceId: string = Schema.String

checkpoint.revision

readonly revision: number = Schema.Number

checkpoint.status

readonly status: "running" | "completed" | "defected"

checkpoint.state

readonly state: Json = Schema.Json

checkpoint.rootEntryId

readonly rootEntryId: string = Schema.String

checkpoint.timers

readonly timers: readonly object[]

checkpoint.aggregates

readonly aggregates: readonly object[]

checkpoint.nextSequence

readonly nextSequence: number = Schema.Number

checkpoint.defect

readonly defect: { category: ...; name: ...; message: ...; } | null

messages

readonly messages: readonly object[]

timers

readonly timers: readonly object[]

activities

readonly activities: readonly object[]

dispatches

readonly dispatches: readonly object[]

executions

readonly executions: readonly object[]

migration

readonly migration: object = PersistedMigrationState

migration.definitionId

readonly definitionId: string = Schema.String

migration.persistenceVersion

readonly persistenceVersion: string = Schema.String

migration.state

readonly state: Json = Schema.Json

messageTombstones

readonly messageTombstones: readonly string[]

executionTombstones

readonly executionTombstones: readonly string[]

nestedDocuments

readonly nestedDocuments: readonly Json[]

nextSequence

readonly nextSequence: number = Schema.Number

tree.rootActorId

readonly rootActorId: string = Schema.String

tree.nextSequence

readonly nextSequence: number = Schema.Number

tree.records

readonly records: readonly object[]

notAfter?

readonly optional notAfter?: number

Defined in: packages/core/src/MachineStore.ts:627

Committed

Defined in: packages/core/src/MachineStore.ts:636

Successful compare-and-set result with the store-assigned revision and observation time.

Properties

_tag

readonly _tag: "Committed"

Defined in: packages/core/src/MachineStore.ts:637

revision

readonly revision: Revision

Defined in: packages/core/src/MachineStore.ts:638

observedAt

readonly observedAt: number

Defined in: packages/core/src/MachineStore.ts:639

Conflict

Defined in: packages/core/src/MachineStore.ts:648

Compare-and-set result when another writer changed or created the aggregate.

Properties

_tag

readonly _tag: "Conflict"

Defined in: packages/core/src/MachineStore.ts:649

actualRevision

readonly actualRevision: Revision | undefined

Defined in: packages/core/src/MachineStore.ts:650

observedAt

readonly observedAt: number

Defined in: packages/core/src/MachineStore.ts:651

Expired

Defined in: packages/core/src/MachineStore.ts:660

Compare-and-set result when its exclusive store-time deadline has elapsed.

Properties

_tag

readonly _tag: "Expired"

Defined in: packages/core/src/MachineStore.ts:661

observedAt

readonly observedAt: number

Defined in: packages/core/src/MachineStore.ts:662

CompareAndSetResult

CompareAndSetResult = Committed | Conflict | Expired

Defined in: packages/core/src/MachineStore.ts:671

Result of atomically checking revision, optional deadline, and replacement.

schemas

PersistedTerminalStatus

const PersistedTerminalStatus: Literals<readonly ["running", "completed", "defected", "cancelled"]>

Defined in: packages/core/src/MachineStore.ts:275

Schema for the persisted lifecycle of a root or nested runtime node.

PersistedRuntimeNode

const PersistedRuntimeNode: Struct<{ key: String; actorId: String; definitionPath: String; parentActorId: NullOr<String>; ownerStateTag: NullOr<String>; invocation: NullOr<String>; ownerPath: String; parentEntryId: NullOr<String>; definitionId: String; persistenceVersion: String; input: Codec<Json, Json, never, never>; state: Codec<Json, Json, never, never>; status: Literals<readonly [..., ..., ..., ...]>; rootEntryId: String; regionEntryIds: $Array<Tuple<...>>; }>

Defined in: packages/core/src/MachineStore.ts:296

Schema for one root or child runtime record in the flattened aggregate tree.

PersistedRuntimeTree

const PersistedRuntimeTree: Struct<{ nodes: $Array<Struct<...>>; }>

Defined in: packages/core/src/MachineStore.ts:333

Schema for a flattened runtime tree whose first node is the root record.

Details

The array representation keeps runtime-selected child keys out of prototype-bearing records at the persistence boundary.

PersistedTimer

const PersistedTimer: Struct<{ entryId: String; ownerPath: String; name: String; durationMillis: Number; dueAtEpochMillis: Number; messageId: String; }>

Defined in: packages/core/src/MachineStore.ts:351

Schema for a timer duration and authoritative absolute deadline owned by one entry.

PersistedExecution

const PersistedExecution: Struct<{ id: String; entryId: String; ownerPath: String; invocation: String; lane: String; status: Literals<readonly [..., ..., ..., ...]>; attempt: Number; fence: Number; }>

Defined in: packages/core/src/MachineStore.ts:379

Schema for stable work identity and its latest aggregate delivery state.

PersistedMigrationState

const PersistedMigrationState: Struct<{ definitionId: String; persistenceVersion: String; state: Codec<Json, Json, never, never>; }>

Defined in: packages/core/src/MachineStore.ts:404

Schema for application-version state exposed to a definition migration.

StoredMachineDelivery

const StoredMachineDelivery: Struct<{ value: TaggedUnion<{ External: ...; Timer: ...; ActivityOutcome: ...; RegionsComplete: ...; }>; sequence: Number; status: Literals<readonly [..., ..., ..., ...]>; claim: NullOr<Struct<...>>; attempt: Number; fence: Number; }>

Defined in: packages/core/src/MachineStore.ts:424

Schema for a machine-mailbox delivery and its claim bookkeeping.

StoredActivityDelivery

const StoredActivityDelivery: Struct<{ value: Struct<{ deliveryId: ...; instanceId: ...; executionId: ...; entryId: ...; generation: ...; ownerPath: ...; invocation: ...; lane: ...; state: ...; parentState: ...; concurrencyGroup: ...; concurrencyLimit: ...; }>; sequence: Number; status: Literals<readonly [..., ..., ..., ...]>; claim: NullOr<Struct<...>>; attempt: Number; fence: Number; }>

Defined in: packages/core/src/MachineStore.ts:447

Schema for an activity command and its claim bookkeeping.

StoredDispatch

const StoredDispatch: Struct<{ idempotencyKey: String; record: Struct<{ instanceId: ...; idempotencyKey: ...; payloadFingerprint: ...; status: ...; revision: ...; reason: ...; }>; }>

Defined in: packages/core/src/MachineStore.ts:470

Schema for a caller-keyed dispatch record.

MachineDocument

const MachineDocument: refine<{ formatVersion: 2; revision: number; instanceId: string; definition: { id: string; version: string; }; input: Json; status: "running" | "completed" | "defected" | "cancelled"; runtime: { nodes: readonly ...[]; }; checkpoint: { formatVersion: number; definitionId: string; persistenceVersion: string; instanceId: string; revision: number; status: ... | ... | ...; state: Json; rootEntryId: string; regionEntryIds: {[key: ...]: ...; }; timers: readonly ...[]; aggregates: readonly ...[]; nextSequence: number; defect: ... | ...; }; messages: readonly object[]; timers: readonly object[]; activities: readonly object[]; dispatches: readonly object[]; executions: readonly object[]; migration: { definitionId: string; persistenceVersion: string; state: Json; }; messageTombstones: readonly string[]; executionTombstones: readonly string[]; nestedDocuments: readonly Json[]; nextSequence: number; tree: { rootActorId: string; nextSequence: number; records: readonly ...[]; }; }, Struct<{ formatVersion: Literal<...>; revision: Number; instanceId: String; definition: Struct<...>; input: Codec<..., ..., ..., ...>; status: Literals<...>; runtime: Struct<...>; checkpoint: Struct<...>; messages: $Array<...>; timers: $Array<...>; activities: $Array<...>; dispatches: $Array<...>; executions: $Array<...>; migration: Struct<...>; messageTombstones: $Array<...>; executionTombstones: $Array<...>; nestedDocuments: $Array<...>; nextSequence: Number; tree: Struct<...>; }>>

Defined in: packages/core/src/MachineStore.ts:527

Schema for a complete machine aggregate whose tree journal is internally consistent.

Tree sequences are positional and gapless, record identities are unique, and the journal root is derived from the aggregate instance. These checks keep custom adapters from returning a structurally valid document that would make replay ambiguous.

Since

0.2.0

services

Service

Defined in: packages/core/src/MachineStore.ts:707

Minimal aggregate persistence contract consumed by the machine engine.

Details

The store owns authoritative time, loading by instance identity, and atomic whole-document replacement. Mailbox ordering, claims, timers, work, child machines, and migrations remain engine behavior and must not be reimplemented by adapters.

Gotchas

compareAndSet must check expectedRevision, optional notAfter, and replacement as one atomic operation. A separate time read followed by a write does not safely fence an expired owner.

Since

0.2.0

Properties

now

readonly now: Effect<number, MachineStoreError>

Defined in: packages/core/src/MachineStore.ts:708

load

readonly load: (instanceId) => Effect<Option<{ formatVersion: ...; revision: ...; instanceId: ...; definition: ...; input: ...; status: ...; runtime: ...; checkpoint: ...; messages: ...; timers: ...; activities: ...; dispatches: ...; executions: ...; migration: ...; messageTombstones: ...; executionTombstones: ...; nestedDocuments: ...; nextSequence: ...; tree: ...; }>, MachineStoreError>

Defined in: packages/core/src/MachineStore.ts:709

Parameters

instanceId

MachineInstanceId

Returns

Effect<Option<{ formatVersion: ...; revision: ...; instanceId: ...; definition: ...; input: ...; status: ...; runtime: ...; checkpoint: ...; messages: ...; timers: ...; activities: ...; dispatches: ...; executions: ...; migration: ...; messageTombstones: ...; executionTombstones: ...; nestedDocuments: ...; nextSequence: ...; tree: ...; }>, MachineStoreError>

compareAndSet

readonly compareAndSet: (request) => Effect<CompareAndSetResult, MachineStoreError>

Defined in: packages/core/src/MachineStore.ts:712

When to use

Use as the service tag provided to MachineEngine.layer, either through a bundled adapter or a custom adapter that passes the primitive store conformance corpus.

Shape<"effect-state-machine/MachineStore", Service, this>

Constructors

Constructor

new MachineStore(_): MachineStore

Defined in: node_modules/.pnpm/effect@4.0.0-rc.110/node_modules/effect/dist/Context.d.ts:115

MachineStore API