@mostajs/statemachine 0.0.1

package/LICENSE

@@ -0,0 +1,15 @@
+@mostajs/statemachine
+Copyright (C) 2026 Dr Hamid MADANI <drmdh@msn.com>
+
+This program is free software: you can redistribute it and/or modify it under
+the terms of the GNU Affero General Public License as published by the Free
+Software Foundation, either version 3 of the License, or (at your option) any
+later version.
+
+This program is distributed in the hope that it will be useful, but WITHOUT
+ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
+details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program. If not, see <https://www.gnu.org/licenses/agpl-3.0.html>.

package/README.md

@@ -0,0 +1,67 @@
+# @mostajs/statemachine
+
+> Machine à états finie **pure** — transitions de configuration (`from[]→to` + permission + **garde injectée**) et **historique immuable** des transitions exécutées (via `AuditSink` injecté). La brique **STATE** du triptyque **State · Rule · Trigger** (modèle Drupal *Workflow*).
+
+**Auteur** : Dr Hamid MADANI <drmdh@msn.com> · **Licence** : AGPL-3.0-or-later
+
+Primitive de l'écosystème `@mostajs/*`. Reste **pure** : la garde (→ `@mostajs/rules`), la permission (→ `@mostajs/rbac`) et le journal (→ `@mostajs/audit`) sont **injectés**. La stack `@mostajs/workflow` les assemble.
+
+## Installation
+
+```bash
+npm i @mostajs/statemachine
+```
+
+Le cœur n'a **aucune dépendance**. Les adaptateurs réels (`@mostajs/audit`, `@mostajs/rbac`) arrivent en v0.1.
+
+## Exemple (cycle de commande)
+
+```ts
+import { defineMachine } from "@mostajs/statemachine";
+
+const m = defineMachine({
+  states: [
+    { id: "nouvelle", initial: true },
+    { id: "en_cours" },
+    { id: "validee" },
+    { id: "terminee", terminal: true },
+    { id: "annulee", terminal: true },
+  ],
+  transitions: [
+    { id: "start",  from: ["nouvelle"], to: "en_cours" },
+    { id: "valid",  from: ["en_cours"], to: "validee", guard: (c) => c.data?.ok === true },
+    { id: "finish", from: ["validee"],  to: "terminee" },
+    { id: "cancel", from: ["nouvelle", "en_cours", "validee"], to: "annulee", permission: "crm.order.transition.cancel" },
+  ],
+});
+
+const ref = { entityType: "order", entityId: "42" };
+await m.transition(ref, "nouvelle", "en_cours", { actorId: "u1", comment: "prise en charge" });
+await m.canTransition("en_cours", "validee", { data: { ok: false } }); // { allowed:false, reason:"guard" }
+await m.history(ref); // historique immuable (qui / quand / from→to / comment)
+```
+
+## Modèle (distinction Drupal config / exécution)
+
+| Concept | Type |
+|---|---|
+| chemin autorisé | `ConfigTransition { id, from: string[], to, permission?, guard? }` |
+| transition exécutée (immuable) | `ExecutedTransition { entityType, entityId, fromState, toState, actorId?, timestamp, comment? }` |
+| journal append-only | `AuditSink { record, list }` |
+
+## Injections (composition)
+
+| Capacité | Injection | Module cible |
+|---|---|---|
+| historique immuable | `audit` | `@mostajs/audit` |
+| permission par transition | `checkPermission` | `@mostajs/rbac` |
+| garde déclarative | `guard` (par transition) | `@mostajs/rules` |
+| date | `now` | testabilité |
+
+## API
+
+`defineMachine(def, opts?)` → `Machine` · `m.availableTransitions(current, input?)` · `m.canTransition(from, to, input?)` → `{ allowed, reason? }` · `m.transition(ref, from, to, input?)` → `ExecutedTransition` · `m.history(ref)` · `m.onPre/onPost`. `input = { actorId?, data?, comment? }`.
+
+## Statut
+
+**v0.0.1** — cœur **implémenté et testé** (`defineMachine`, `can/transition`, gardes, `MemoryAuditSink`, hooks `pre/post`). Feuille de route : `docs/03-PLAN-DEV-STATEMACHINE.md` (0.1 adaptateurs `audit`/`rbac`, 1.0 = 14 livrables). Étude : `docs/01-ETUDE-ETAT-ART-STATEMACHINE-07062026.md`.

