effect-machine 0.3.0 → 0.3.2

package/dist/persistence/persistent-actor.js

@@ -0,0 +1,348 @@
+import { Inspector } from "../inspection.js";
+import { INTERNAL_INIT_EVENT } 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 { buildActorRefCore, notifyListeners } from "../actor.js";
+import { Cause, Clock, Effect, Exit, Fiber, Option, Queue, Ref, Schedule, Scope, SubscriptionRef } from "effect";
+
+//#region src/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);
+		version = persistedEvent.version;
+	}
+	return {
+		state,
+		version
+	};
+});
+/**
+* Build PersistentActorRef with all methods
+*/
+const buildPersistentActorRef = (id, persistentMachine, stateRef, versionRef, eventQueue, stoppedRef, listeners, stop, adapter) => {
+	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 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 dummySelf = { send: Effect.fn("effect-machine.persistentActor.replay.send")((_event) => Effect.void) };
+					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 dummySelf = { send: Effect.fn("effect-machine.persistentActor.replay.send")((_event) => Effect.void) };
+					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),
+		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 inspector = Option.getOrUndefined(yield* Effect.serviceOption(Inspector));
+	const eventQueue = yield* Queue.unbounded();
+	const stoppedRef = yield* Ref.make(false);
+	const self = { send: Effect.fn("effect-machine.persistentActor.self.send")(function* (event) {
+		if (yield* Ref.get(stoppedRef)) return;
+		yield* Queue.offer(eventQueue, event);
+	}) };
+	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
+	};
+	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
+		}).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);
+	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);
+	}
+	const loopFiber = yield* Effect.forkDaemon(persistentEventLoop(id, persistentMachine, stateRef, versionRef, eventQueue, stoppedRef, self, listeners, adapter, createdAt, stateScopeRef, backgroundFibers, snapshotQueue, snapshotEnabledRef, persistenceQueue, snapshotFiber, persistenceFiber, inspector));
+	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);
+});
+/**
+* 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) {
+	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, 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) {
+	yield* emitWithTimestamp(inspector, (timestamp) => ({
+		type: "@machine.effect",
+		actorId,
+		effectType: "spawn",
+		state,
+		timestamp
+	}));
+	yield* runSpawnEffects(machine, state, event, self, stateScope, 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/{src/persistence/persistent-machine.ts → dist/persistence/persistent-machine.d.ts}

@@ -1,13 +1,14 @@
-import type { Schema, Schedule } from "effect";
-
-import type { Machine } from "../machine.js";
-import type { StateBrand, EventBrand } from "../internal/brands.js";
-import { MissingSchemaError } from "../errors.js";
-
-// Branded type constraints
-type BrandedState = { readonly _tag: string } & StateBrand;
-type BrandedEvent = { readonly _tag: string } & EventBrand;
+import { EventBrand, StateBrand } from "../internal/brands.js";
+import { Machine } from "../machine.js";
+import { Schedule, Schema } from "effect";
 
+//#region src/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.
@@ -15,7 +16,7 @@ type BrandedEvent = { readonly _tag: string } & EventBrand;
  * 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.
  */
-export interface PersistenceConfig<S, E, SSI = unknown, ESI = unknown> {
+interface PersistenceConfig<S, E, SSI = unknown, ESI = unknown> {
   /**
    * Schedule controlling when snapshots are taken.
    * Input is the new state after each transition.
@@ -26,25 +27,21 @@ export interface PersistenceConfig<S, E, SSI = unknown, ESI = unknown> {
    * - 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.
@@ -52,32 +49,27 @@ export interface PersistenceConfig<S, E, SSI = unknown, ESI = unknown> {
    */
   readonly machineType?: string;
 }
-
 /**
  * Machine with persistence configuration attached.
  * Spawn auto-detects this and returns PersistentActorRef.
  */
-export interface PersistentMachine<
-  S extends { readonly _tag: string },
-  E extends { readonly _tag: string },
-  R = never,
-> {
+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
  */
-export const isPersistentMachine = (
-  value: unknown,
-): value is PersistentMachine<{ readonly _tag: string }, { readonly _tag: string }, unknown> =>
-  typeof value === "object" &&
-  value !== null &&
-  "_tag" in value &&
-  (value as { _tag: unknown })._tag === "PersistentMachine";
-
+declare const isPersistentMachine: (value: unknown) => value is PersistentMachine<{
+  readonly _tag: string;
+}, {
+  readonly _tag: string;
+}, unknown>;
 /**
  * Attach persistence configuration to a machine.
  *
@@ -101,31 +93,13 @@ export const isPersistentMachine = (
  * );
  * ```
  */
-export interface WithPersistenceConfig {
-  readonly snapshotSchedule: Schedule.Schedule<unknown, { readonly _tag: string }>;
+interface WithPersistenceConfig {
+  readonly snapshotSchedule: Schedule.Schedule<unknown, {
+    readonly _tag: string;
+  }>;
   readonly journalEvents: boolean;
   readonly machineType?: string;
 }
-
-export const persist =
-  (config: WithPersistenceConfig) =>
-  <S extends BrandedState, E extends BrandedEvent, R>(
-    machine: Machine<S, E, R>,
-  ): PersistentMachine<S, E, R> => {
-    const stateSchema = machine.stateSchema;
-    const eventSchema = machine.eventSchema;
-
-    if (stateSchema === undefined || eventSchema === undefined) {
-      throw new MissingSchemaError({ operation: "persist" });
-    }
-
-    return {
-      _tag: "PersistentMachine",
-      machine,
-      persistence: {
-        ...config,
-        stateSchema,
-        eventSchema,
-      } as unknown as PersistenceConfig<S, E>,
-    };
-  };
+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/persistence/persistent-machine.js

@@ -0,0 +1,24 @@
+import { MissingSchemaError } from "../errors.js";
+
+//#region src/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/schema.d.ts

@@ -0,0 +1,141 @@
+import { FullEventBrand, FullStateBrand } from "./internal/brands.js";
+import { Schema } from "effect";
+
+//#region src/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 };