effect-machine 0.6.0 → 0.7.1

package/dist-v3/persistence/persistent-actor.d.ts

@@ -0,0 +1,49 @@
+import { PersistentMachine } from "./persistent-machine.js";
+import { EffectsDef, GuardsDef } from "../slot.js";
+import { PersistedEvent, PersistenceError, Snapshot, VersionConflictError } from "./adapter.js";
+import { ActorRef } from "../actor.js";
+import { Effect, Option } from "effect";
+
+//#region src-v3/persistence/persistent-actor.d.ts
+/**
+ * Extended ActorRef with persistence capabilities
+ */
+interface PersistentActorRef<S extends {
+  readonly _tag: string;
+}, E extends {
+  readonly _tag: string;
+}, R = never> extends ActorRef<S, E> {
+  /**
+   * Force an immediate snapshot save
+   */
+  readonly persist: Effect.Effect<void, PersistenceError | VersionConflictError>;
+  /**
+   * Get the current persistence version
+   */
+  readonly version: Effect.Effect<number>;
+  /**
+   * Replay events to restore actor to a specific version.
+   * Note: This only computes state; does not re-run transition effects.
+   */
+  readonly replayTo: (version: number) => Effect.Effect<void, PersistenceError, R>;
+}
+/**
+ * Create a persistent actor from a PersistentMachine.
+ * Restores from existing snapshot if available, otherwise starts fresh.
+ */
+declare const createPersistentActor: <S extends {
+  readonly _tag: string;
+}, E extends {
+  readonly _tag: string;
+}, R, GD extends GuardsDef = Record<string, never>, EFD extends EffectsDef = Record<string, never>>(id: string, persistentMachine: PersistentMachine<S, E, R>, initialSnapshot: Option.Option<Snapshot<S>>, initialEvents: readonly PersistedEvent<E>[]) => Effect.Effect<PersistentActorRef<S, E, R>, unknown, unknown>;
+/**
+ * Restore an actor from persistence.
+ * Returns None if no persisted state exists.
+ */
+declare const restorePersistentActor: <S extends {
+  readonly _tag: string;
+}, E extends {
+  readonly _tag: string;
+}, R>(id: string, persistentMachine: PersistentMachine<S, E, R>) => Effect.Effect<Option.None<PersistentActorRef<S, E, R>> | Option.Some<PersistentActorRef<S, E, R>>, unknown, unknown>;
+//#endregion
+export { PersistentActorRef, createPersistentActor, restorePersistentActor };

package/dist-v3/persistence/persistent-actor.js