package/dist/audit.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @mostajs/statemachine — journal d'exécution en mémoire (défaut / tests).
+ *
+ * Append-only et immuable : aucune API d'édition/suppression n'est exposée ;
+ * `list` retourne des copies. En production, brancher un adaptateur sur
+ * @mostajs/audit (et **ne jamais** câbler sa purge `deleteOlderThan`).
+ *
+ * @author Dr Hamid MADANI <drmdh@msn.com>
+ * @license AGPL-3.0-or-later
+ */
+import { type AuditSink, type ExecutedTransition, type EntityRef } from "./types.js";
+export declare class MemoryAuditSink implements AuditSink {
+    private readonly log;
+    record(transition: ExecutedTransition): Promise<void>;
+    list(ref: EntityRef): Promise<ExecutedTransition[]>;
+}
+//# sourceMappingURL=audit.d.ts.map

package/dist/audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../src/audit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,kBAAkB,EAAE,KAAK,SAAS,EAAE,MAAM,YAAY,CAAC;AAErF,qBAAa,eAAgB,YAAW,SAAS;IAC/C,OAAO,CAAC,QAAQ,CAAC,GAAG,CAA4B;IAE1C,MAAM,CAAC,UAAU,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IAIrD,IAAI,CAAC,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC;CAK1D"}

package/dist/audit.js

@@ -0,0 +1,22 @@
+/**
+ * @mostajs/statemachine — journal d'exécution en mémoire (défaut / tests).
+ *
+ * Append-only et immuable : aucune API d'édition/suppression n'est exposée ;
+ * `list` retourne des copies. En production, brancher un adaptateur sur
+ * @mostajs/audit (et **ne jamais** câbler sa purge `deleteOlderThan`).
+ *
+ * @author Dr Hamid MADANI <drmdh@msn.com>
+ * @license AGPL-3.0-or-later
+ */
+export class MemoryAuditSink {
+    log = [];
+    async record(transition) {
+        this.log.push({ ...transition });
+    }
+    async list(ref) {
+        return this.log
+            .filter((e) => e.entityType === ref.entityType && e.entityId === ref.entityId)
+            .map((e) => ({ ...e }));
+    }
+}
+//# sourceMappingURL=audit.js.map

