@futdevpro/fsm-dynamo 1.15.11 → 1.15.12

package/src/_modules/state-machine/_models/state-machine-event.interface.ts

@@ -0,0 +1,25 @@
+/**
+ * Egy sikeres atmenet utan kibocsatott esemeny.
+ *
+ * A `DyFM_StateMachine.events$` Observable-en at szubszkribalhato. Az opcionalis
+ * `persist` callback is ezt az objektumot kapja meg, igy a konzumens (pl.
+ * Mongoose ControlModel) eldontheti milyen mezoket frissit.
+ *
+ * `stateVersion` minden sikeres atmenet utan inkrementalodik (0 -> 1 -> 2 -> ...).
+ * Optimistic-concurrency token-kent hasznalhato a `persist` callback-ben
+ * (`$inc: { stateVersion: 1 }` + `findOneAndUpdate({ stateVersion: prevVersion })`
+ * mintara) hogy a race conditions detektalhatoak legyenek tobb-folyamatos
+ * deploy-okban.
+ */
+export interface DyFM_StateMachineEvent<TState extends string, TContext = unknown> {
+  /** Az atmenet elotti state. */
+  from: TState;
+  /** Az atmenet utani state. */
+  to: TState;
+  /** A frissitett state-version szam (>= 1). */
+  stateVersion: number;
+  /** Az opcionalis context, ahogy a `transition()`-be erkezett. */
+  context?: TContext;
+  /** Az atmenet idobelyege (ms epoch). */
+  timestamp: number;
+}

package/src/_modules/state-machine/_models/state-machine.control-model.spec.ts