@@ -0,0 +1,367 @@
+import { Inspector } from "../inspection.js";
+import { INTERNAL_INIT_EVENT, stubSystem } from "../internal/utils.js";
+import { processEventCore, resolveTransition, runSpawnEffects, runTransitionHandler } from "../internal/transition.js";
+import { emitWithTimestamp } from "../internal/inspection.js";
+import { PersistenceAdapterTag } from "./adapter.js";
+import { ActorSystem, buildActorRefCore, notifyListeners } from "../actor.js";
+import { Cause, Clock, Effect, Exit, Fiber, Option, Queue, Ref, Schedule, Scope, SubscriptionRef } from "effect";
+
+//#region src-v3/persistence/persistent-actor.ts
+/** Get current time in milliseconds using Effect Clock */
+const now = Clock.currentTimeMillis;
+/**
+* Replay persisted events to compute state.
+* Supports async handlers - used for initial restore.
+* @internal
+*/
+const replayEvents = Effect.fn("effect-machine.persistentActor.replayEvents")(function* (machine, startState, events, self, stopVersion) {
+	let state = startState;
+	let version = 0;
+	for (const persistedEvent of events) {
+		if (stopVersion !== void 0 && persistedEvent.version > stopVersion) break;
+		const transition = resolveTransition(machine, state, persistedEvent.event);
+		if (transition !== void 0) state = yield* runTransitionHandler(machine, transition, state, persistedEvent.event, self, stubSystem);
+		version = persistedEvent.version;
+	}
+	return {
+		state,
+		version
+	};
+});
+/**
+* Build PersistentActorRef with all methods
+*/
+const buildPersistentActorRef = (id, persistentMachine, stateRef, versionRef, eventQueue, stoppedRef, listeners, stop, adapter, system, childrenMap) => {
+	const { machine, persistence } = persistentMachine;
+	const typedMachine = machine;
+	const persist = Effect.gen(function* () {
+		const snapshot = {
+			state: yield* SubscriptionRef.get(stateRef),
+			version: yield* Ref.get(versionRef),
+			timestamp: yield* now
+		};
+		yield* adapter.saveSnapshot(id, snapshot, persistence.stateSchema);
+	}).pipe(Effect.withSpan("effect-machine.persistentActor.persist"));
+	const version = Ref.get(versionRef).pipe(Effect.withSpan("effect-machine.persistentActor.version"));
+	const replayTo = Effect.fn("effect-machine.persistentActor.replayTo")(function* (targetVersion) {
+		if (targetVersion <= (yield* Ref.get(versionRef))) {
+			const dummySelf = {
+				send: Effect.fn("effect-machine.persistentActor.replay.send")((_event) => Effect.void),
+				spawn: () => Effect.die("spawn not supported in replay")
+			};
+			const maybeSnapshot = yield* adapter.loadSnapshot(id, persistence.stateSchema);
+			if (Option.isSome(maybeSnapshot)) {
+				const snapshot = maybeSnapshot.value;
+				if (snapshot.version <= targetVersion) {
+					const events = yield* adapter.loadEvents(id, persistence.eventSchema, snapshot.version);
+					const result = yield* replayEvents(typedMachine, snapshot.state, events, dummySelf, targetVersion);
+					yield* SubscriptionRef.set(stateRef, result.state);
+					yield* Ref.set(versionRef, result.version);
+					notifyListeners(listeners, result.state);
+				}
+			} else {
+				const events = yield* adapter.loadEvents(id, persistence.eventSchema);
+				if (events.length > 0) {
+					const result = yield* replayEvents(typedMachine, typedMachine.initial, events, dummySelf, targetVersion);
+					yield* SubscriptionRef.set(stateRef, result.state);
+					yield* Ref.set(versionRef, result.version);
+					notifyListeners(listeners, result.state);
+				}
+			}
+		}
+	});
+	return {
+		...buildActorRefCore(id, typedMachine, stateRef, eventQueue, stoppedRef, listeners, stop, system, childrenMap),
+		persist,
+		version,
+		replayTo
+	};
+};
+/**
+* Create a persistent actor from a PersistentMachine.
+* Restores from existing snapshot if available, otherwise starts fresh.
+*/
+const createPersistentActor = Effect.fn("effect-machine.persistentActor.spawn")(function* (id, persistentMachine, initialSnapshot, initialEvents) {
+	yield* Effect.annotateCurrentSpan("effect_machine.actor.id", id);
+	const adapter = yield* PersistenceAdapterTag;
+	const { machine, persistence } = persistentMachine;
+	const typedMachine = machine;
+	const existingSystem = yield* Effect.serviceOption(ActorSystem);
+	if (Option.isNone(existingSystem)) return yield* Effect.die("PersistentActor requires ActorSystem in context");
+	const system = existingSystem.value;
+	const inspector = Option.getOrUndefined(yield* Effect.serviceOption(Inspector));
+	const eventQueue = yield* Queue.unbounded();
+	const stoppedRef = yield* Ref.make(false);
+	const childrenMap = /* @__PURE__ */ new Map();
+	const self = {
+		send: Effect.fn("effect-machine.persistentActor.self.send")(function* (event) {
+			if (yield* Ref.get(stoppedRef)) return;
+			yield* Queue.offer(eventQueue, event);
+		}),
+		spawn: (childId, childMachine) => Effect.gen(function* () {
+			const child = yield* system.spawn(childId, childMachine).pipe(Effect.provideService(ActorSystem, system));
+			childrenMap.set(childId, child);
+			const maybeScope = yield* Effect.serviceOption(Scope.Scope);
+			if (Option.isSome(maybeScope)) yield* Scope.addFinalizer(maybeScope.value, Effect.sync(() => {
+				childrenMap.delete(childId);
+			}));
+			return child;
+		})
+	};
+	let resolvedInitial;
+	let initialVersion;
+	if (Option.isSome(initialSnapshot)) {
+		const result = yield* replayEvents(typedMachine, initialSnapshot.value.state, initialEvents, self);
+		resolvedInitial = result.state;
+		initialVersion = initialEvents.length > 0 ? result.version : initialSnapshot.value.version;
+	} else if (initialEvents.length > 0) {
+		const result = yield* replayEvents(typedMachine, typedMachine.initial, initialEvents, self);
+		resolvedInitial = result.state;
+		initialVersion = result.version;
+	} else {
+		resolvedInitial = typedMachine.initial;
+		initialVersion = 0;
+	}
+	yield* Effect.annotateCurrentSpan("effect_machine.actor.initial_state", resolvedInitial._tag);
+	const stateRef = yield* SubscriptionRef.make(resolvedInitial);
+	const versionRef = yield* Ref.make(initialVersion);
+	const listeners = /* @__PURE__ */ new Set();
+	let createdAt;
+	if (Option.isSome(initialSnapshot)) {
+		const existingMeta = adapter.loadMetadata !== void 0 ? yield* adapter.loadMetadata(id) : Option.none();
+		createdAt = Option.isSome(existingMeta) ? existingMeta.value.createdAt : initialSnapshot.value.timestamp;
+	} else createdAt = yield* now;
+	yield* emitWithTimestamp(inspector, (timestamp) => ({
+		type: "@machine.spawn",
+		actorId: id,
+		initialState: resolvedInitial,
+		timestamp
+	}));
+	const snapshotEnabledRef = yield* Ref.make(true);
+	const persistenceQueue = yield* Queue.unbounded();
+	const persistenceFiber = yield* Effect.forkDaemon(persistenceWorker(persistenceQueue));
+	yield* Queue.offer(persistenceQueue, saveMetadata(id, resolvedInitial, initialVersion, createdAt, persistence, adapter));
+	const snapshotQueue = yield* Queue.unbounded();
+	const snapshotFiber = yield* Effect.forkDaemon(snapshotWorker(id, persistence, adapter, snapshotQueue, snapshotEnabledRef));
+	const backgroundFibers = [];
+	const initEvent = { _tag: INTERNAL_INIT_EVENT };
+	const initCtx = {
+		state: resolvedInitial,
+		event: initEvent,
+		self,
+		system
+	};
+	const { effects: effectSlots } = typedMachine._slots;
+	for (const bg of typedMachine.backgroundEffects) {
+		const fiber = yield* Effect.forkDaemon(bg.handler({
+			state: resolvedInitial,
+			event: initEvent,
+			self,
+			effects: effectSlots,
+			system
+		}).pipe(Effect.provideService(typedMachine.Context, initCtx)));
+		backgroundFibers.push(fiber);
+	}
+	const stateScopeRef = { current: yield* Scope.make() };
+	yield* runSpawnEffectsWithInspection(typedMachine, resolvedInitial, initEvent, self, stateScopeRef.current, id, inspector, system);
+	if (typedMachine.finalStates.has(resolvedInitial._tag)) {
+		yield* Scope.close(stateScopeRef.current, Exit.void);
+		yield* Effect.all(backgroundFibers.map(Fiber.interrupt), { concurrency: "unbounded" });
+		yield* Fiber.interrupt(snapshotFiber);
+		yield* Fiber.interrupt(persistenceFiber);
+		yield* Ref.set(stoppedRef, true);
+		yield* emitWithTimestamp(inspector, (timestamp) => ({
+			type: "@machine.stop",
+			actorId: id,
+			finalState: resolvedInitial,
+			timestamp
+		}));
+		return buildPersistentActorRef(id, persistentMachine, stateRef, versionRef, eventQueue, stoppedRef, listeners, Ref.set(stoppedRef, true).pipe(Effect.withSpan("effect-machine.persistentActor.stop"), Effect.asVoid), adapter, system, childrenMap);
+	}
+	const loopFiber = yield* Effect.forkDaemon(persistentEventLoop(id, persistentMachine, stateRef, versionRef, eventQueue, stoppedRef, self, listeners, adapter, createdAt, stateScopeRef, backgroundFibers, snapshotQueue, snapshotEnabledRef, persistenceQueue, snapshotFiber, persistenceFiber, inspector, system));
+	return buildPersistentActorRef(id, persistentMachine, stateRef, versionRef, eventQueue, stoppedRef, listeners, Effect.gen(function* () {
+		const finalState = yield* SubscriptionRef.get(stateRef);
+		yield* emitWithTimestamp(inspector, (timestamp) => ({
+			type: "@machine.stop",
+			actorId: id,
+			finalState,
+			timestamp
+		}));
+		yield* Ref.set(stoppedRef, true);
+		yield* Fiber.interrupt(loopFiber);
+		yield* Scope.close(stateScopeRef.current, Exit.void);
+		yield* Effect.all(backgroundFibers.map(Fiber.interrupt), { concurrency: "unbounded" });
+		yield* Fiber.interrupt(snapshotFiber);
+		yield* Fiber.interrupt(persistenceFiber);
+	}).pipe(Effect.withSpan("effect-machine.persistentActor.stop"), Effect.asVoid), adapter, system, childrenMap);
+});
+/**
+* Main event loop for persistent actor
+*/
+const persistentEventLoop = Effect.fn("effect-machine.persistentActor.eventLoop")(function* (id, persistentMachine, stateRef, versionRef, eventQueue, stoppedRef, self, listeners, adapter, createdAt, stateScopeRef, backgroundFibers, snapshotQueue, snapshotEnabledRef, persistenceQueue, snapshotFiber, persistenceFiber, inspector, system) {
+	const { machine, persistence } = persistentMachine;
+	const typedMachine = machine;
+	const hooks = inspector === void 0 ? void 0 : {
+		onSpawnEffect: (state) => emitWithTimestamp(inspector, (timestamp) => ({
+			type: "@machine.effect",
+			actorId: id,
+			effectType: "spawn",
+			state,
+			timestamp
+		})),
+		onTransition: (from, to, ev) => emitWithTimestamp(inspector, (timestamp) => ({
+			type: "@machine.transition",
+			actorId: id,
+			fromState: from,
+			toState: to,
+			event: ev,
+			timestamp
+		})),
+		onError: (info) => emitWithTimestamp(inspector, (timestamp) => ({
+			type: "@machine.error",
+			actorId: id,
+			phase: info.phase,
+			state: info.state,
+			event: info.event,
+			error: Cause.pretty(info.cause),
+			timestamp
+		}))
+	};
+	while (true) {
+		const event = yield* Queue.take(eventQueue);
+		const currentState = yield* SubscriptionRef.get(stateRef);
+		const currentVersion = yield* Ref.get(versionRef);
+		yield* emitWithTimestamp(inspector, (timestamp) => ({
+			type: "@machine.event",
+			actorId: id,
+			state: currentState,
+			event,
+			timestamp
+		}));
+		const result = yield* processEventCore(typedMachine, currentState, event, self, stateScopeRef, system, hooks);
+		if (!result.transitioned) continue;
+		const newVersion = currentVersion + 1;
+		yield* Ref.set(versionRef, newVersion);
+		yield* SubscriptionRef.set(stateRef, result.newState);
+		notifyListeners(listeners, result.newState);
+		if (persistence.journalEvents) {
+			const persistedEvent = {
+				event,
+				version: newVersion,
+				timestamp: yield* now
+			};
+			const journalTask = adapter.appendEvent(id, persistedEvent, persistence.eventSchema).pipe(Effect.catchAll((e) => Effect.logWarning(`Failed to journal event for actor ${id}`, e)), Effect.asVoid);
+			yield* Queue.offer(persistenceQueue, journalTask);
+		}
+		yield* Queue.offer(persistenceQueue, saveMetadata(id, result.newState, newVersion, createdAt, persistence, adapter));
+		if (yield* Ref.get(snapshotEnabledRef)) yield* Queue.offer(snapshotQueue, {
+			state: result.newState,
+			version: newVersion
+		});
+		if (result.lifecycleRan && result.isFinal) {
+			yield* emitWithTimestamp(inspector, (timestamp) => ({
+				type: "@machine.stop",
+				actorId: id,
+				finalState: result.newState,
+				timestamp
+			}));
+			yield* Ref.set(stoppedRef, true);
+			yield* Scope.close(stateScopeRef.current, Exit.void);
+			yield* Effect.all(backgroundFibers.map(Fiber.interrupt), { concurrency: "unbounded" });
+			yield* Fiber.interrupt(snapshotFiber);
+			yield* Fiber.interrupt(persistenceFiber);
+			return;
+		}
+	}
+});
+/**
+* Run spawn effects with inspection and tracing.
+* @internal
+*/
+const runSpawnEffectsWithInspection = Effect.fn("effect-machine.persistentActor.spawnEffects")(function* (machine, state, event, self, stateScope, actorId, inspector, system) {
+	yield* emitWithTimestamp(inspector, (timestamp) => ({
+		type: "@machine.effect",
+		actorId,
+		effectType: "spawn",
+		state,
+		timestamp
+	}));
+	yield* runSpawnEffects(machine, state, event, self, stateScope, system, inspector === void 0 ? void 0 : (info) => emitWithTimestamp(inspector, (timestamp) => ({
+		type: "@machine.error",
+		actorId,
+		phase: info.phase,
+		state: info.state,
+		event: info.event,
+		error: Cause.pretty(info.cause),
+		timestamp
+	})));
+});
+/**
+* Persistence worker (journaling + metadata).
+*/
+const persistenceWorker = Effect.fn("effect-machine.persistentActor.persistenceWorker")(function* (queue) {
+	while (true) yield* yield* Queue.take(queue);
+});
+/**
+* Snapshot scheduler worker (runs in background).
+*/
+const snapshotWorker = Effect.fn("effect-machine.persistentActor.snapshotWorker")(function* (id, persistence, adapter, queue, enabledRef) {
+	const driver = yield* Schedule.driver(persistence.snapshotSchedule);
+	while (true) {
+		const { state, version } = yield* Queue.take(queue);
+		if (!(yield* Ref.get(enabledRef))) continue;
+		if (!(yield* driver.next(state).pipe(Effect.match({
+			onFailure: () => false,
+			onSuccess: () => true
+		})))) {
+			yield* Ref.set(enabledRef, false);
+			continue;
+		}
+		yield* saveSnapshot(id, state, version, persistence, adapter);
+	}
+});
+/**
+* Save a snapshot after state transition.
+* Called by snapshot scheduler.
+*/
+const saveSnapshot = Effect.fn("effect-machine.persistentActor.saveSnapshot")(function* (id, state, version, persistence, adapter) {
+	const snapshot = {
+		state,
+		version,
+		timestamp: yield* now
+	};
+	yield* adapter.saveSnapshot(id, snapshot, persistence.stateSchema).pipe(Effect.catchAll((e) => Effect.logWarning(`Failed to save snapshot for actor ${id}`, e)));
+});
+/**
+* Save or update actor metadata if adapter supports registry.
+* Called on spawn and state transitions.
+*/
+const saveMetadata = Effect.fn("effect-machine.persistentActor.saveMetadata")(function* (id, state, version, createdAt, persistence, adapter) {
+	const save = adapter.saveMetadata;
+	if (save === void 0) return;
+	const lastActivityAt = yield* now;
+	yield* save({
+		id,
+		machineType: persistence.machineType ?? "unknown",
+		createdAt,
+		lastActivityAt,
+		version,
+		stateTag: state._tag
+	}).pipe(Effect.catchAll((e) => Effect.logWarning(`Failed to save metadata for actor ${id}`, e)));
+});
+/**
+* Restore an actor from persistence.
+* Returns None if no persisted state exists.
+*/
+const restorePersistentActor = Effect.fn("effect-machine.persistentActor.restore")(function* (id, persistentMachine) {
+	const adapter = yield* PersistenceAdapterTag;
+	const { persistence } = persistentMachine;
+	const maybeSnapshot = yield* adapter.loadSnapshot(id, persistence.stateSchema);
+	const events = yield* adapter.loadEvents(id, persistence.eventSchema, Option.isSome(maybeSnapshot) ? maybeSnapshot.value.version : void 0);
+	if (Option.isNone(maybeSnapshot) && events.length === 0) return Option.none();
+	const actor = yield* createPersistentActor(id, persistentMachine, maybeSnapshot, events);
+	return Option.some(actor);
+});
+
+//#endregion
+export { createPersistentActor, restorePersistentActor };