package/dist/audit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.js","sourceRoot":"","sources":["../src/audit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,MAAM,OAAO,eAAe;IACT,GAAG,GAAyB,EAAE,CAAC;IAEhD,KAAK,CAAC,MAAM,CAAC,UAA8B;QACzC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,GAAG,UAAU,EAAE,CAAC,CAAC;IACnC,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,GAAc;QACvB,OAAO,IAAI,CAAC,GAAG;aACZ,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,KAAK,GAAG,CAAC,UAAU,IAAI,CAAC,CAAC,QAAQ,KAAK,GAAG,CAAC,QAAQ,CAAC;aAC7E,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;IAC5B,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @mostajs/statemachine — point d'entrée public.
+ *
+ * Machine à états finie pure (STATE du triptyque State·Rule·Trigger). Transitions
+ * de config (from[]→to + permission + garde injectée), historique immuable délégué
+ * à un AuditSink. Assemblée par la stack @mostajs/workflow.
+ *
+ * @author Dr Hamid MADANI <drmdh@msn.com>
+ * @license AGPL-3.0-or-later
+ */
+export { type State, type EntityRef, type GuardContext, type Guard, type ConfigTransition, type ExecutedTransition, type AuditSink, type PermissionCheck, type MachineDef, type DenyReason, type CanResult, StateMachineError, UnknownStateError, InvalidTransitionError, TerminalStateError, GuardDeniedError, PermissionDeniedError, } from "./types.js";
+export { MemoryAuditSink } from "./audit.js";
+export { Machine, defineMachine, type MachineOptions, type TransitionInput, } from "./machine.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EACL,KAAK,KAAK,EACV,KAAK,SAAS,EACd,KAAK,YAAY,EACjB,KAAK,KAAK,EACV,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,SAAS,EACd,KAAK,eAAe,EACpB,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,SAAS,EACd,iBAAiB,EACjB,iBAAiB,EACjB,sBAAsB,EACtB,kBAAkB,EAClB,gBAAgB,EAChB,qBAAqB,GACtB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EACL,OAAO,EACP,aAAa,EACb,KAAK,cAAc,EACnB,KAAK,eAAe,GACrB,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,14 @@
+/**
+ * @mostajs/statemachine — point d'entrée public.
+ *
+ * Machine à états finie pure (STATE du triptyque State·Rule·Trigger). Transitions
+ * de config (from[]→to + permission + garde injectée), historique immuable délégué
+ * à un AuditSink. Assemblée par la stack @mostajs/workflow.
+ *
+ * @author Dr Hamid MADANI <drmdh@msn.com>
+ * @license AGPL-3.0-or-later
+ */
+export { StateMachineError, UnknownStateError, InvalidTransitionError, TerminalStateError, GuardDeniedError, PermissionDeniedError, } from "./types.js";
+export { MemoryAuditSink } from "./audit.js";
+export { Machine, defineMachine, } from "./machine.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAYL,iBAAiB,EACjB,iBAAiB,EACjB,sBAAsB,EACtB,kBAAkB,EAClB,gBAAgB,EAChB,qBAAqB,GACtB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EACL,OAAO,EACP,aAAa,GAGd,MAAM,cAAc,CAAC"}

package/dist/machine.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @mostajs/statemachine — façade `Machine` + `defineMachine`.
+ *
+ * FSM pure : garde et permission **injectées**, historique **délégué** à un
+ * `AuditSink`. Aucune dépendance dure à @mostajs/rules ni @mostajs/trigger —
+ * c'est la stack @mostajs/workflow qui les branche.
+ *
+ * @author Dr Hamid MADANI <drmdh@msn.com>
+ * @license AGPL-3.0-or-later
+ */
+import { type MachineDef, type State, type ConfigTransition, type ExecutedTransition, type EntityRef, type AuditSink, type PermissionCheck, type CanResult } from "./types.js";
+export interface MachineOptions {
+    /** Journal d'exécution (défaut : `MemoryAuditSink`). */
+    audit?: AuditSink;
+    /** Vérificateur de permission (optionnel ; sans lui, `permission` reste déclaratif). */
+    checkPermission?: PermissionCheck;
+    /** Horloge injectée (testabilité ; défaut : `() => new Date()`). */
+    now?: () => Date;
+}
+export interface TransitionInput {
+    actorId?: string;
+    data?: Record<string, unknown>;
+    comment?: string;
+}
+type Hook = (t: ExecutedTransition) => void | Promise<void>;
+export declare class Machine {
+    readonly states: ReadonlyMap<string, State>;
+    readonly initial: string;
+    private readonly transitions;
+    private readonly audit;
+    private readonly checkPermission?;
+    private readonly now;
+    private readonly preHooks;
+    private readonly postHooks;
+    constructor(def: MachineDef, opts?: MachineOptions);
+    private isTerminal;
+    private find;
+    /** Transitions praticables depuis `current` (chemin + permission + garde évalués). */
+    availableTransitions(current: string, input?: TransitionInput): Promise<ConfigTransition[]>;
+    /** Indique si une transition `from→to` est autorisée et, sinon, pourquoi. */
+    canTransition(from: string, to: string, input?: TransitionInput): Promise<CanResult>;
+    /** Exécute une transition : valide, émet `pre`, journalise (immuable), émet `post`. */
+    transition(ref: EntityRef, from: string, to: string, input?: TransitionInput): Promise<ExecutedTransition>;
+    /** Historique chronologique immuable de l'entité (ordre d'insertion). */
+    history(ref: EntityRef): Promise<ExecutedTransition[]>;
+    onPre(fn: Hook): this;
+    onPost(fn: Hook): this;
+    private denyError;
+}
+/** Définit (et valide) une machine à états. */
+export declare function defineMachine(def: MachineDef, opts?: MachineOptions): Machine;
+export {};
+//# sourceMappingURL=machine.d.ts.map

