@shirudo/ddd-kit 3.0.0-rc.12 → 3.0.0-rc.13

package/dist/state-machine.js

@@ -0,0 +1,673 @@
+import { E as KitWiringError, o as DomainError } from "./chunks/kit-errors.js";
+import { _ as isIntrinsicConstructorPrototype, g as isBuiltInObject, m as findPropertyDescriptor, n as deepFreeze } from "./chunks/value-object.js";
+
+//#region src/domain/state-machine/errors.ts
+/** No transition is defined for the input in the current state. */
+var InvalidDomainTransitionError = class extends DomainError {
+	state;
+	inputType;
+	constructor(state, inputType) {
+		super({
+			code: "INVALID_DOMAIN_TRANSITION",
+			message: `No domain transition from "${state}" on "${inputType}".`
+		});
+		this.state = state;
+		this.inputType = inputType;
+	}
+};
+/** A defined transition was rejected by its domain guard. */
+var DomainTransitionGuardRejectedError = class extends DomainError {
+	state;
+	inputType;
+	constructor(state, inputType) {
+		super({
+			code: "DOMAIN_TRANSITION_GUARD_REJECTED",
+			message: `Domain transition guard rejected "${inputType}" from "${state}".`
+		});
+		this.state = state;
+		this.inputType = inputType;
+	}
+};
+/** The machine definition violates its runtime contract. */
+var InvalidDomainMachineDefinitionError = class extends KitWiringError {
+	constructor(message, cause) {
+		super("INVALID_DOMAIN_MACHINE_DEFINITION", message, cause);
+	}
+};
+/** Context contains unsupported or unsafe runtime data. */
+var InvalidDomainMachineContextError = class extends KitWiringError {
+	constructor(message, cause) {
+		super("INVALID_DOMAIN_MACHINE_CONTEXT", message, cause);
+	}
+};
+/** A supplied or produced snapshot is malformed or violates invariants. */
+var InvalidDomainMachineSnapshotError = class extends KitWiringError {
+	constructor(message, cause) {
+		super("INVALID_DOMAIN_MACHINE_SNAPSHOT", message, cause);
+	}
+};
+/** An input is malformed or contains unsupported runtime data. */
+var InvalidDomainMachineInputError = class extends KitWiringError {
+	constructor(message, cause) {
+		super("INVALID_DOMAIN_MACHINE_INPUT", message, cause);
+	}
+};
+/** A guard returned a value other than `boolean` or `DomainError`. */
+var InvalidDomainTransitionGuardResultError = class extends KitWiringError {
+	constructor(message, cause) {
+		super("INVALID_DOMAIN_TRANSITION_GUARD_RESULT", message, cause);
+	}
+};
+/** A reducer returned a malformed result or unsupported output data. */
+var InvalidDomainTransitionResultError = class extends KitWiringError {
+	constructor(message, cause) {
+		super("INVALID_DOMAIN_TRANSITION_RESULT", message, cause);
+	}
+};
+/** A callback attempted to evaluate the same stateful machine recursively. */
+var ReentrantDomainStateMachineEvaluationError = class extends KitWiringError {
+	constructor() {
+		super("REENTRANT_DOMAIN_STATE_MACHINE_EVALUATION", "Domain state machine callbacks cannot evaluate the same machine.");
+	}
+};
+
+//#endregion
+//#region src/domain/state-machine/machine-data.ts
+const DOMAIN_MACHINE_DATA_MAX_DEPTH = 256;
+const DOMAIN_MACHINE_DATA_MAX_NODES = 1e4;
+const DOMAIN_MACHINE_DATA_MAX_PROPERTIES = 1e5;
+function copyDomainMachineOutputs(outputs) {
+	try {
+		const copiedOutputs = cloneDomainMachineDataValue(outputs ?? [], createDomainTransitionOutputError);
+		return deepFreeze(copiedOutputs);
+	} catch (cause) {
+		if (cause instanceof InvalidDomainTransitionResultError) throw cause;
+		throw new InvalidDomainTransitionResultError("Domain transition result outputs must contain cloneable, deeply immutable data.", cause);
+	}
+}
+function copyDomainMachineInput(input) {
+	try {
+		return deepFreeze(cloneDomainMachineDataValue(input, createDomainMachineInputError));
+	} catch (cause) {
+		if (cause instanceof InvalidDomainMachineInputError) throw cause;
+		throw new InvalidDomainMachineInputError("Domain machine input must contain cloneable, deeply immutable data.", cause);
+	}
+}
+function copyDomainMachineContext(context) {
+	try {
+		return deepFreeze(cloneDomainMachineDataValue(context, createDomainMachineContextError));
+	} catch (cause) {
+		if (cause instanceof InvalidDomainMachineContextError) throw cause;
+		throw new InvalidDomainMachineContextError("Domain machine context must contain cloneable, deeply immutable data.", cause);
+	}
+}
+function createDomainMachineContextError(message, cause) {
+	return new InvalidDomainMachineContextError(message, cause);
+}
+function createDomainMachineInputError(message, cause) {
+	return new InvalidDomainMachineInputError(message, cause);
+}
+function createDomainTransitionOutputError(message, cause) {
+	return new InvalidDomainTransitionResultError(message, cause);
+}
+function cloneDomainMachineDataValue(value, errorFactory, seen = /* @__PURE__ */ new WeakMap(), traversal = {
+	nodes: 0,
+	properties: 0
+}, depth = 0) {
+	if (typeof value === "function") throw errorFactory("Domain machine data cannot contain function values.");
+	if (value === null || typeof value !== "object") return value;
+	const source = value;
+	if (depth > DOMAIN_MACHINE_DATA_MAX_DEPTH) throw errorFactory(`Domain machine data exceeds the maximum depth of ${DOMAIN_MACHINE_DATA_MAX_DEPTH}.`);
+	const existing = seen.get(source);
+	if (existing !== void 0) return existing;
+	traversal.nodes += 1;
+	if (traversal.nodes > DOMAIN_MACHINE_DATA_MAX_NODES) throw errorFactory(`Domain machine data contains more than ${DOMAIN_MACHINE_DATA_MAX_NODES.toLocaleString("en-US")} object nodes.`);
+	const toStringTagDescriptor = findPropertyDescriptor(source, Symbol.toStringTag);
+	if (toStringTagDescriptor !== void 0 && !("value" in toStringTagDescriptor)) throw errorFactory("Domain machine data cannot contain accessor properties.");
+	if (Array.isArray(value)) {
+		if (!isIntrinsicArrayPrototype(Object.getPrototypeOf(value))) throw errorFactory("Domain machine data cannot contain custom Array instances.");
+		const cloned = new Array(value.length);
+		seen.set(source, cloned);
+		for (const key of readDomainMachineDataKeys(source, errorFactory, traversal)) {
+			const descriptor = Object.getOwnPropertyDescriptor(source, key);
+			if (!descriptor) continue;
+			if (!("value" in descriptor)) throw errorFactory("Domain machine data cannot contain accessor properties.");
+			if (key === "length") continue;
+			descriptor.value = cloneDomainMachineDataValue(descriptor.value, errorFactory, seen, traversal, depth + 1);
+			Object.defineProperty(cloned, key, descriptor);
+		}
+		return cloned;
+	}
+	const prototype = Object.getPrototypeOf(source);
+	if (prototype !== null && !isIntrinsicObjectPrototype(prototype)) throw errorFactory("Domain machine data cannot contain custom class instances.");
+	const tag = Object.prototype.toString.call(source);
+	if (isBuiltInObject(source, tag) || ArrayBuffer.isView(source)) throw errorFactory(`Domain machine data cannot contain ${tag.slice(8, -1)} object values.`);
+	const cloned = Object.create(prototype === null ? null : Object.prototype);
+	seen.set(source, cloned);
+	for (const key of readDomainMachineDataKeys(source, errorFactory, traversal)) {
+		const descriptor = Object.getOwnPropertyDescriptor(source, key);
+		if (!descriptor) continue;
+		if (!("value" in descriptor)) throw errorFactory("Domain machine data cannot contain accessor properties.");
+		descriptor.value = cloneDomainMachineDataValue(descriptor.value, errorFactory, seen, traversal, depth + 1);
+		Object.defineProperty(cloned, key, descriptor);
+	}
+	return cloned;
+}
+function readDomainMachineDataKeys(value, errorFactory, traversal) {
+	const keys = Reflect.ownKeys(value);
+	traversal.properties += keys.length;
+	if (traversal.properties > DOMAIN_MACHINE_DATA_MAX_PROPERTIES) throw errorFactory(`Domain machine data contains more than ${DOMAIN_MACHINE_DATA_MAX_PROPERTIES.toLocaleString("en-US")} own properties.`);
+	return keys;
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isPlainRecord(value) {
+	if (!isRecord(value)) return false;
+	const prototype = Object.getPrototypeOf(value);
+	return prototype === null || isIntrinsicObjectPrototype(prototype);
+}
+function isIntrinsicArrayPrototype(prototype) {
+	if (prototype === null || !Array.isArray(prototype)) return false;
+	if (!isIntrinsicConstructorPrototype(prototype, "Array")) return false;
+	const parentPrototype = Object.getPrototypeOf(prototype);
+	return parentPrototype !== null && isIntrinsicObjectPrototype(parentPrototype);
+}
+function isIntrinsicObjectPrototype(prototype) {
+	return Object.getPrototypeOf(prototype) === null && isIntrinsicConstructorPrototype(prototype, "Object");
+}
+function hasOwn(value, key) {
+	return Object.hasOwn(value, key);
+}
+
+//#endregion
+//#region src/domain/state-machine/definition.ts
+const DOMAIN_MACHINE_DEFINITION_KEYS = /* @__PURE__ */ new Set([
+	"initial",
+	"initialContext",
+	"validateSnapshot",
+	"states"
+]);
+const DOMAIN_MACHINE_STATE_NODE_KEYS = /* @__PURE__ */ new Set([
+	"terminal",
+	"validateContext",
+	"on"
+]);
+const DOMAIN_MACHINE_TRANSITION_KEYS = /* @__PURE__ */ new Set([
+	"target",
+	"guard",
+	"reduce"
+]);
+function copyDomainMachineDefinition(definition) {
+	const states = readDomainMachineDefinitionProperty(definition, "states");
+	const copiedStates = Object.create(null);
+	for (const state of Object.keys(states)) {
+		const node = readDomainMachineDefinitionProperty(states, state);
+		const transitions = readOptionalDomainMachineDefinitionProperty(node, "on");
+		const copiedTransitions = Object.create(null);
+		for (const inputType of Object.keys(transitions ?? {})) {
+			const transition = readDomainMachineDefinitionProperty(transitions, inputType);
+			if (transition) {
+				const copiedTransition = Object.freeze({
+					target: readDomainMachineDefinitionProperty(transition, "target"),
+					guard: readOptionalDomainMachineDefinitionProperty(transition, "guard"),
+					reduce: readOptionalDomainMachineDefinitionProperty(transition, "reduce")
+				});
+				Object.defineProperty(copiedTransitions, inputType, {
+					value: copiedTransition,
+					enumerable: true
+				});
+			}
+		}
+		Object.defineProperty(copiedStates, state, {
+			value: Object.freeze({
+				terminal: readOptionalDomainMachineDefinitionProperty(node, "terminal"),
+				validateContext: readOptionalDomainMachineDefinitionProperty(node, "validateContext"),
+				on: Object.freeze(copiedTransitions)
+			}),
+			enumerable: true
+		});
+	}
+	return Object.freeze({
+		initial: readDomainMachineDefinitionProperty(definition, "initial"),
+		initialContext: readDomainMachineDefinitionProperty(definition, "initialContext"),
+		validateSnapshot: readOptionalDomainMachineDefinitionProperty(definition, "validateSnapshot"),
+		states: Object.freeze(copiedStates)
+	});
+}
+/**
+* Registry of definitions produced by `prepareDomainMachineDefinition`:
+* validated, defensively copied, deeply frozen. The runtime membership
+* proof lives in this module-private WeakSet (the stable copies are
+* frozen and must stay pure data, so no runtime brand property); the
+* compile-time proof is the required type brand on
+* {@link PreparedDomainMachineDefinition}. Only
+* `prepareDomainMachineDefinition` below adds to the set, so membership
+* always implies validated + copied + frozen.
+*/
+const preparedDefinitions = /* @__PURE__ */ new WeakSet();
+/**
+* The entry-point normalization every pure function and the
+* `DomainStateMachine` constructor share: a prepared definition passes
+* through untouched (already validated, copied, frozen); anything else
+* pays the documented per-call validate-and-copy.
+*/
+function ensureStableDomainMachineDefinition(definition) {
+	if (preparedDefinitions.has(definition)) return definition;
+	validateDomainMachineDefinition(definition);
+	const stable = copyDomainMachineDefinition(definition);
+	validateDomainMachineDefinition(stable);
+	return stable;
+}
+/**
+* Validates and stabilizes a machine definition ONCE, for repeated use
+* with the pure functions. Without it, `transitionDomainState` and
+* `canTransitionDomainState` re-validate and defensively re-copy the
+* WHOLE definition on every call (the documented safety of the raw
+* path); on a hot dispatch path that is avoidable O(definition) work.
+* The `DomainStateMachine` class does the equivalent once in its
+* constructor; this export brings the same amortization to pure-API
+* users:
+*
+* ```ts
+* const prepared = prepareDomainMachineDefinition(orderLifecycle);
+* // per dispatch: no re-validation, no definition copy
+* const outcome = transitionDomainState(prepared, snapshot, input);
+* ```
+*
+* The returned definition is a deeply frozen copy, isolated from later
+* mutation of the input object. Preparing an already-prepared
+* definition returns it unchanged.
+*/
+function prepareDomainMachineDefinition(definition) {
+	const stable = ensureStableDomainMachineDefinition(definition);
+	preparedDefinitions.add(stable);
+	return stable;
+}
+function getTransition(definition, state, input) {
+	const transitions = definition.states[state].on;
+	if (!transitions || !hasOwn(transitions, input.type)) return void 0;
+	return transitions[input.type];
+}
+function validateDomainMachineDefinition(definition) {
+	const candidate = definition;
+	if (!isPlainRecord(candidate)) throw new InvalidDomainMachineDefinitionError("Domain machine definition must be a plain object.");
+	assertDomainMachineDefinitionDataProperties(candidate, DOMAIN_MACHINE_DEFINITION_KEYS);
+	const initial = readDomainMachineDefinitionProperty(candidate, "initial");
+	if (typeof initial !== "string") throw new InvalidDomainMachineDefinitionError("Domain machine initial state must be a string data property.");
+	if (typeof readDomainMachineDefinitionProperty(candidate, "initialContext") !== "function") throw new InvalidDomainMachineDefinitionError("Domain machine initialContext must be a function data property.");
+	const validateSnapshot = readOptionalDomainMachineDefinitionProperty(candidate, "validateSnapshot");
+	if (validateSnapshot !== void 0 && typeof validateSnapshot !== "function") throw new InvalidDomainMachineDefinitionError("Domain machine validateSnapshot must be a function data property.");
+	const statesCandidate = readDomainMachineDefinitionProperty(candidate, "states");
+	if (!isPlainRecord(statesCandidate)) throw new InvalidDomainMachineDefinitionError("Domain machine states must be a plain object data property.");
+	const states = statesCandidate;
+	assertDomainMachineDefinitionEntryMap(states, "state");
+	if (!hasOwn(states, initial)) throw new InvalidDomainMachineDefinitionError(`Initial domain machine state "${initial}" is not defined.`);
+	for (const state of Object.keys(states)) {
+		const node = readDomainMachineDefinitionProperty(states, state);
+		if (!isPlainRecord(node)) throw new InvalidDomainMachineDefinitionError(`Domain machine state "${state}" must be a plain object data property.`);
+		assertDomainMachineDefinitionDataProperties(node, DOMAIN_MACHINE_STATE_NODE_KEYS);
+		const terminal = readOptionalDomainMachineDefinitionProperty(node, "terminal");
+		if (terminal !== void 0 && typeof terminal !== "boolean") throw new InvalidDomainMachineDefinitionError(`Domain machine state "${state}" terminal flag must be a boolean.`);
+		const validateContext = readOptionalDomainMachineDefinitionProperty(node, "validateContext");
+		if (validateContext !== void 0 && typeof validateContext !== "function") throw new InvalidDomainMachineDefinitionError(`Domain machine state "${state}" validateContext must be a function.`);
+		const transitions = readOptionalDomainMachineDefinitionProperty(node, "on");
+		if (transitions !== void 0 && !isPlainRecord(transitions)) throw new InvalidDomainMachineDefinitionError(`Domain machine state "${state}" transitions must be a plain object.`);
+		if (isPlainRecord(transitions)) assertDomainMachineDefinitionEntryMap(transitions, "input");
+		const inputTypes = Object.keys(transitions ?? {});
+		if (terminal === true && inputTypes.length > 0) throw new InvalidDomainMachineDefinitionError(`Terminal domain machine state "${state}" cannot declare transitions.`);
+		for (const inputType of inputTypes) {
+			const transition = readDomainMachineDefinitionProperty(transitions, inputType);
+			if (!isPlainRecord(transition)) throw new InvalidDomainMachineDefinitionError(`Domain transition from "${state}" on "${inputType}" must be a plain object.`);
+			assertDomainMachineDefinitionDataProperties(transition, DOMAIN_MACHINE_TRANSITION_KEYS);
+			const target = readDomainMachineDefinitionProperty(transition, "target");
+			if (typeof target !== "string") throw new InvalidDomainMachineDefinitionError(`Domain transition from "${state}" on "${inputType}" must target a string state.`);
+			if (!hasOwn(states, target)) throw new InvalidDomainMachineDefinitionError(`Domain transition from "${state}" on "${inputType}" targets unknown state "${target}".`);
+			const guard = readOptionalDomainMachineDefinitionProperty(transition, "guard");
+			if (guard !== void 0 && typeof guard !== "function") throw new InvalidDomainMachineDefinitionError(`Domain transition from "${state}" on "${inputType}" guard must be a function.`);
+			const reduce = readOptionalDomainMachineDefinitionProperty(transition, "reduce");
+			if (reduce !== void 0 && typeof reduce !== "function") throw new InvalidDomainMachineDefinitionError(`Domain transition from "${state}" on "${inputType}" reduce must be a function.`);
+		}
+	}
+}
+function assertDomainMachineDefinitionDataProperties(value, allowedKeys) {
+	for (const key of Reflect.ownKeys(value)) {
+		const descriptor = Object.getOwnPropertyDescriptor(value, key);
+		if (descriptor !== void 0 && !("value" in descriptor)) throw new InvalidDomainMachineDefinitionError("Domain machine definition must contain data properties only.");
+		if (allowedKeys !== void 0 && !allowedKeys.has(key)) throw new InvalidDomainMachineDefinitionError(`Domain machine definition contains unknown property "${String(key)}".`);
+	}
+}
+function assertDomainMachineDefinitionEntryMap(value, entryName) {
+	assertDomainMachineDefinitionDataProperties(value);
+	for (const key of Reflect.ownKeys(value)) {
+		const descriptor = Object.getOwnPropertyDescriptor(value, key);
+		if (typeof key !== "string" || descriptor?.enumerable !== true) throw new InvalidDomainMachineDefinitionError(`Domain machine ${entryName} names must be enumerable string properties.`);
+	}
+}
+function readDomainMachineDefinitionProperty(value, key) {
+	const descriptor = Object.getOwnPropertyDescriptor(value, key);
+	if (descriptor === void 0 || !("value" in descriptor)) throw new InvalidDomainMachineDefinitionError("Domain machine definition must contain data properties only.");
+	return descriptor.value;
+}
+function readOptionalDomainMachineDefinitionProperty(value, key) {
+	const descriptor = Object.getOwnPropertyDescriptor(value, key);
+	if (descriptor === void 0) return void 0;
+	if (!("value" in descriptor)) throw new InvalidDomainMachineDefinitionError("Domain machine definition must contain data properties only.");
+	return descriptor.value;
+}
+
+//#endregion
+//#region src/domain/state-machine/snapshot.ts
+const DOMAIN_TRANSITION_RESULT_KEYS = /* @__PURE__ */ new Set(["context", "outputs"]);
+function prepareDomainMachineSnapshot(definition, snapshot) {
+	validateDomainMachineSnapshot(definition, snapshot);
+	const preparedSnapshot = createDomainMachineSnapshot(snapshot);
+	validateDomainMachineSnapshot(definition, preparedSnapshot);
+	validateDomainMachineSnapshotInvariant(definition, preparedSnapshot);
+	return preparedSnapshot;
+}
+function createDomainMachineSnapshotFromPreparedContext(state, context) {
+	return Object.freeze({
+		state,
+		context
+	});
+}
+function createDomainMachineSnapshot(snapshot) {
+	return Object.freeze({
+		state: readDomainMachineSnapshotState(snapshot),
+		context: copyDomainMachineContext(readDomainMachineSnapshotContext(snapshot))
+	});
+}
+function validateDomainMachineSnapshot(definition, snapshot) {
+	if (!isRecord(snapshot)) throw new InvalidDomainMachineSnapshotError("Domain machine snapshot must be an object.");
+	const state = readDomainMachineSnapshotState(snapshot);
+	readDomainMachineSnapshotContext(snapshot);
+	if (!hasOwn(definition.states, state)) throw new InvalidDomainMachineSnapshotError(`Domain machine snapshot state "${state}" is not defined.`);
+}
+function validateDomainMachineSnapshotInvariant(definition, snapshot) {
+	const stateNode = definition.states[snapshot.state];
+	if (stateNode.validateContext !== void 0) {
+		const validContext = stateNode.validateContext({
+			state: snapshot.state,
+			context: snapshot.context
+		});
+		if (typeof validContext !== "boolean") throw new InvalidDomainMachineDefinitionError(`Domain machine state "${snapshot.state}" validateContext must return a boolean.`);
+		if (!validContext) throw new InvalidDomainMachineSnapshotError(`Domain machine snapshot violates the context invariant for state "${snapshot.state}".`);
+	}
+	if (definition.validateSnapshot === void 0) return;
+	const valid = definition.validateSnapshot(snapshot);
+	if (typeof valid !== "boolean") throw new InvalidDomainMachineDefinitionError("Domain machine validateSnapshot must return a boolean.");
+	if (!valid) throw new InvalidDomainMachineSnapshotError(`Domain machine snapshot violates invariants for state "${snapshot.state}".`);
+}
+function readDomainMachineSnapshotState(snapshot) {
+	const stateDescriptor = Object.getOwnPropertyDescriptor(snapshot, "state");
+	if (stateDescriptor === void 0 || !("value" in stateDescriptor) || typeof stateDescriptor.value !== "string") throw new InvalidDomainMachineSnapshotError("Domain machine snapshot state must be a string data property.");
+	return stateDescriptor.value;
+}
+function readDomainMachineSnapshotContext(snapshot) {
+	const contextDescriptor = Object.getOwnPropertyDescriptor(snapshot, "context");
+	if (contextDescriptor === void 0 || !("value" in contextDescriptor)) throw new InvalidDomainMachineSnapshotError("Domain machine snapshot context must be present as a data property.");
+	return contextDescriptor.value;
+}
+function validateDomainMachineInput(input) {
+	if (!isDomainMachineInput(input)) throw new InvalidDomainMachineInputError("Domain machine input must be an object with a string type.");
+}
+function isDomainMachineInput(input) {
+	if (!isRecord(input)) return false;
+	const typeDescriptor = Object.getOwnPropertyDescriptor(input, "type");
+	return typeDescriptor !== void 0 && "value" in typeDescriptor && typeof typeDescriptor.value === "string";
+}
+function resolveDomainTransitionGuardResult(result) {
+	if (typeof result === "boolean") return { allowed: result };
+	if (result instanceof DomainError) return {
+		allowed: false,
+		rejection: result
+	};
+	throw new InvalidDomainTransitionGuardResultError("Domain transition guard must return a boolean or DomainError.");
+}
+function validateDomainTransitionResult(result) {
+	if (result === void 0) return;
+	if (!isPlainRecord(result)) throw new InvalidDomainTransitionResultError("Domain transition result must be a plain object when returned.");
+	for (const key of Reflect.ownKeys(result)) {
+		if (!DOMAIN_TRANSITION_RESULT_KEYS.has(key)) throw new InvalidDomainTransitionResultError(`Domain transition result contains unknown property "${String(key)}".`);
+		const descriptor = Object.getOwnPropertyDescriptor(result, key);
+		if (descriptor !== void 0 && !("value" in descriptor)) throw new InvalidDomainTransitionResultError("Domain transition result must contain data properties only.");
+	}
+	const outputs = readDomainTransitionResultOutputs(result);
+	if (outputs !== void 0 && !Array.isArray(outputs)) throw new InvalidDomainTransitionResultError("Domain transition result outputs must be an array when provided.");
+}
+function readDomainTransitionResultContext(result) {
+	if (result === void 0) return { hasContext: false };
+	const contextDescriptor = Object.getOwnPropertyDescriptor(result, "context");
+	if (contextDescriptor === void 0) return { hasContext: false };
+	if (!("value" in contextDescriptor)) throw new InvalidDomainTransitionResultError("Domain transition result context must be a data property when provided.");
+	return {
+		hasContext: true,
+		context: contextDescriptor.value
+	};
+}
+function readDomainTransitionResultOutputs(result) {
+	if (result === void 0) return void 0;
+	const outputsDescriptor = Object.getOwnPropertyDescriptor(result, "outputs");
+	if (outputsDescriptor === void 0) return void 0;
+	if (!("value" in outputsDescriptor)) throw new InvalidDomainTransitionResultError("Domain transition result outputs must be a data property when provided.");
+	return outputsDescriptor.value;
+}
+
+//#endregion
+//#region src/domain/state-machine/transition.ts
+/** Creates and validates a fresh initial snapshot from a machine definition. */
+function createInitialDomainMachineSnapshot(definition) {
+	return createInitialDomainMachineSnapshotFromPrepared(ensureStableDomainMachineDefinition(definition));
+}
+function createInitialDomainMachineSnapshotFromPrepared(definition) {
+	const snapshot = createDomainMachineSnapshot({
+		state: definition.initial,
+		context: definition.initialContext()
+	});
+	validateDomainMachineSnapshotInvariant(definition, snapshot);
+	return snapshot;
+}
+/**
+* Checks whether an input currently has an allowed transition.
+*
+* Returns `false` for missing transitions, terminal states, rejected guards,
+* and inputs without an own string `type` property. Invalid payload data for a
+* matching transition and broken guard code still throw structured errors.
+*/
+function canTransitionDomainState(definition, snapshot, input) {
+	const stableDefinition = ensureStableDomainMachineDefinition(definition);
+	return canTransitionPreparedDomainState(stableDefinition, prepareDomainMachineSnapshot(stableDefinition, snapshot), input);
+}
+function canTransitionPreparedDomainState(definition, snapshot, input) {
+	if (!isDomainMachineInput(input)) return false;
+	if (definition.states[snapshot.state].terminal === true) return false;
+	const transition = getTransition(definition, snapshot.state, input);
+	if (!transition) return false;
+	const currentInput = copyDomainMachineInput(input);
+	if (!transition.guard) return true;
+	const guardResult = transition.guard({
+		state: snapshot.state,
+		context: snapshot.context,
+		input: currentInput
+	});
+	return resolveDomainTransitionGuardResult(guardResult).allowed;
+}
+/**
+* Applies one input without mutating the input definition or snapshot.
+*
+* @throws {@link InvalidDomainTransitionError} when no transition is defined.
+* @throws {@link DomainTransitionGuardRejectedError} when its guard rejects.
+* @throws A concrete `DomainError` returned by a rejecting guard.
+*/
+function transitionDomainState(definition, snapshot, input) {
+	const stableDefinition = ensureStableDomainMachineDefinition(definition);
+	return transitionPreparedDomainState(stableDefinition, prepareDomainMachineSnapshot(stableDefinition, snapshot), input);
+}
+function transitionPreparedDomainState(definition, snapshot, input) {
+	validateDomainMachineInput(input);
+	const from = snapshot.state;
+	const transition = definition.states[from].terminal === true ? void 0 : getTransition(definition, from, input);
+	if (!transition) throw new InvalidDomainTransitionError(from, input.type);
+	const currentInput = copyDomainMachineInput(input);
+	const guardResult = transition.guard === void 0 ? true : transition.guard({
+		state: from,
+		context: snapshot.context,
+		input: currentInput
+	});
+	const guardDecision = resolveDomainTransitionGuardResult(guardResult);
+	if (!guardDecision.allowed) {
+		if (guardDecision.rejection !== void 0) throw guardDecision.rejection;
+		throw new DomainTransitionGuardRejectedError(from, currentInput.type);
+	}
+	const result = transition.reduce?.({
+		state: from,
+		context: snapshot.context,
+		input: currentInput
+	});
+	validateDomainTransitionResult(result);
+	const contextResult = readDomainTransitionResultContext(result);
+	const nextContext = contextResult.hasContext ? contextResult.context : snapshot.context;
+	const nextSnapshot = nextContext === snapshot.context ? createDomainMachineSnapshotFromPreparedContext(transition.target, snapshot.context) : createDomainMachineSnapshot({
+		state: transition.target,
+		context: nextContext
+	});
+	validateDomainMachineSnapshotInvariant(definition, nextSnapshot);
+	return Object.freeze({
+		from,
+		to: transition.target,
+		snapshot: nextSnapshot,
+		outputs: copyDomainMachineOutputs(readDomainTransitionResultOutputs(result))
+	});
+}
+
+//#endregion
+//#region src/domain/state-machine/analyzer.ts
+/**
+* Inspects the declarative transition graph without executing definition callbacks.
+* Guarded edges are treated as possible edges, so diagnostics never claim more
+* runtime reachability than the static graph can prove.
+*/
+function analyzeDomainMachineDefinition(definition) {
+	const stableDefinition = ensureStableDomainMachineDefinition(definition);
+	const states = Object.keys(stableDefinition.states).sort(compareStrings);
+	const outgoing = /* @__PURE__ */ new Map();
+	const incoming = /* @__PURE__ */ new Map();
+	const transitions = [];
+	for (const state of states) {
+		outgoing.set(state, []);
+		incoming.set(state, []);
+	}
+	for (const state of states) {
+		const stateTransitions = stableDefinition.states[state].on;
+		const inputTypes = Object.keys(stateTransitions ?? {}).sort(compareStrings);
+		for (const inputType of inputTypes) {
+			const transition = stateTransitions?.[inputType];
+			if (transition === void 0) continue;
+			outgoing.get(state)?.push(transition.target);
+			incoming.get(transition.target)?.push(state);
+			transitions.push(Object.freeze({
+				state,
+				inputType,
+				target: transition.target,
+				guarded: transition.guard !== void 0
+			}));
+		}
+	}
+	const structurallyReachable = visitGraph([stableDefinition.initial], outgoing);
+	const statesWithTerminalPath = visitGraph(states.filter((state) => stableDefinition.states[state].terminal === true), incoming);
+	const diagnostics = [];
+	for (const state of states) if (!structurallyReachable.has(state)) diagnostics.push(Object.freeze({
+		code: "unreachable-state",
+		state
+	}));
+	for (const state of states) if (stableDefinition.states[state].terminal !== true && outgoing.get(state)?.length === 0) diagnostics.push(Object.freeze({
+		code: "structural-dead-end",
+		state
+	}));
+	for (const state of states) if (!statesWithTerminalPath.has(state)) diagnostics.push(Object.freeze({
+		code: "no-terminal-path",
+		state
+	}));
+	return Object.freeze({
+		diagnostics: Object.freeze(diagnostics),
+		transitions: Object.freeze(transitions),
+		structurallyReachableStates: Object.freeze(states.filter((state) => structurallyReachable.has(state))),
+		statesWithTerminalPath: Object.freeze(states.filter((state) => statesWithTerminalPath.has(state)))
+	});
+}
+function visitGraph(startStates, edges) {
+	const visited = /* @__PURE__ */ new Set();
+	const pending = [...startStates];
+	while (pending.length > 0) {
+		const state = pending.pop();
+		if (state === void 0 || visited.has(state)) continue;
+		visited.add(state);
+		for (const next of edges.get(state) ?? []) if (!visited.has(next)) pending.push(next);
+	}
+	return visited;
+}
+function compareStrings(left, right) {
+	return left < right ? -1 : left > right ? 1 : 0;
+}
+
+//#endregion
+//#region src/domain/state-machine/domain-state-machine.ts
+/**
+* Stateful convenience wrapper around the pure domain transition functions.
+*
+* Persist {@link snapshot}, not the machine instance. Pass a restored snapshot
+* to the second constructor overload to validate and reconstitute a machine.
+*/
+var DomainStateMachine = class {
+	definition;
+	#snapshot;
+	#evaluating = false;
+	constructor(definition, ...snapshotInput) {
+		this.definition = ensureStableDomainMachineDefinition(definition);
+		const [suppliedSnapshot] = snapshotInput;
+		if (suppliedSnapshot !== void 0) this.#snapshot = prepareDomainMachineSnapshot(this.definition, suppliedSnapshot);
+		else this.#snapshot = createInitialDomainMachineSnapshotFromPrepared(this.definition);
+	}
+	/** Returns a defensive, deeply frozen copy of the current snapshot. */
+	get snapshot() {
+		return createDomainMachineSnapshot(this.#snapshot);
+	}
+	/** Current named control state. */
+	get state() {
+		return this.#snapshot.state;
+	}
+	/** Current deeply readonly context. */
+	get context() {
+		return this.#snapshot.context;
+	}
+	/** Whether the current state permanently forbids outgoing transitions. */
+	isTerminal() {
+		return this.definition.states[this.state].terminal === true;
+	}
+	/** Checks a transition without changing the current snapshot. */
+	can(input) {
+		return this.evaluate(() => canTransitionPreparedDomainState(this.definition, this.#snapshot, input));
+	}
+	/** Applies an input and advances the current snapshot on success. */
+	dispatch(input) {
+		return this.evaluate(() => {
+			const result = transitionPreparedDomainState(this.definition, this.#snapshot, input);
+			this.#snapshot = result.snapshot;
+			return result;
+		});
+	}
+	evaluate(operation) {
+		if (this.#evaluating) throw new ReentrantDomainStateMachineEvaluationError();
+		this.#evaluating = true;
+		try {
+			return operation();
+		} finally {
+			this.#evaluating = false;
+		}
+	}
+};
+
+//#endregion
+export { DomainStateMachine, DomainTransitionGuardRejectedError, InvalidDomainMachineContextError, InvalidDomainMachineDefinitionError, InvalidDomainMachineInputError, InvalidDomainMachineSnapshotError, InvalidDomainTransitionError, InvalidDomainTransitionGuardResultError, InvalidDomainTransitionResultError, ReentrantDomainStateMachineEvaluationError, analyzeDomainMachineDefinition, canTransitionDomainState, createInitialDomainMachineSnapshot, prepareDomainMachineDefinition, transitionDomainState };
+//# sourceMappingURL=state-machine.js.map