package/dist-v3/persistence/persistent-machine.d.ts

@@ -0,0 +1,105 @@
+import { EventBrand, StateBrand } from "../internal/brands.js";
+import { Machine } from "../machine.js";
+import { Schedule, Schema } from "effect";
+
+//#region src-v3/persistence/persistent-machine.d.ts
+type BrandedState = {
+  readonly _tag: string;
+} & StateBrand;
+type BrandedEvent = {
+  readonly _tag: string;
+} & EventBrand;
+/**
+ * Configuration for persistence behavior (after resolution).
+ * Schemas are required at runtime - the persist function ensures this.
+ *
+ * Note: Schema types S and E should match the structural shape of the machine's
+ * state and event types (without brands). The schemas don't know about brands.
+ */
+interface PersistenceConfig<S, E, SSI = unknown, ESI = unknown> {
+  /**
+   * Schedule controlling when snapshots are taken.
+   * Input is the new state after each transition.
+   *
+   * Examples:
+   * - Schedule.forever — snapshot every transition
+   * - Schedule.spaced("5 seconds") — debounced snapshots
+   * - Schedule.recurs(100) — every N transitions
+   */
+  readonly snapshotSchedule: Schedule.Schedule<unknown, S>;
+  /**
+   * Whether to journal events for replay capability.
+   * When true, all events are appended to the event log.
+   */
+  readonly journalEvents: boolean;
+  /**
+   * Schema for serializing/deserializing state.
+   * Always present at runtime (resolved from config or machine).
+   */
+  readonly stateSchema: Schema.Schema<S, SSI, never>;
+  /**
+   * Schema for serializing/deserializing events.
+   * Always present at runtime (resolved from config or machine).
+   */
+  readonly eventSchema: Schema.Schema<E, ESI, never>;
+  /**
+   * User-provided identifier for the machine type.
+   * Used for filtering actors in restoreAll.
+   * Optional — defaults to "unknown" if not provided.
+   */
+  readonly machineType?: string;
+}
+/**
+ * Machine with persistence configuration attached.
+ * Spawn auto-detects this and returns PersistentActorRef.
+ */
+interface PersistentMachine<S extends {
+  readonly _tag: string;
+}, E extends {
+  readonly _tag: string;
+}, R = never> {
+  readonly _tag: "PersistentMachine";
+  readonly machine: Machine<S, E, R>;
+  readonly persistence: PersistenceConfig<S, E>;
+}
+/**
+ * Type guard to check if a value is a PersistentMachine
+ */
+declare const isPersistentMachine: (value: unknown) => value is PersistentMachine<{
+  readonly _tag: string;
+}, {
+  readonly _tag: string;
+}, unknown>;
+/**
+ * Attach persistence configuration to a machine.
+ *
+ * Schemas are read from the machine - must use `Machine.make({ state, event, initial })`.
+ *
+ * @example
+ * ```ts
+ * const orderMachine = Machine.make({
+ *   state: OrderState,
+ *   event: OrderEvent,
+ *   initial: OrderState.Idle(),
+ * }).pipe(
+ *   Machine.on(OrderState.Idle, OrderEvent.Submit, ({ event }) =>
+ *     OrderState.Pending({ orderId: event.orderId })
+ *   ),
+ *   Machine.final(OrderState.Paid),
+ *   Machine.persist({
+ *     snapshotSchedule: Schedule.forever,
+ *     journalEvents: true,
+ *   }),
+ * );
+ * ```
+ */
+interface WithPersistenceConfig {
+  readonly snapshotSchedule: Schedule.Schedule<unknown, {
+    readonly _tag: string;
+  }>;
+  readonly journalEvents: boolean;
+  readonly machineType?: string;
+}
+declare const persist: (config: WithPersistenceConfig) => <S extends BrandedState, E extends BrandedEvent, R>(machine: Machine<S, E, R>) => PersistentMachine<S, E, R>;
+//#endregion
+export { PersistenceConfig, PersistentMachine, WithPersistenceConfig, isPersistentMachine, persist };