package/dist/machine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"machine.d.ts","sourceRoot":"","sources":["../src/machine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EACL,KAAK,UAAU,EACf,KAAK,KAAK,EACV,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,SAAS,EAEd,KAAK,SAAS,EACd,KAAK,eAAe,EACpB,KAAK,SAAS,EAOf,MAAM,YAAY,CAAC;AAGpB,MAAM,WAAW,cAAc;IAC7B,wDAAwD;IACxD,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,wFAAwF;IACxF,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,oEAAoE;IACpE,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,KAAK,IAAI,GAAG,CAAC,CAAC,EAAE,kBAAkB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE5D,qBAAa,OAAO;IAClB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAC5C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAqB;IACjD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAY;IAClC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAkB;IACnD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAa;IACjC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAc;IACvC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAc;gBAE5B,GAAG,EAAE,UAAU,EAAE,IAAI,GAAE,cAAmB;IAgCtD,OAAO,CAAC,UAAU;IAIlB,OAAO,CAAC,IAAI;IAIZ,sFAAsF;IAChF,oBAAoB,CACxB,OAAO,EAAE,MAAM,EACf,KAAK,GAAE,eAAoB,GAC1B,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAY9B,6EAA6E;IACvE,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,GAAE,eAAoB,GAAG,OAAO,CAAC,SAAS,CAAC;IAoB9F,uFAAuF;IACjF,UAAU,CACd,GAAG,EAAE,SAAS,EACd,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,EACV,KAAK,GAAE,eAAoB,GAC1B,OAAO,CAAC,kBAAkB,CAAC;IAsB9B,yEAAyE;IACzE,OAAO,CAAC,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAItD,KAAK,CAAC,EAAE,EAAE,IAAI,GAAG,IAAI;IAIrB,MAAM,CAAC,EAAE,EAAE,IAAI,GAAG,IAAI;IAKtB,OAAO,CAAC,SAAS;CAgBlB;AAED,+CAA+C;AAC/C,wBAAgB,aAAa,CAAC,GAAG,EAAE,UAAU,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,OAAO,CAE7E"}

package/dist/machine.js