@@ -0,0 +1,314 @@
+import { firstValueFrom, take, toArray } from 'rxjs';
+
+import { DyFM_StateMachine } from './state-machine.control-model';
+import { DyFM_StateMachineEvent } from './state-machine-event.interface';
+import {
+  DyFM_StateMachineTransition_FailureResult,
+  DyFM_StateMachineTransition_Result,
+  DyFM_StateMachineTransition_SuccessResult,
+} from './state-transition-result.interface';
+
+
+/** Test state-enum a RAG ingest mintabol. */
+enum TestRagState {
+  Idle = 'idle',
+  Ingesting = 'ingesting',
+  Embedding = 'embedding',
+  Ready = 'ready',
+  Degraded = 'degraded',
+  Reingesting = 'reingesting',
+}
+
+/** Default test-config helper. */
+const buildBasicConfig = () => ({
+  initial: TestRagState.Idle,
+  transitions: [
+    { from: TestRagState.Idle, to: TestRagState.Ingesting },
+    { from: TestRagState.Ingesting, to: TestRagState.Embedding },
+    { from: TestRagState.Embedding, to: TestRagState.Ready },
+    { from: TestRagState.Ready, to: TestRagState.Degraded },
+    { from: TestRagState.Degraded, to: TestRagState.Reingesting },
+    { from: TestRagState.Reingesting, to: TestRagState.Ready },
+    // Wildcard array → degraded from any "working" state
+    {
+      from: [TestRagState.Ingesting, TestRagState.Embedding, TestRagState.Reingesting] as TestRagState[],
+      to: TestRagState.Degraded,
+    },
+  ],
+});
+
+
+describe('| DyFM_StateMachine | constructor + sync getters', () => {
+  it('| initial state is set from config.initial', () => {
+    const sm = new DyFM_StateMachine<TestRagState>(buildBasicConfig());
+    expect(sm.state()).toBe(TestRagState.Idle);
+    expect(sm.stateVersion()).toBe(0);
+  });
+
+  it('| throws on missing config', () => {
+    expect(() => new DyFM_StateMachine<TestRagState>(undefined as any)).toThrowError(/config object required/);
+  });
+
+  it('| throws on missing config.initial', () => {
+    expect(() => new DyFM_StateMachine<TestRagState>({ transitions: [] } as any)).toThrowError(/initial must be a string/);
+  });
+
+  it('| throws on empty transitions array', () => {
+    expect(() => new DyFM_StateMachine<TestRagState>({ initial: TestRagState.Idle, transitions: [] })).toThrowError(/non-empty array/);
+  });
+});
+
+
+describe('| DyFM_StateMachine | state$ observable', () => {
+  it('| emits initial value on subscribe (BehaviorSubject pattern)', async () => {
+    const sm = new DyFM_StateMachine<TestRagState>(buildBasicConfig());
+    const firstValue: TestRagState = await firstValueFrom(sm.state$);
+    expect(firstValue).toBe(TestRagState.Idle);
+  });
+
+  it('| emits new state after successful transition', async () => {
+    const sm = new DyFM_StateMachine<TestRagState>(buildBasicConfig());
+    const next$: Promise<TestRagState[]> = firstValueFrom(sm.state$.pipe(take(2), toArray()));
+    await sm.transition(TestRagState.Ingesting);
+    const emitted: TestRagState[] = await next$;
+    expect(emitted).toEqual([TestRagState.Idle, TestRagState.Ingesting]);
+  });
+});
+
+
+describe('| DyFM_StateMachine | canTransition', () => {
+  it('| true on valid transition path', async () => {
+    const sm = new DyFM_StateMachine<TestRagState>(buildBasicConfig());
+    expect(await sm.canTransition(TestRagState.Ingesting)).toBe(true);
+  });
+
+  it('| false on invalid transition (no matching from→to)', async () => {
+    const sm = new DyFM_StateMachine<TestRagState>(buildBasicConfig());
+    // Idle → Ready is NOT in the transition map
+    expect(await sm.canTransition(TestRagState.Ready)).toBe(false);
+  });
+
+  it('| false when guard returns false', async () => {
+    const sm = new DyFM_StateMachine<TestRagState, { allow: boolean }>({
+      initial: TestRagState.Idle,
+      transitions: [
+        { from: TestRagState.Idle, to: TestRagState.Ingesting, guard: (ctx) => ctx?.allow === true },
+      ],
+    });
+    expect(await sm.canTransition(TestRagState.Ingesting, { allow: false })).toBe(false);
+    expect(await sm.canTransition(TestRagState.Ingesting, { allow: true })).toBe(true);
+  });
+});
+
+
+describe('| DyFM_StateMachine | transition — happy paths', () => {
+  it('| basic ok flow: state changes, stateVersion++, ok result', async () => {
+    const sm = new DyFM_StateMachine<TestRagState>(buildBasicConfig());
+    const result: DyFM_StateMachineTransition_Result<TestRagState> = await sm.transition(TestRagState.Ingesting);
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.from).toBe(TestRagState.Idle);
+      expect(result.to).toBe(TestRagState.Ingesting);
+      expect(result.stateVersion).toBe(1);
+    }
+    expect(sm.state()).toBe(TestRagState.Ingesting);
+    expect(sm.stateVersion()).toBe(1);
+  });
+
+  it('| full happy-path through ingest → ready', async () => {
+    const sm = new DyFM_StateMachine<TestRagState>(buildBasicConfig());
+    await sm.transition(TestRagState.Ingesting);
+    await sm.transition(TestRagState.Embedding);
+    const r3: DyFM_StateMachineTransition_Result<TestRagState> = await sm.transition(TestRagState.Ready);
+    expect(r3.ok).toBe(true);
+    expect(sm.state()).toBe(TestRagState.Ready);
+    expect(sm.stateVersion()).toBe(3);
+  });
+
+  it('| wildcard `*` from matches any current state', async () => {
+    const sm = new DyFM_StateMachine<TestRagState>({
+      initial: TestRagState.Idle,
+      transitions: [
+        { from: '*', to: TestRagState.Degraded },
+        { from: TestRagState.Idle, to: TestRagState.Ingesting },
+      ],
+    });
+    // Idle → Degraded via wildcard
+    const r1 = await sm.transition(TestRagState.Degraded);
+    expect(r1.ok).toBe(true);
+    expect(sm.state()).toBe(TestRagState.Degraded);
+  });
+
+  it('| array-from matches multiple sources', async () => {
+    const sm = new DyFM_StateMachine<TestRagState>(buildBasicConfig());
+    await sm.transition(TestRagState.Ingesting);
+    // [Ingesting, Embedding, Reingesting] → Degraded
+    const r: DyFM_StateMachineTransition_Result<TestRagState> = await sm.transition(TestRagState.Degraded);
+    expect(r.ok).toBe(true);
+    expect(sm.state()).toBe(TestRagState.Degraded);
+  });
+});
+
+
+describe('| DyFM_StateMachine | transition — failure paths', () => {
+  it('| invalid-transition reason when no matching transition', async () => {
+    const sm = new DyFM_StateMachine<TestRagState>(buildBasicConfig());
+    // Idle → Ready is not in the map
+    const result: DyFM_StateMachineTransition_Result<TestRagState> = await sm.transition(TestRagState.Ready);
+    expect(result.ok).toBe(false);
+    const f: DyFM_StateMachineTransition_FailureResult<TestRagState> = result as DyFM_StateMachineTransition_FailureResult<TestRagState>;
+    expect(f.reason).toBe('invalid-transition');
+    expect(f.currentState).toBe(TestRagState.Idle);
+    expect(f.attemptedTo).toBe(TestRagState.Ready);
+    expect(sm.state()).toBe(TestRagState.Idle);
+    expect(sm.stateVersion()).toBe(0);
+  });
+
+  it('| guard-rejected reason when guard returns false; state unchanged', async () => {
+    const sm = new DyFM_StateMachine<TestRagState, { allow: boolean }>({
+      initial: TestRagState.Idle,
+      transitions: [
+        { from: TestRagState.Idle, to: TestRagState.Ingesting, guard: (ctx) => ctx?.allow === true },
+      ],
+    });
+    const result = await sm.transition(TestRagState.Ingesting, { allow: false });
+    expect(result.ok).toBe(false);
+    const f: DyFM_StateMachineTransition_FailureResult<TestRagState> = result as DyFM_StateMachineTransition_FailureResult<TestRagState>;
+    expect(f.reason).toBe('guard-rejected');
+    expect(sm.state()).toBe(TestRagState.Idle);
+    expect(sm.stateVersion()).toBe(0);
+  });
+
+  it('| onLeave called BEFORE state change', async () => {
+    let stateAtOnLeave: TestRagState | null = null;
+    const sm = new DyFM_StateMachine<TestRagState>({
+      initial: TestRagState.Idle,
+      transitions: [
+        {
+          from: TestRagState.Idle,
+          to: TestRagState.Ingesting,
+          onLeave: async () => { stateAtOnLeave = sm.state(); },
+        },
+      ],
+    });
+    await sm.transition(TestRagState.Ingesting);
+    expect(stateAtOnLeave).toBe(TestRagState.Idle);
+    expect(sm.state()).toBe(TestRagState.Ingesting);
+  });
+
+  it('| onEnter called AFTER state change, BEFORE persist', async () => {
+    let stateAtOnEnter: TestRagState | null = null;
+    let stateAtPersist: TestRagState | null = null;
+    const sm = new DyFM_StateMachine<TestRagState>({
+      initial: TestRagState.Idle,
+      transitions: [
+        {
+          from: TestRagState.Idle,
+          to: TestRagState.Ingesting,
+          onEnter: async () => { stateAtOnEnter = sm.state(); },
+        },
+      ],
+      persist: async () => { stateAtPersist = sm.state(); },
+    });
+    await sm.transition(TestRagState.Ingesting);
+    expect(stateAtOnEnter).toBe(TestRagState.Ingesting);
+    expect(stateAtPersist).toBe(TestRagState.Ingesting);
+  });
+
+  it('| onEnter throw → state reverts + on-enter-failed reason', async () => {
+    const sm = new DyFM_StateMachine<TestRagState>({
+      initial: TestRagState.Idle,
+      transitions: [
+        {
+          from: TestRagState.Idle,
+          to: TestRagState.Ingesting,
+          onEnter: async () => { throw new Error('boom-onEnter'); },
+        },
+      ],
+    });
+    const result: DyFM_StateMachineTransition_Result<TestRagState> = await sm.transition(TestRagState.Ingesting);
+    expect(result.ok).toBe(false);
+    const f1: DyFM_StateMachineTransition_FailureResult<TestRagState> = result as DyFM_StateMachineTransition_FailureResult<TestRagState>;
+    expect(f1.reason).toBe('on-enter-failed');
+    expect(String((f1.error as Error)?.message ?? '')).toContain('boom-onEnter');
+    expect(sm.state()).toBe(TestRagState.Idle);   // reverted
+    expect(sm.stateVersion()).toBe(0);             // reverted
+  });
+
+  it('| persist throw → state reverts + persist-failed reason', async () => {
+    const sm = new DyFM_StateMachine<TestRagState>({
+      initial: TestRagState.Idle,
+      transitions: [
+        { from: TestRagState.Idle, to: TestRagState.Ingesting },
+      ],
+      persist: async () => { throw new Error('boom-persist'); },
+    });
+    const result = await sm.transition(TestRagState.Ingesting);
+    expect(result.ok).toBe(false);
+    const f2: DyFM_StateMachineTransition_FailureResult<TestRagState> = result as DyFM_StateMachineTransition_FailureResult<TestRagState>;
+    expect(f2.reason).toBe('persist-failed');
+    expect(String((f2.error as Error)?.message ?? '')).toContain('boom-persist');
+    expect(sm.state()).toBe(TestRagState.Idle);   // reverted
+    expect(sm.stateVersion()).toBe(0);
+  });
+
+  it('| onLeave throw → state NOT changed + on-leave-failed reason', async () => {
+    const sm = new DyFM_StateMachine<TestRagState>({
+      initial: TestRagState.Idle,
+      transitions: [
+        {
+          from: TestRagState.Idle,
+          to: TestRagState.Ingesting,
+          onLeave: async () => { throw new Error('boom-onLeave'); },
+        },
+      ],
+    });
+    const result = await sm.transition(TestRagState.Ingesting);
+    expect(result.ok).toBe(false);
+    const f3: DyFM_StateMachineTransition_FailureResult<TestRagState> = result as DyFM_StateMachineTransition_FailureResult<TestRagState>;
+    expect(f3.reason).toBe('on-leave-failed');
+    expect(sm.state()).toBe(TestRagState.Idle);   // never changed
+    expect(sm.stateVersion()).toBe(0);
+  });
+});
+
+
+describe('| DyFM_StateMachine | events$ + mutex', () => {
+  it('| events$ emits on successful transition', async () => {
+    const sm = new DyFM_StateMachine<TestRagState>(buildBasicConfig());
+    const event$: Promise<DyFM_StateMachineEvent<TestRagState>> = firstValueFrom(sm.events$);
+    await sm.transition(TestRagState.Ingesting);
+    const event = await event$;
+    expect(event.from).toBe(TestRagState.Idle);
+    expect(event.to).toBe(TestRagState.Ingesting);
+    expect(event.stateVersion).toBe(1);
+    expect(typeof event.timestamp).toBe('number');
+  });
+
+  it('| concurrent transitions are serialized (mutex)', async () => {
+    let inflightCount: number = 0;
+    let maxInflight: number = 0;
+    const sm = new DyFM_StateMachine<TestRagState>({
+      initial: TestRagState.Idle,
+      transitions: [
+        { from: TestRagState.Idle, to: TestRagState.Ingesting,
+          onEnter: async (): Promise<void> => {
+            inflightCount++;
+            if (inflightCount > maxInflight) { maxInflight = inflightCount; }
+            await new Promise((r): void => { setTimeout(r, 10); });
+            inflightCount--;
+          },
+        },
+        { from: TestRagState.Ingesting, to: TestRagState.Idle },
+      ],
+    });
+    // Fire 3 transitions concurrently — they must serialize
+    await Promise.all([
+      sm.transition(TestRagState.Ingesting),
+      sm.transition(TestRagState.Idle),
+      sm.transition(TestRagState.Ingesting),
+    ]);
+    expect(maxInflight).toBe(1);
+    expect(sm.stateVersion()).toBe(3);
+  });
+});