package/dist-v3/persistence/persistent-machine.js

@@ -0,0 +1,24 @@
+import { MissingSchemaError } from "../errors.js";
+
+//#region src-v3/persistence/persistent-machine.ts
+/**
+* Type guard to check if a value is a PersistentMachine
+*/
+const isPersistentMachine = (value) => typeof value === "object" && value !== null && "_tag" in value && value._tag === "PersistentMachine";
+const persist = (config) => (machine) => {
+	const stateSchema = machine.stateSchema;
+	const eventSchema = machine.eventSchema;
+	if (stateSchema === void 0 || eventSchema === void 0) throw new MissingSchemaError({ operation: "persist" });
+	return {
+		_tag: "PersistentMachine",
+		machine,
+		persistence: {
+			...config,
+			stateSchema,
+			eventSchema
+		}
+	};
+};
+
+//#endregion
+export { isPersistentMachine, persist };

package/dist-v3/schema.d.ts

@@ -0,0 +1,141 @@
+import { FullEventBrand, FullStateBrand } from "./internal/brands.js";
+import { Schema } from "effect";
+
+//#region src-v3/schema.d.ts
+/**
+ * Extract the TypeScript type from a TaggedStruct schema
+ */
+type TaggedStructType<Tag extends string, Fields extends Schema.Struct.Fields> = Schema.Schema.Type<Schema.TaggedStruct<Tag, Fields>>;
+/**
+ * Build variant schemas type from definition
+ */
+type VariantSchemas<D extends Record<string, Schema.Struct.Fields>> = { readonly [K in keyof D & string]: Schema.TaggedStruct<K, D[K]> };
+/**
+ * Build union type from variant schemas.
+ * Used for constraining fluent method type params.
+ */
+type VariantsUnion<D extends Record<string, Schema.Struct.Fields>> = { [K in keyof D & string]: TaggedStructType<K, D[K]> }[keyof D & string];
+/**
+ * Check if fields are empty (no required properties)
+ */
+type IsEmptyFields<Fields extends Schema.Struct.Fields> = keyof Fields extends never ? true : false;
+/**
+ * Constructor functions for each variant.
+ * Empty structs: plain values with `_tag`: `State.Idle`
+ * Non-empty structs require args: `State.Loading({ url })`
+ *
+ * Each variant also has a `derive` method for constructing from a source object.
+ */
+/**
+ * Constructor functions for each variant.
+ * Empty structs: plain values with `_tag`: `State.Idle`
+ * Non-empty structs require args: `State.Loading({ url })`
+ *
+ * Each variant also has a `derive` method for constructing from a source object.
+ * The source type uses `object` to accept branded state types without index signature issues.
+ */
+type VariantConstructors<D extends Record<string, Schema.Struct.Fields>, Brand> = { readonly [K in keyof D & string]: IsEmptyFields<D[K]> extends true ? TaggedStructType<K, D[K]> & Brand & {
+  readonly derive: (source: object) => TaggedStructType<K, D[K]> & Brand;
+} : ((args: Schema.Struct.Constructor<D[K]>) => TaggedStructType<K, D[K]> & Brand) & {
+  readonly derive: (source: object, partial?: Partial<Schema.Struct.Constructor<D[K]>>) => TaggedStructType<K, D[K]> & Brand;
+  readonly _tag: K;
+} };
+/**
+ * Pattern matching cases type
+ */
+type MatchCases<D extends Record<string, Schema.Struct.Fields>, R> = { readonly [K in keyof D & string]: (value: TaggedStructType<K, D[K]>) => R };
+/**
+ * Base schema interface with pattern matching helpers
+ */
+interface MachineSchemaBase<D extends Record<string, Schema.Struct.Fields>, Brand> {
+  /**
+   * Raw definition record for introspection
+   */
+  readonly _definition: D;
+  /**
+   * Per-variant schemas for fine-grained operations
+   */
+  readonly variants: VariantSchemas<D>;
+  /**
+   * Type guard: `OrderState.$is("Pending")(value)`
+   */
+  readonly $is: <Tag extends keyof D & string>(tag: Tag) => (u: unknown) => u is TaggedStructType<Tag, D[Tag]> & Brand;
+  /**
+   * Pattern matching (curried and uncurried)
+   */
+  readonly $match: {
+    <R>(cases: MatchCases<D, R>): (value: VariantsUnion<D> & Brand) => R;
+    <R>(value: VariantsUnion<D> & Brand, cases: MatchCases<D, R>): R;
+  };
+}
+/**
+ * Schema-first state definition that provides:
+ * - Schema for encode/decode/validate
+ * - Variant constructors: `OrderState.Pending({ orderId: "x" })`
+ * - Pattern matching: `$is`, `$match`
+ * - Type inference: `typeof OrderState.Type`
+ *
+ * The D type parameter captures the definition, creating a unique brand
+ * per distinct schema definition shape.
+ */
+type MachineStateSchema<D extends Record<string, Schema.Struct.Fields>> = Schema.Schema<VariantsUnion<D> & FullStateBrand<D>, VariantsUnion<D>, never> & MachineSchemaBase<D, FullStateBrand<D>> & VariantConstructors<D, FullStateBrand<D>>;
+/**
+ * Schema-first event definition (same structure as state, different brand)
+ *
+ * The D type parameter captures the definition, creating a unique brand
+ * per distinct schema definition shape.
+ */
+type MachineEventSchema<D extends Record<string, Schema.Struct.Fields>> = Schema.Schema<VariantsUnion<D> & FullEventBrand<D>, VariantsUnion<D>, never> & MachineSchemaBase<D, FullEventBrand<D>> & VariantConstructors<D, FullEventBrand<D>>;
+/**
+ * Create a schema-first State definition.
+ *
+ * The schema's definition type D creates a unique brand, preventing
+ * accidental use of constructors from different state schemas
+ * (unless they have identical definitions).
+ *
+ * @example
+ * ```ts
+ * const OrderState = MachineSchema.State({
+ *   Pending: { orderId: Schema.String },
+ *   Shipped: { trackingId: Schema.String },
+ * })
+ *
+ * type OrderState = typeof OrderState.Type
+ *
+ * // Construct
+ * const s = OrderState.Pending({ orderId: "123" })
+ *
+ * // Pattern match
+ * OrderState.$match(s, {
+ *   Pending: (v) => v.orderId,
+ *   Shipped: (v) => v.trackingId,
+ * })
+ *
+ * // Validate
+ * Schema.decodeUnknownSync(OrderState)(rawJson)
+ * ```
+ */
+declare const State: <const D extends Record<string, Schema.Struct.Fields>>(definition: D) => MachineStateSchema<D>;
+/**
+ * Create a schema-first Event definition.
+ *
+ * The schema's definition type D creates a unique brand, preventing
+ * accidental use of constructors from different event schemas
+ * (unless they have identical definitions).
+ *
+ * @example
+ * ```ts
+ * const OrderEvent = MachineSchema.Event({
+ *   Ship: { trackingId: Schema.String },
+ *   Cancel: {},
+ * })
+ *
+ * type OrderEvent = typeof OrderEvent.Type
+ *
+ * // Construct
+ * const e = OrderEvent.Ship({ trackingId: "abc" })
+ * ```
+ */
+declare const Event: <const D extends Record<string, Schema.Struct.Fields>>(definition: D) => MachineEventSchema<D>;
+//#endregion
+export { Event, MachineEventSchema, MachineStateSchema, State, VariantsUnion };