@@ -0,0 +1,157 @@
+/**
+ * @mostajs/statemachine — façade `Machine` + `defineMachine`.
+ *
+ * FSM pure : garde et permission **injectées**, historique **délégué** à un
+ * `AuditSink`. Aucune dépendance dure à @mostajs/rules ni @mostajs/trigger —
+ * c'est la stack @mostajs/workflow qui les branche.
+ *
+ * @author Dr Hamid MADANI <drmdh@msn.com>
+ * @license AGPL-3.0-or-later
+ */
+import { StateMachineError, UnknownStateError, InvalidTransitionError, TerminalStateError, GuardDeniedError, PermissionDeniedError, } from "./types.js";
+import { MemoryAuditSink } from "./audit.js";
+export class Machine {
+    states;
+    initial;
+    transitions;
+    audit;
+    checkPermission;
+    now;
+    preHooks = [];
+    postHooks = [];
+    constructor(def, opts = {}) {
+        if (!def.states?.length)
+            throw new StateMachineError("Machine sans état.");
+        const states = new Map();
+        for (const s of def.states) {
+            if (states.has(s.id))
+                throw new StateMachineError(`État dupliqué : "${s.id}"`);
+            states.set(s.id, s);
+        }
+        const initials = def.states.filter((s) => s.initial);
+        if (initials.length !== 1) {
+            throw new StateMachineError(`Exactement un état initial requis (trouvé : ${initials.length}).`);
+        }
+        // Validation des transitions : états connus + dédup (from,to).
+        const seen = new Set();
+        for (const t of def.transitions) {
+            if (!states.has(t.to))
+                throw new UnknownStateError(`Transition "${t.id}" : état cible inconnu "${t.to}".`);
+            for (const f of t.from) {
+                if (!states.has(f))
+                    throw new UnknownStateError(`Transition "${t.id}" : état source inconnu "${f}".`);
+                const key = `${f}->${t.to}`;
+                if (seen.has(key))
+                    throw new InvalidTransitionError(`Transition dupliquée : ${key}`);
+                seen.add(key);
+            }
+        }
+        this.states = states;
+        this.initial = initials[0].id;
+        this.transitions = def.transitions;
+        this.audit = opts.audit ?? new MemoryAuditSink();
+        this.checkPermission = opts.checkPermission;
+        this.now = opts.now ?? (() => new Date());
+    }
+    isTerminal(id) {
+        return this.states.get(id)?.terminal === true;
+    }
+    find(from, to) {
+        return this.transitions.find((t) => t.to === to && t.from.includes(from));
+    }
+    /** Transitions praticables depuis `current` (chemin + permission + garde évalués). */
+    async availableTransitions(current, input = {}) {
+        if (!this.states.has(current))
+            throw new UnknownStateError(`État inconnu : "${current}".`);
+        if (this.isTerminal(current))
+            return [];
+        const out = [];
+        for (const t of this.transitions) {
+            if (!t.from.includes(current))
+                continue;
+            const res = await this.canTransition(current, t.to, input);
+            if (res.allowed)
+                out.push(t);
+        }
+        return out;
+    }
+    /** Indique si une transition `from→to` est autorisée et, sinon, pourquoi. */
+    async canTransition(from, to, input = {}) {
+        if (!this.states.has(from) || !this.states.has(to)) {
+            return { allowed: false, reason: "unknown-state" };
+        }
+        if (this.isTerminal(from))
+            return { allowed: false, reason: "terminal" };
+        const t = this.find(from, to);
+        if (!t)
+            return { allowed: false, reason: "no-path" };
+        const ctx = { from, to, actorId: input.actorId, data: input.data };
+        if (t.permission && this.checkPermission) {
+            const ok = await this.checkPermission(input.actorId, t.permission, ctx);
+            if (!ok)
+                return { allowed: false, reason: "permission" };
+        }
+        if (t.guard) {
+            const ok = await t.guard(ctx); // deny-by-default : falsy => refus
+            if (!ok)
+                return { allowed: false, reason: "guard" };
+        }
+        return { allowed: true };
+    }
+    /** Exécute une transition : valide, émet `pre`, journalise (immuable), émet `post`. */
+    async transition(ref, from, to, input = {}) {
+        const res = await this.canTransition(from, to, input);
+        if (!res.allowed)
+            throw this.denyError(res.reason, from, to);
+        const t = this.find(from, to);
+        const executed = {
+            entityType: ref.entityType,
+            entityId: ref.entityId,
+            fromState: from,
+            toState: to,
+            actorId: input.actorId,
+            timestamp: this.now().toISOString(),
+            comment: input.comment,
+            transitionId: t.id,
+        };
+        for (const h of this.preHooks)
+            await h(executed); // un hook peut lever pour vétoer
+        await this.audit.record(executed);
+        for (const h of this.postHooks)
+            await h(executed);
+        return executed;
+    }
+    /** Historique chronologique immuable de l'entité (ordre d'insertion). */
+    history(ref) {
+        return this.audit.list(ref);
+    }
+    onPre(fn) {
+        this.preHooks.push(fn);
+        return this;
+    }
+    onPost(fn) {
+        this.postHooks.push(fn);
+        return this;
+    }
+    denyError(reason, from, to) {
+        const path = `${from} → ${to}`;
+        switch (reason) {
+            case "terminal":
+                return new TerminalStateError(`État terminal : aucune transition depuis "${from}".`);
+            case "permission":
+                return new PermissionDeniedError(`Permission refusée pour ${path}.`);
+            case "guard":
+                return new GuardDeniedError(`Garde refusée pour ${path}.`);
+            case "unknown-state":
+                return new UnknownStateError(`État inconnu dans ${path}.`);
+            case "no-path":
+            default:
+                return new InvalidTransitionError(`Transition non autorisée : ${path}.`);
+        }
+    }
+}
+/** Définit (et valide) une machine à états. */
+export function defineMachine(def, opts) {
+    return new Machine(def, opts);
+}
+//# sourceMappingURL=machine.js.map