package/src/_modules/state-machine/_models/state-machine.control-model.ts

@@ -0,0 +1,298 @@
+import { BehaviorSubject, Observable, Subject } from 'rxjs';
+
+import { DyFM_StateMachineConfig } from './state-machine-config.interface';
+import { DyFM_StateMachineEvent } from './state-machine-event.interface';
+import { DyFM_StateTransition } from './state-transition.interface';
+import {
+  DyFM_StateMachineTransition_FailureReason,
+  DyFM_StateMachineTransition_Result,
+} from './state-transition-result.interface';
+
+
+/**
+ * Generic finite state machine (FR-006, BL-20260518-004).
+ *
+ * Konfiguralhato `initial` state-tel + `transitions[]` listaval. Reaktiv
+ * (`state$` BehaviorSubject + `events$` Subject), single-instance mutex-szel
+ * vedett, opcionalis aszinkron `persist` callback-kel.
+ *
+ * **Hasznalat (CCAP MP1-D RAG ingest minta):**
+ * ```typescript
+ * enum RagIngestState { Idle='idle', Ingesting='ingesting', Embedding='embedding',
+ *   Ready='ready', Degraded='degraded', Reingesting='reingesting' }
+ *
+ * const ragFsm = new DyFM_StateMachine<RagIngestState>({
+ *   initial: RagIngestState.Idle,
+ *   transitions: [
+ *     { from: RagIngestState.Idle, to: RagIngestState.Ingesting },
+ *     { from: RagIngestState.Ingesting, to: RagIngestState.Embedding,
+ *       guard: ctx => ctx?.pendingChunks === 0 },
+ *     { from: RagIngestState.Embedding, to: RagIngestState.Ready,
+ *       onEnter: () => persistCorpusVersion() },
+ *     { from: RagIngestState.Ready, to: RagIngestState.Degraded },
+ *     { from: RagIngestState.Degraded, to: RagIngestState.Reingesting },
+ *     // Wildcard array: barmely "futasi" allapotbol degraded-re
+ *     { from: [RagIngestState.Ingesting, RagIngestState.Embedding,
+ *              RagIngestState.Reingesting], to: RagIngestState.Degraded },
+ *   ],
+ *   persist: async event => await mongoCollection.updateOne(
+ *     { _id: 'rag-status', stateVersion: event.stateVersion - 1 },
+ *     { $set: { state: event.to, stateVersion: event.stateVersion } },
+ *   ),
+ * });
+ *
+ * const result = await ragFsm.transition(RagIngestState.Ingesting);
+ * if (result.ok) { console.log('Now in:', result.to, 'v:', result.stateVersion); }
+ * ```
+ *
+ * **Atomicity:** Az `onEnter` vagy `persist` callback throw-ja eseten a state
+ * automatikusan visszaall a from-ra (revert). Ha az `onLeave` throw-ol, a
+ * state-valtas mar el sem kezdodik (early-return).
+ *
+ * **Mutex:** Egy-instance-en belul a `transition()` hivasok sorosak (in-memory
+ * Promise-queue). Tobb-instance / tobb-folyamatos race-condition-re az
+ * opcionalis `persist` callback `stateVersion`-t hasznalja optimistic-locking-hez.
+ */
+export class DyFM_StateMachine<TState extends string, TContext = unknown> {
+
+  /** Aktualis state. */
+  private _state: TState;
+
+  /** Aktualis state-version (0 = initial; minden sikeres atmenet utan +1). */
+  private _stateVersion: number = 0;
+
+  /** Reactive state-source. */
+  private readonly _state$: BehaviorSubject<TState>;
+
+  /** Public reactive state observable. */
+  readonly state$: Observable<TState>;
+
+  /** Reactive event-stream — minden sikeres atmenet utan emittal. */
+  private readonly _events$: Subject<DyFM_StateMachineEvent<TState, TContext>>;
+
+  /** Public reactive event observable. */
+  readonly events$: Observable<DyFM_StateMachineEvent<TState, TContext>>;
+
+  /** Config snapshot. */
+  private readonly _config: DyFM_StateMachineConfig<TState, TContext>;
+
+  /** Mutex tail — soros transition() hivasokhoz. */
+  private _mutexTail: Promise<unknown> = Promise.resolve();
+
+
+  constructor(config: DyFM_StateMachineConfig<TState, TContext>) {
+    if (!config || typeof config !== 'object') {
+      throw new Error('DyFM_StateMachine: config object required');
+    }
+    if (typeof config.initial !== 'string') {
+      throw new Error('DyFM_StateMachine: config.initial must be a string state value');
+    }
+    if (!Array.isArray(config.transitions) || config.transitions.length === 0) {
+      throw new Error('DyFM_StateMachine: config.transitions must be a non-empty array');
+    }
+    this._config = config;
+    this._state = config.initial;
+    this._state$ = new BehaviorSubject<TState>(this._state);
+    this.state$ = this._state$.asObservable();
+    this._events$ = new Subject<DyFM_StateMachineEvent<TState, TContext>>();
+    this.events$ = this._events$.asObservable();
+  }
+
+
+  /**
+   * Sync getter — az aktualis state.
+   */
+  state(): TState {
+    return this._state;
+  }
+
+  /**
+   * Sync getter — az aktualis state-version.
+   */
+  stateVersion(): number {
+    return this._stateVersion;
+  }
+
+  /**
+   * Megnezi hogy van-e olyan transition ami a jelenlegi state-bol a kert
+   * `to`-ba vezet, ES (ha van guard) a guard `true`-t adna a kontextusra.
+   *
+   * NEM fut le onLeave / onEnter / persist callback.
+   */
+  async canTransition(to: TState, ctx?: TContext): Promise<boolean> {
+    const transition: DyFM_StateTransition<TState, TContext> | undefined =
+      this._findTransition(this._state, to);
+    if (!transition) { return false; }
+    if (transition.guard) {
+      try {
+        const guardResult: boolean = await transition.guard(ctx);
+        return guardResult === true;
+      } catch {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  /**
+   * Atmenet vegrehajtasa a kert `to` state-re.
+   *
+   * Flow:
+   *  1. Mutex-acquire — soros vegrehajtas egy instance-en
+   *  2. Transition-keres (`_findTransition`); ha nincs → `invalid-transition`
+   *  3. `guard(ctx)` — ha false → `guard-rejected`
+   *  4. `onLeave(ctx)` — throw → `on-leave-failed` (state meg NEM valtozott)
+   *  5. State + version frissites, `state$.next()` emit
+   *  6. `onEnter(ctx)` — throw → revert state + `on-enter-failed`
+   *  7. `persist(event)` if configured — throw → revert state + `persist-failed`
+   *  8. `events$.next(event)` emit
+   *  9. Mutex-release, return ok
+   */
+  async transition(
+    to: TState,
+    ctx?: TContext,
+  ): Promise<DyFM_StateMachineTransition_Result<TState>> {
+    const release: { resolve: () => void } = { resolve: (): void => { /* noop */ } };
+    const myTurn: Promise<void> = new Promise<void>((res: () => void): void => {
+      release.resolve = res;
+    });
+    const prevTail: Promise<unknown> = this._mutexTail;
+    this._mutexTail = myTurn;
+    try {
+      await prevTail;
+      return await this._transitionInternal(to, ctx);
+    } finally {
+      release.resolve();
+    }
+  }
+
+
+  /** Mutex-protected belso transition logika. */
+  private async _transitionInternal(
+    to: TState,
+    ctx?: TContext,
+  ): Promise<DyFM_StateMachineTransition_Result<TState>> {
+    const from: TState = this._state;
+
+    // 1. Transition lookup
+    const transition: DyFM_StateTransition<TState, TContext> | undefined =
+      this._findTransition(from, to);
+    if (!transition) {
+      return this._failure(from, to, 'invalid-transition');
+    }
+
+    // 2. Guard check
+    if (transition.guard) {
+      let guardResult: boolean;
+      try {
+        guardResult = await transition.guard(ctx);
+      } catch (err: unknown) {
+        return this._failure(from, to, 'guard-rejected', err as Error);
+      }
+      if (guardResult !== true) {
+        return this._failure(from, to, 'guard-rejected');
+      }
+    }
+
+    // 3. onLeave (pre-change)
+    if (transition.onLeave) {
+      try {
+        await transition.onLeave(ctx);
+      } catch (err: unknown) {
+        return this._failure(from, to, 'on-leave-failed', err as Error);
+      }
+    }
+
+    // 4. State + version transition (the actual change)
+    const newVersion: number = this._stateVersion + 1;
+    this._state = to;
+    this._stateVersion = newVersion;
+    this._state$.next(this._state);
+
+    // 5. onEnter (post-change, pre-persist)
+    if (transition.onEnter) {
+      try {
+        await transition.onEnter(ctx);
+      } catch (err: unknown) {
+        // Revert
+        this._state = from;
+        this._stateVersion = newVersion - 1;
+        this._state$.next(this._state);
+        return this._failure(from, to, 'on-enter-failed', err as Error);
+      }
+    }
+
+    // 6. Persist (post-state-change, post-onEnter)
+    const event: DyFM_StateMachineEvent<TState, TContext> = {
+      from: from,
+      to: to,
+      stateVersion: newVersion,
+      context: ctx,
+      timestamp: Date.now(),
+    };
+    if (this._config.persist) {
+      try {
+        await this._config.persist(event);
+      } catch (err: unknown) {
+        // Revert
+        this._state = from;
+        this._stateVersion = newVersion - 1;
+        this._state$.next(this._state);
+        return this._failure(from, to, 'persist-failed', err as Error);
+      }
+    }
+
+    // 7. Emit event
+    this._events$.next(event);
+
+    return {
+      ok: true,
+      from: from,
+      to: to,
+      stateVersion: newVersion,
+    };
+  }
+
+
+  /**
+   * Lookup: a `transitions[]` listaban olyat keres, aminek `from` matchel a
+   * `current`-tel (vagy `'*'` wildcard), ES `to` matchel a `target`-tel.
+   *
+   * Az elso talalatot adja vissza (a kepes ezert a config-ban a specifikusabb
+   * jojjon eloszor a wildcardnel — de a peldakban a wildcard tartalmazza az
+   * 'invalidat' is, igy az ordering MUST nem szigoru a tipikus eseteknel).
+   */
+  private _findTransition(
+    current: TState,
+    target: TState,
+  ): DyFM_StateTransition<TState, TContext> | undefined {
+    for (const t of this._config.transitions) {
+      if (t.to !== target) { continue; }
+      if (t.from === '*') { return t; }
+      if (Array.isArray(t.from)) {
+        if (t.from.includes(current)) { return t; }
+      } else if (t.from === current) {
+        return t;
+      }
+    }
+    return undefined;
+  }
+
+  /**
+   * Belso helper a sikertelen result epitesere.
+   */
+  private _failure(
+    from: TState,
+    attemptedTo: TState,
+    reason: DyFM_StateMachineTransition_FailureReason,
+    error?: Error,
+  ): DyFM_StateMachineTransition_Result<TState> {
+    return {
+      ok: false,
+      reason: reason,
+      currentState: this._state,
+      attemptedTo: attemptedTo,
+      error: error,
+    };
+  }
+}

package/src/_modules/state-machine/_models/state-transition-result.interface.ts

@@ -0,0 +1,53 @@
+import { DyFM_Error } from '../../../_models/control-models/error.control-model';
+
+/**
+ * Failure reason-ok a `DyFM_StateMachineTransition_Result.reason` mezohoz.
+ *
+ *  - `invalid-transition`: nincs olyan transition a config-ban ami a jelenlegi
+ *    state-bol a kert `to`-ba vezet.
+ *  - `guard-rejected`: a transition `guard` callback-je `false`-t adott.
+ *  - `on-leave-failed`: a transition `onLeave` callback-je throw-olt; state NEM valtozott.
+ *  - `on-enter-failed`: az `onEnter` callback throw-olt az uj state beallitasa utan; state revert-elve a from-ra.
+ *  - `persist-failed`: a `persist` callback throw-olt; state revert-elve a from-ra.
+ */
+export type DyFM_StateMachineTransition_FailureReason =
+  | 'invalid-transition'
+  | 'guard-rejected'
+  | 'on-leave-failed'
+  | 'on-enter-failed'
+  | 'persist-failed';
+
+
+/**
+ * Sikeres atmenet eredmenye.
+ */
+export interface DyFM_StateMachineTransition_SuccessResult<TState extends string> {
+  ok: true;
+  from: TState;
+  to: TState;
+  /** A frissitett state-version szam (>= 1). */
+  stateVersion: number;
+}
+
+
+/**
+ * Sikertelen atmenet eredmenye.
+ */
+export interface DyFM_StateMachineTransition_FailureResult<TState extends string> {
+  ok: false;
+  reason: DyFM_StateMachineTransition_FailureReason;
+  /** A jelenlegi state amikor a sikertelenseg torent. */
+  currentState: TState;
+  /** A megkiserelt cel-state. */
+  attemptedTo: TState;
+  /** Opcionalis hiba ha az atmenet error-ral bukott (pl. on-enter throw, persist throw). */
+  error?: DyFM_Error | Error;
+}
+
+
+/**
+ * Discriminated union — `ok` flag-gel branchol.
+ */
+export type DyFM_StateMachineTransition_Result<TState extends string> =
+  | DyFM_StateMachineTransition_SuccessResult<TState>
+  | DyFM_StateMachineTransition_FailureResult<TState>;