package/dist/machine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"machine.js","sourceRoot":"","sources":["../src/machine.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,88 @@
+/**
+ * @mostajs/statemachine — types publics (modèle Drupal Workflow : config vs exécution).
+ *
+ * @author Dr Hamid MADANI <drmdh@msn.com>
+ * @license AGPL-3.0-or-later
+ */
+/** Un état de la machine. `initial`/`terminal` marquent l'entrée et les puits ; `weight` ordonne ; `status=false` = désactivé. */
+export interface State {
+    id: string;
+    label?: string;
+    weight?: number;
+    initial?: boolean;
+    terminal?: boolean;
+    status?: boolean;
+    /** Code couleur de présentation (badge/kanban) — métadonnée d'UI, ex. `"#3B82F6"`. */
+    color?: string;
+    /** Métadonnées de domaine libres (ex. `{ party: "sender" | "receiver", initiators: [...] }`). */
+    meta?: Record<string, unknown>;
+}
+/** Référence d'une entité métier suivie (ex. une commande). */
+export interface EntityRef {
+    entityType: string;
+    entityId: string;
+}
+/** Contexte fourni aux gardes et au checker de permission. */
+export interface GuardContext {
+    from: string;
+    to: string;
+    actorId?: string;
+    data?: Record<string, unknown>;
+}
+/** Garde de transition (prédicat **injecté** — typiquement délégué à @mostajs/rules). Falsy = refus. */
+export type Guard = (ctx: GuardContext) => boolean | Promise<boolean>;
+/**
+ * Transition de **configuration** (chemin autorisé). Modèle Drupal : plusieurs `from` → un `to`.
+ * `permission` = clé RBAC ; `guard` = prédicat injecté.
+ */
+export interface ConfigTransition {
+    id: string;
+    from: string[];
+    to: string;
+    label?: string;
+    permission?: string;
+    guard?: Guard;
+}
+/** Transition **exécutée** (entrée d'historique immuable : qui / quand / ancien→nouveau / commentaire). */
+export interface ExecutedTransition {
+    entityType: string;
+    entityId: string;
+    fromState: string;
+    toState: string;
+    actorId?: string;
+    timestamp: string;
+    comment?: string;
+    transitionId?: string;
+}
+/** Journal d'exécution **append-only** (immuable). En prod : adaptateur @mostajs/audit. */
+export interface AuditSink {
+    record(transition: ExecutedTransition): Promise<void>;
+    list(ref: EntityRef): Promise<ExecutedTransition[]>;
+}
+/** Vérificateur de permission **injecté** (typiquement @mostajs/rbac). */
+export type PermissionCheck = (actorId: string | undefined, permission: string, ctx: GuardContext) => boolean | Promise<boolean>;
+/** Définition d'une machine : ses états et ses transitions de configuration. */
+export interface MachineDef {
+    states: State[];
+    transitions: ConfigTransition[];
+}
+/** Raison d'un refus de transition. */
+export type DenyReason = "unknown-state" | "no-path" | "terminal" | "permission" | "guard";
+export interface CanResult {
+    allowed: boolean;
+    reason?: DenyReason;
+}
+export declare class StateMachineError extends Error {
+    constructor(message: string);
+}
+export declare class UnknownStateError extends StateMachineError {
+}
+export declare class InvalidTransitionError extends StateMachineError {
+}
+export declare class TerminalStateError extends StateMachineError {
+}
+export declare class GuardDeniedError extends StateMachineError {
+}
+export declare class PermissionDeniedError extends StateMachineError {
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,24 @@
+/**
+ * @mostajs/statemachine — types publics (modèle Drupal Workflow : config vs exécution).
+ *
+ * @author Dr Hamid MADANI <drmdh@msn.com>
+ * @license AGPL-3.0-or-later
+ */
+// ─── Erreurs typées ──────────────────────────────────────────────────────────
+export class StateMachineError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = new.target.name;
+    }
+}
+export class UnknownStateError extends StateMachineError {
+}
+export class InvalidTransitionError extends StateMachineError {
+}
+export class TerminalStateError extends StateMachineError {
+}
+export class GuardDeniedError extends StateMachineError {
+}
+export class PermissionDeniedError extends StateMachineError {
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA0FH,gFAAgF;AAChF,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAC1C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC;IAC9B,CAAC;CACF;AACD,MAAM,OAAO,iBAAkB,SAAQ,iBAAiB;CAAG;AAC3D,MAAM,OAAO,sBAAuB,SAAQ,iBAAiB;CAAG;AAChE,MAAM,OAAO,kBAAmB,SAAQ,iBAAiB;CAAG;AAC5D,MAAM,OAAO,gBAAiB,SAAQ,iBAAiB;CAAG;AAC1D,MAAM,OAAO,qBAAsB,SAAQ,iBAAiB;CAAG"}

package/llms.txt

@@ -0,0 +1,77 @@
+# @mostajs/statemachine — fiche LLM
+
+RÔLE
+  Machine à états finie PURE = la brique STATE du triptyque State·Rule·Trigger
+  (inspiré du module Drupal Workflow). Définit états + transitions de configuration
+  (from[]→to + permission + garde INJECTÉE), exécute une transition et JOURNALISE
+  immuablement (qui/quand/ancien→nouveau/commentaire) via un AuditSink INJECTÉ.
+  NE FAIT PAS : évaluer les règles (→ @mostajs/rules, garde injectée), événements/actions
+  (→ @mostajs/trigger), assemblage (→ stack @mostajs/workflow), persistance de l'état métier
+  (→ consommateur). Pure : aucune dépendance dure à rules/trigger. Responsabilité unique.
+
+MODÈLE (Drupal Workflow : config vs exécution)
+  State { id, label?, weight?, initial?, terminal?, status? }
+  ConfigTransition { id, from: string[], to, label?, permission?, guard? }   # plusieurs from -> un to
+  ExecutedTransition { entityType, entityId, fromState, toState, actorId?, timestamp, comment?, transitionId? }  # immuable
+  AuditSink { record(t): Promise<void>; list(ref): Promise<ExecutedTransition[]> }   # append-only
+  PermissionCheck(actorId, permission, ctx) -> boolean|Promise<boolean>             # injecté (rbac)
+  Guard(ctx) -> boolean|Promise<boolean>                                            # injecté (rules) ; falsy = refus
+  EntityRef { entityType, entityId }
+
+INSTALL
+  npm i @mostajs/statemachine        # cœur sans dépendance ; audit/permission/guard injectés
+
+EXPORTS
+  defineMachine(def, opts?) -> Machine     # opts: { audit?, checkPermission?, now? }
+  Machine :
+    states: ReadonlyMap<string,State> ; initial: string
+    availableTransitions(current, input?) -> Promise<ConfigTransition[]>
+    canTransition(from, to, input?) -> Promise<{ allowed, reason? }>
+    transition(ref, from, to, input?) -> Promise<ExecutedTransition>   # émet pre -> record -> post
+    history(ref) -> Promise<ExecutedTransition[]>
+    onPre(fn) / onPost(fn)
+  MemoryAuditSink                          # défaut / tests (append-only, immuable)
+  Types + erreurs : StateMachineError, UnknownStateError, InvalidTransitionError,
+                    TerminalStateError, GuardDeniedError, PermissionDeniedError
+  input (TransitionInput) = { actorId?, data?, comment? }
+  reason (DenyReason) = "unknown-state" | "no-path" | "terminal" | "permission" | "guard"
+
+EXEMPLE (commande CRM, 8 états)
+  import { defineMachine } from "@mostajs/statemachine";
+  const m = defineMachine({
+    states: [
+      { id: "nouvelle", initial: true }, { id: "en_cours" }, { id: "validee" },
+      { id: "terminee", terminal: true }, { id: "annulee", terminal: true },
+    ],
+    transitions: [
+      { id: "start",  from: ["nouvelle"], to: "en_cours" },
+      { id: "valid",  from: ["en_cours"], to: "validee", guard: (c) => c.data?.ok === true },
+      { id: "finish", from: ["validee"],  to: "terminee" },
+      { id: "cancel", from: ["nouvelle","en_cours","validee"], to: "annulee", permission: "crm.order.transition.cancel" },
+    ],
+  });
+  const ref = { entityType: "order", entityId: "42" };
+  await m.canTransition("nouvelle", "en_cours");            // { allowed: true }
+  await m.transition(ref, "nouvelle", "en_cours", { actorId: "u1" });
+  await m.canTransition("en_cours", "validee", { data: { ok: false } }); // { allowed:false, reason:"guard" }
+  await m.history(ref);                                     // [ ExecutedTransition... ] immuable
+
+COMPOSITION
+  - Historique : @mostajs/audit (adaptateur AuditSink en prod ; ne JAMAIS câbler deleteOlderThan).
+  - Permission par transition : @mostajs/rbac (PermissionCheck injecté).
+  - Garde déclarative : @mostajs/rules (guard injectée, par la stack workflow).
+  - Assemblage : @mostajs/workflow branche garde->rules, pre/post->trigger, historique->audit.
+
+PIÈGES
+  - Toutes les opérations sont ASYNCHRONES.
+  - Garde deny-by-default : une garde renvoyant falsy refuse la transition (GuardDeniedError).
+  - États terminaux : aucune transition sortante (TerminalStateError).
+  - Exactement UN état initial requis ; transitions dédupliquées sur (from,to) à la définition.
+  - `permission` déclarée mais sans checkPermission injecté => NON enforcée (métadonnée) ; brancher rbac pour l'appliquer.
+  - Historique IMMUABLE : MemoryAuditSink est append-only, list() renvoie des copies ; ne pas exposer d'édition.
+  - Date injectée (now) pour la testabilité.
+
+STATUT
+  v0.0.1 — cœur IMPLÉMENTÉ (defineMachine, can/transition, gardes, MemoryAuditSink, hooks), testé.
+  v0.1 = adaptateurs réels @mostajs/audit + @mostajs/rbac. Voir docs/03-PLAN-DEV-STATEMACHINE.md.
+  Licence AGPL-3.0-or-later. Auteur Dr Hamid MADANI.

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@mostajs/statemachine",
+  "version": "0.0.1",
+  "description": "Pure finite state machine — config transitions (from[]→to + permission + injected guard) and immutable executed-transition history (via injected AuditSink). The STATE primitive of the State·Rule·Trigger triptych, assembled by @mostajs/workflow.",
+  "author": "Dr Hamid MADANI <drmdh@msn.com>",
+  "license": "AGPL-3.0-or-later",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md",
+    "llms.txt"
+  ],
+  "keywords": [
+    "state-machine",
+    "fsm",
+    "workflow",
+    "transition",
+    "guard",
+    "audit-trail",
+    "immutable-history",
+    "mosta",
+    "mostajs"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/apolocine/mosta-statemachine"
+  },
+  "homepage": "https://mostajs.dev/packages/statemachine",
+  "bugs": {
+    "url": "https://github.com/apolocine/mosta-statemachine/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "node --test test-scripts/*.test.mjs"
+  }
+}