@sebasoft/neuron-js 0.3.0 → 0.5.0

package/README.md

@@ -1,28 +1,52 @@
-![neuron-cover640.png](docs/assets/neuron-cover640.png)
+<p align="center">
+  <img src="docs/public/img/neuron-cover640.png" alt="neuron-js logo" width="640">
+</p>
 
 # neuron-js
 
-> **A pluggable, serializable rules engine for functional programming rulesets.**
+> **AI-friendly TypeScript rules engine for serializable JSON business rules and deterministic workflow decisions.**
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Socket Badge](https://badge.socket.dev/npm/package/@sebasoft/neuron-js)](https://socket.dev/npm/package/@sebasoft/neuron-js)
 [![Node.js Version](https://img.shields.io/badge/node-%3E%3D24.0.0-blue.svg)](https://nodejs.org)
 [![Build Status](https://github.com/SebaSOFT/neuron-js/actions/workflows/ci.yml/badge.svg)](https://github.com/SebaSOFT/neuron-js/actions)
 
-`neuron-js` is a lightweight, extensible rules engine designed to execute functional programming logic for other applications in a strictly serializable format. By modeling execution after biological systems—using **Neurons** as registries and **Synapses** as executors—it allows you to build, store, and run complex functional rulesets that remain pure JSON.
+`neuron-js` lets teams define business rules and workflow decisions as pure JSON, execute them deterministically in Node.js or the browser, and extend the rule vocabulary with TypeScript actions, conditions, parameters, rules, and lifecycle hooks.
 
-Perfect for dynamic business rules, automation workflows, and cross-application decision logic.
+Use it when hardcoded `if/else` logic is too rigid, but a heavyweight workflow or BPMN platform is too much machinery.
+
+## Links
+
+- Documentation: <https://sebasoft.github.io/neuron-js/>
+- npm: <https://www.npmjs.com/package/@sebasoft/neuron-js>
+- GitHub: <https://github.com/SebaSOFT/neuron-js>
+- Examples: [`examples/`](examples/) with pricing, eligibility, and workflow-routing scenarios
+- Schemas and validation docs: [`docs/schemas-validation-explainability.md`](docs/schemas-validation-explainability.md)
+- AI-readable docs: planned as `NJS-GROWTH-04`
+
+---
+
+## Why neuron-js?
+
+Use `neuron-js` when:
+
+- Business rules need to be stored, versioned, audited, or changed without redeploying code.
+- Backend and frontend code need to share the same deterministic rule definitions.
+- AI assistants or workflow tools generate JSON rules that still need developer-owned validation and execution boundaries.
+- Product, pricing, eligibility, routing, or automation decisions change faster than application deployments.
+- A full workflow platform is too heavy, but hardcoded conditional logic is too brittle.
+
+Do not use `neuron-js` when a simple hardcoded condition is clearer and rarely changes, when arbitrary user code execution is required, or when you need a full BPMN/process orchestration platform.
 
 ---
 
 ## ✨ Features
 
-- 🛠 **Pluggable Architecture**: Easily register custom Actions, Conditions, and Parameters.
-- 📦 **JSON Serializable**: Logic scripts are pure JSON, perfect for database storage or remote transmission.
-- 🧬 **Biological Analogy**: Intuitive execution model based on neurons, synapses, and rules.
-- ⚡ **Modern Toolchain**: Built with Node 24, TypeScript, Biome, and Vitest.
-- 🌓 **Dual-Module Support**: Native ESM and CommonJS support via `tshy`.
-- 🪝 **Lifecycle Hooks**: Comprehensive hook system for monitoring and side-effect management.
+- 🛠 **Pluggable TypeScript registry**: Register custom Actions, Conditions, Parameters, and Rules.
+- 📦 **JSON business rules**: Store, transmit, version, and audit logic as serializable JSON.
+- ⚡ **Deterministic execution**: Run predictable workflow and business decisions in Node.js or the browser.
+- 🪝 **Lifecycle hooks**: Monitor script, rule, action, and error events around execution.
+- 🌓 **Dual-module support**: Native ESM and CommonJS bundles via `tshy`.
 
 ---
 
@@ -36,43 +60,41 @@ yarn add @sebasoft/neuron-js
 npm install @sebasoft/neuron-js
 ```
 
-### Basic Usage
+### Executable rule example
 
 ```typescript
 import { Neuron, Synapse } from '@sebasoft/neuron-js';
 
-// 1. Initialize the registry
 const neuron = new Neuron();
-
-// 2. Setup the executor
 const synapse = new Synapse(neuron);
 
-// 3. Define your logic script (JSON-serializable)
 const script = {
-  id: 'hello-script',
+  id: 'pricing-decision',
   rules: [
     {
-      id: 'rule-1',
+      id: 'vip-discount-rule',
       type: 'simple_rule',
       options: {},
       conditions: [
         {
-          id: 'is-positive',
+          id: 'minimum-order-value',
           type: 'compare_two_numbers',
+          options: {},
           params: [
-            { name: 'op1', type: 'simple_number', value: '10' },
-            { name: 'comp', type: 'comparator', value: '>' },
-            { name: 'op2', type: 'simple_number', value: '0' }
+            { id: 'order-total', name: 'op1', type: 'simple_number', value: '125', options: {} },
+            { id: 'comparison', name: 'comp', type: 'comparator', value: '>', options: {} },
+            { id: 'threshold', name: 'op2', type: 'simple_number', value: '100', options: {} }
           ]
         }
       ],
       actions: [
         {
-          id: 'add-log',
+          id: 'calculate-discount',
           type: 'add_two_numbers',
+          options: {},
           params: [
-            { name: 'op1', type: 'simple_number', value: '5' },
-            { name: 'op2', type: 'simple_number', value: '5' }
+            { id: 'base-discount', name: 'op1', type: 'simple_number', value: '10', options: {} },
+            { id: 'vip-bonus', name: 'op2', type: 'simple_number', value: '5', options: {} }
           ]
         }
       ]
@@ -80,34 +102,44 @@ const script = {
   ]
 };
 
-// 4. Execute
 const context = { messages: [], state: {} };
 const result = synapse.execute(script, context);
 
 console.log(result.isSuccessful()); // true
-console.log(result.value); // 1 (number of rules executed)
+console.log(result.value); // 1 rule executed
+console.log(result.context.messages.map((message) => message.text)); // includes "Sum result: 15"
 ```
 
 ---
 
 ## 🧬 Core Concepts
 
-### Neuron (The Registry)
-The `Neuron` acts as the central hub where all element types (Actions, Conditions, Parameters, Rules) are registered. It ensures the runtime knows how to instantiate any element defined in your scripts.
+### Neuron: the registry
+
+The `Neuron` registry knows which parameter, condition, action, and rule types are available. Applications keep control of this registry so generated or stored JSON can only use developer-approved capabilities.
+
+### Synapse: the executor
+
+The `Synapse` engine connects a `Neuron` registry with a serializable script and an execution context. It evaluates rules, applies actions, and emits lifecycle hooks.
 
-### Synapse (The Executor)
-The `Synapse` is the engine that connects a `Neuron` registry to an `ExecutionScript`. It traverses the logic and manages the flow of the `ExecutionContext`.
+### Rule
+
+A Rule is a logical unit containing conditions and actions.
+
+- **No Conditions**: the rule is treated as always eligible.
+- **No Actions**: the rule evaluates conditions but performs no operation.
 
 ### Elements
-- **Action**: An operation to perform (e.g., "SendEmail", "UpdateDatabase").
-- **Condition**: A logical predicate (e.g., "UserIsAdmin", "ValueIsGreaterThanX").
-- **Parameter**: Configurable inputs for elements, enabling reusable logic templates.
+
+- **Action**: An operation to perform, such as writing to context, calculating a value, or triggering an approved side effect.
+- **Condition**: A predicate that decides whether a rule should run.
+- **Parameter**: A serializable input for actions and conditions.
 
 ---
 
 ## 💾 Execution Context & State
 
-The `ExecutionContext` is a shared state object that persists throughout the entire execution of a script. It allows Actions and Conditions to communicate and share data.
+The `ExecutionContext` is a shared state object that persists through script execution. Actions and conditions can read from it, and actions can return updated context for later rules.
 
 ```typescript
 interface ExecutionContext {
@@ -116,22 +148,27 @@ interface ExecutionContext {
 }
 ```
 
-### Using State in Actions
-Actions can read from the context and return an updated context to pass information to subsequent rules.
+---
 
-```typescript
-// Example: An action that stores a value in the state
-execute(context: ExecutionContext): ExecutionResult {
-  const newState = { ...context.state, lastCalculation: 42 };
-  return new ExecutionResult(true, { ...context, state: newState });
-}
-```
+## Roadmap-aligned docs
+
+The current public surface includes installation, positioning, core concepts, runtime architecture, and runnable examples.
+
+Available adoption assets:
+
+- Runnable examples: [`examples/`](examples/)
+- JSON Schemas, validation, and explain output: [`docs/schemas-validation-explainability.md`](docs/schemas-validation-explainability.md)
+
+Planned next adoption assets:
+
+- `llms.txt` and AI-assistant documentation: `NJS-GROWTH-04`
+- Comparison and migration pages: `NJS-GROWTH-05`
 
 ---
 
 ## 🛠 Development
 
-We use a modern toolchain for high performance and developer ergonomics:
+We use a modern toolchain for high-signal development:
 
 - **Linting & Formatting**: [Biome](https://biomejs.dev/)
 - **Testing**: [Vitest](https://vitest.dev/)
@@ -142,8 +179,10 @@ We use a modern toolchain for high performance and developer ergonomics:
 
 ```bash
 yarn test    # Run test suite
-yarn lint    # Check for linting issues
+yarn lint    # Check linting and formatting
+yarn examples # Build and verify runnable examples
 yarn build   # Generate ESM/CJS bundles
+yarn docs:build # Build API docs and VitePress site
 ```
 
 ---

package/dist/commonjs/Synapse.d.ts

@@ -3,10 +3,28 @@ import type { ScriptInterface } from "./interfaces/Script.js";
 import type { ExecutionContext } from "./types/ExecutionContext.js";
 import { ExecutionResult } from "./types/ExecutionResult.js";
 import type { HookEmitter } from "./types/HookEmitter.js";
+/**
+ * The Synapse class is the core execution engine of the rules system.
+ * It processes logic defined in scripts by coordinating between the Registry (Neuron) and the state (ExecutionContext).
+ */
 export declare class Synapse {
     private readonly _neuron;
     private readonly _hookEmitter?;
+    /**
+     * Initializes a new execution engine.
+     *
+     * @param _neuron - The registry containing all element definitions.
+     * @param _hookEmitter - Optional global lifecycle hook emitter.
+     */
     constructor(_neuron: Neuron, _hookEmitter?: HookEmitter | undefined);
+    /**
+     * Executes a script logic against a provided context.
+     *
+     * @param script - The serializable script defining the logic rules.
+     * @param context - The shared state object to pass through the execution.
+     * @param runtimeHookEmitter - Optional one-time hook emitter for this specific execution.
+     * @returns An ExecutionResult containing the final context and the number of successfully executed rules.
+     */
     execute(script: ScriptInterface, context: ExecutionContext, runtimeHookEmitter?: HookEmitter): ExecutionResult<number>;
 }
 //# sourceMappingURL=Synapse.d.ts.map

package/dist/commonjs/Synapse.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Synapse.d.ts","sourceRoot":"","sources":["../../src/Synapse.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEzC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAE9D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AACpE,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAE1D,qBAAa,OAAO;IAEhB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC;gBADb,OAAO,EAAE,MAAM,EACf,YAAY,CAAC,EAAE,WAAW,YAAA;IAG7C,OAAO,CACL,MAAM,EAAE,eAAe,EACvB,OAAO,EAAE,gBAAgB,EACzB,kBAAkB,CAAC,EAAE,WAAW,GAC/B,eAAe,CAAC,MAAM,CAAC;CAsB3B"}
+{"version":3,"file":"Synapse.d.ts","sourceRoot":"","sources":["../../src/Synapse.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEzC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAE9D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AACpE,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAE1D;;;GAGG;AACH,qBAAa,OAAO;IAQhB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC;IARhC;;;;;OAKG;gBAEgB,OAAO,EAAE,MAAM,EACf,YAAY,CAAC,EAAE,WAAW,YAAA;IAG7C;;;;;;;OAOG;IACH,OAAO,CACL,MAAM,EAAE,eAAe,EACvB,OAAO,EAAE,gBAAgB,EACzB,kBAAkB,CAAC,EAAE,WAAW,GAC/B,eAAe,CAAC,MAAM,CAAC;CAsB3B"}

package/dist/commonjs/Synapse.js

@@ -4,13 +4,31 @@ exports.Synapse = void 0;
 const HookEvents_js_1 = require("./interfaces/HookEvents.js");
 const RuleRuntime_js_1 = require("./runtime/RuleRuntime.js");
 const ExecutionResult_js_1 = require("./types/ExecutionResult.js");
+/**
+ * The Synapse class is the core execution engine of the rules system.
+ * It processes logic defined in scripts by coordinating between the Registry (Neuron) and the state (ExecutionContext).
+ */
 class Synapse {
     _neuron;
     _hookEmitter;
+    /**
+     * Initializes a new execution engine.
+     *
+     * @param _neuron - The registry containing all element definitions.
+     * @param _hookEmitter - Optional global lifecycle hook emitter.
+     */
     constructor(_neuron, _hookEmitter) {
         this._neuron = _neuron;
         this._hookEmitter = _hookEmitter;
     }
+    /**
+     * Executes a script logic against a provided context.
+     *
+     * @param script - The serializable script defining the logic rules.
+     * @param context - The shared state object to pass through the execution.
+     * @param runtimeHookEmitter - Optional one-time hook emitter for this specific execution.
+     * @returns An ExecutionResult containing the final context and the number of successfully executed rules.
+     */
     execute(script, context, runtimeHookEmitter) {
         const emitter = runtimeHookEmitter ?? this._hookEmitter;
         if (!script?.rules || script.rules.length === 0) {

package/dist/commonjs/Synapse.js.map

@@ -1 +1 @@
-{"version":3,"file":"Synapse.js","sourceRoot":"","sources":["../../src/Synapse.ts"],"names":[],"mappings":";;;AACA,8DAAwD;AAExD,6DAAuD;AAEvD,mEAA6D;AAG7D,MAAa,OAAO;IAEC;IACA;IAFnB,YACmB,OAAe,EACf,YAA0B;QAD1B,YAAO,GAAP,OAAO,CAAQ;QACf,iBAAY,GAAZ,YAAY,CAAc;IAC1C,CAAC;IAEJ,OAAO,CACL,MAAuB,EACvB,OAAyB,EACzB,kBAAgC;QAEhC,MAAM,OAAO,GAAG,kBAAkB,IAAI,IAAI,CAAC,YAAY,CAAC;QAExD,IAAI,CAAC,MAAM,EAAE,KAAK,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAChD,OAAO,EAAE,CAAC,0BAAU,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC;YAC/C,MAAM,MAAM,GAAG,IAAI,oCAAe,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC,cAAc,CAAC,CAAC,CAAC;YACvE,OAAO,EAAE,CAAC,0BAAU,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;YAC7C,OAAO,MAAM,CAAC;QAChB,CAAC;QAED,OAAO,EAAE,CAAC,0BAAU,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC;QAC/C,MAAM,WAAW,GAAG,IAAI,4BAAW,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACzE,MAAM,MAAM,GAAG,WAAW,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QAE5C,IAAI,MAAM,CAAC,YAAY,EAAE,EAAE,CAAC;YAC1B,OAAO,EAAE,CAAC,0BAAU,CAAC,aAAa,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;QACtD,CAAC;aAAM,CAAC;YACN,OAAO,EAAE,CAAC,0BAAU,CAAC,eAAe,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;QACxD,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC;CACF;AAhCD,0BAgCC"}
+{"version":3,"file":"Synapse.js","sourceRoot":"","sources":["../../src/Synapse.ts"],"names":[],"mappings":";;;AACA,8DAAwD;AAExD,6DAAuD;AAEvD,mEAA6D;AAG7D;;;GAGG;AACH,MAAa,OAAO;IAQC;IACA;IARnB;;;;;OAKG;IACH,YACmB,OAAe,EACf,YAA0B;QAD1B,YAAO,GAAP,OAAO,CAAQ;QACf,iBAAY,GAAZ,YAAY,CAAc;IAC1C,CAAC;IAEJ;;;;;;;OAOG;IACH,OAAO,CACL,MAAuB,EACvB,OAAyB,EACzB,kBAAgC;QAEhC,MAAM,OAAO,GAAG,kBAAkB,IAAI,IAAI,CAAC,YAAY,CAAC;QAExD,IAAI,CAAC,MAAM,EAAE,KAAK,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAChD,OAAO,EAAE,CAAC,0BAAU,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC;YAC/C,MAAM,MAAM,GAAG,IAAI,oCAAe,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC,cAAc,CAAC,CAAC,CAAC;YACvE,OAAO,EAAE,CAAC,0BAAU,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;YAC7C,OAAO,MAAM,CAAC;QAChB,CAAC;QAED,OAAO,EAAE,CAAC,0BAAU,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC;QAC/C,MAAM,WAAW,GAAG,IAAI,4BAAW,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACzE,MAAM,MAAM,GAAG,WAAW,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QAE5C,IAAI,MAAM,CAAC,YAAY,EAAE,EAAE,CAAC;YAC1B,OAAO,EAAE,CAAC,0BAAU,CAAC,aAAa,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;QACtD,CAAC;aAAM,CAAC;YACN,OAAO,EAAE,CAAC,0BAAU,CAAC,eAAe,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;QACxD,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC;CACF;AA9CD,0BA8CC"}

package/dist/commonjs/abstracts/AbstractAction.d.ts

@@ -0,0 +1,15 @@
+import type { Neuron } from "../index.js";
+import type { ActionOptions } from "../interfaces/Action.js";
+import type { ParameterInterface } from "../interfaces/Parameter.js";
+import type { ExecutionContext } from "../types/ExecutionContext.js";
+import { AbstractElement } from "./AbstractElement.js";
+export declare abstract class AbstractAction<TOptions extends ActionOptions = ActionOptions> extends AbstractElement<TOptions> {
+    readonly rawParams: ParameterInterface[];
+    protected readonly neuron: Neuron;
+    readonly params: Map<string, {
+        getValue(context: ExecutionContext): unknown | null;
+    }>;
+    constructor(id: string, type: string, rawParams: ParameterInterface[], options: TOptions, neuron: Neuron);
+    toJSON(): object;
+}
+//# sourceMappingURL=AbstractAction.d.ts.map

package/dist/commonjs/abstracts/AbstractAction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AbstractAction.d.ts","sourceRoot":"","sources":["../../../src/abstracts/AbstractAction.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AACrE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAEvD,8BAAsB,cAAc,CAClC,QAAQ,SAAS,aAAa,GAAG,aAAa,CAC9C,SAAQ,eAAe,CAAC,QAAQ,CAAC;aASf,SAAS,EAAE,kBAAkB,EAAE;IAE/C,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM;IAVnC,SAAgB,MAAM,EAAE,GAAG,CACzB,MAAM,EACN;QAAE,QAAQ,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,GAAG,IAAI,CAAA;KAAE,CACxD,CAAC;gBAGA,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,MAAM,EACI,SAAS,EAAE,kBAAkB,EAAE,EAC/C,OAAO,EAAE,QAAQ,EACE,MAAM,EAAE,MAAM;IAMnC,MAAM,IAAI,MAAM;CAQjB"}

package/dist/commonjs/abstracts/AbstractAction.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AbstractAction = void 0;
+const AbstractElement_js_1 = require("./AbstractElement.js");
+class AbstractAction extends AbstractElement_js_1.AbstractElement {
+    rawParams;
+    neuron;
+    params;
+    constructor(id, type, rawParams, options, neuron) {
+        super(id, type, options);
+        this.rawParams = rawParams;
+        this.neuron = neuron;
+        this.params = neuron.createParameterMap(rawParams);
+    }
+    toJSON() {
+        return {
+            id: this.id,
+            type: this.type,
+            params: this.rawParams,
+            options: this.options,
+        };
+    }
+}
+exports.AbstractAction = AbstractAction;
+//# sourceMappingURL=AbstractAction.js.map

package/dist/commonjs/abstracts/AbstractAction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AbstractAction.js","sourceRoot":"","sources":["../../../src/abstracts/AbstractAction.ts"],"names":[],"mappings":";;;AAIA,6DAAuD;AAEvD,MAAsB,cAEpB,SAAQ,oCAAyB;IASf;IAEG;IAVL,MAAM,CAGpB;IAEF,YACE,EAAU,EACV,IAAY,EACI,SAA+B,EAC/C,OAAiB,EACE,MAAc;QAEjC,KAAK,CAAC,EAAE,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;QAJT,cAAS,GAAT,SAAS,CAAsB;QAE5B,WAAM,GAAN,MAAM,CAAQ;QAGjC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,kBAAkB,CAAC,SAAS,CAAC,CAAC;IACrD,CAAC;IAED,MAAM;QACJ,OAAO;YACL,EAAE,EAAE,IAAI,CAAC,EAAE;YACX,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,MAAM,EAAE,IAAI,CAAC,SAAS;YACtB,OAAO,EAAE,IAAI,CAAC,OAAO;SACtB,CAAC;IACJ,CAAC;CACF;AA3BD,wCA2BC"}

package/dist/commonjs/abstracts/AbstractCondition.d.ts

@@ -0,0 +1,15 @@
+import type { Neuron } from "../index.js";
+import type { ConditionOptions } from "../interfaces/Condition.js";
+import type { ParameterInterface } from "../interfaces/Parameter.js";
+import type { ExecutionContext } from "../types/ExecutionContext.js";
+import { AbstractElement } from "./AbstractElement.js";
+export declare abstract class AbstractCondition<TOptions extends ConditionOptions = ConditionOptions> extends AbstractElement<TOptions> {
+    readonly rawParams: ParameterInterface[];
+    protected readonly neuron: Neuron;
+    readonly params: Map<string, {
+        getValue(context: ExecutionContext): unknown | null;
+    }>;
+    constructor(id: string, type: string, rawParams: ParameterInterface[], options: TOptions, neuron: Neuron);
+    toJSON(): object;
+}
+//# sourceMappingURL=AbstractCondition.d.ts.map

package/dist/commonjs/abstracts/AbstractCondition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AbstractCondition.d.ts","sourceRoot":"","sources":["../../../src/abstracts/AbstractCondition.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AACnE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AACrE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAEvD,8BAAsB,iBAAiB,CACrC,QAAQ,SAAS,gBAAgB,GAAG,gBAAgB,CACpD,SAAQ,eAAe,CAAC,QAAQ,CAAC;aASf,SAAS,EAAE,kBAAkB,EAAE;IAE/C,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM;IAVnC,SAAgB,MAAM,EAAE,GAAG,CACzB,MAAM,EACN;QAAE,QAAQ,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,GAAG,IAAI,CAAA;KAAE,CACxD,CAAC;gBAGA,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,MAAM,EACI,SAAS,EAAE,kBAAkB,EAAE,EAC/C,OAAO,EAAE,QAAQ,EACE,MAAM,EAAE,MAAM;IAMnC,MAAM,IAAI,MAAM;CAQjB"}

package/dist/commonjs/abstracts/AbstractCondition.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AbstractCondition = void 0;
+const AbstractElement_js_1 = require("./AbstractElement.js");
+class AbstractCondition extends AbstractElement_js_1.AbstractElement {
+    rawParams;
+    neuron;
+    params;
+    constructor(id, type, rawParams, options, neuron) {
+        super(id, type, options);
+        this.rawParams = rawParams;
+        this.neuron = neuron;
+        this.params = neuron.createParameterMap(rawParams);
+    }
+    toJSON() {
+        return {
+            id: this.id,
+            type: this.type,
+            params: this.rawParams,
+            options: this.options,
+        };
+    }
+}
+exports.AbstractCondition = AbstractCondition;
+//# sourceMappingURL=AbstractCondition.js.map

package/dist/commonjs/abstracts/AbstractCondition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AbstractCondition.js","sourceRoot":"","sources":["../../../src/abstracts/AbstractCondition.ts"],"names":[],"mappings":";;;AAIA,6DAAuD;AAEvD,MAAsB,iBAEpB,SAAQ,oCAAyB;IASf;IAEG;IAVL,MAAM,CAGpB;IAEF,YACE,EAAU,EACV,IAAY,EACI,SAA+B,EAC/C,OAAiB,EACE,MAAc;QAEjC,KAAK,CAAC,EAAE,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;QAJT,cAAS,GAAT,SAAS,CAAsB;QAE5B,WAAM,GAAN,MAAM,CAAQ;QAGjC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,kBAAkB,CAAC,SAAS,CAAC,CAAC;IACrD,CAAC;IAED,MAAM;QACJ,OAAO;YACL,EAAE,EAAE,IAAI,CAAC,EAAE;YACX,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,MAAM,EAAE,IAAI,CAAC,SAAS;YACtB,OAAO,EAAE,IAAI,CAAC,OAAO;SACtB,CAAC;IACJ,CAAC;CACF;AA3BD,8CA2BC"}

package/dist/commonjs/contracts/explain.d.ts

@@ -0,0 +1,9 @@
+import type { ScriptInterface } from "../interfaces/Script.js";
+import type { ExecutionResult } from "../types/ExecutionResult.js";
+import type { ExecutionExplanation } from "./validation.js";
+export interface ExplainExecutionOptions {
+    script: ScriptInterface;
+    result: ExecutionResult<number>;
+}
+export declare function explainExecution({ script, result, }: ExplainExecutionOptions): ExecutionExplanation;
+//# sourceMappingURL=explain.d.ts.map

package/dist/commonjs/contracts/explain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explain.d.ts","sourceRoot":"","sources":["../../../src/contracts/explain.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,KAAK,EACV,oBAAoB,EAErB,MAAM,iBAAiB,CAAC;AAEzB,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,eAAe,CAAC;IACxB,MAAM,EAAE,eAAe,CAAC,MAAM,CAAC,CAAC;CACjC;AAED,wBAAgB,gBAAgB,CAAC,EAC/B,MAAM,EACN,MAAM,GACP,EAAE,uBAAuB,GAAG,oBAAoB,CAkDhD"}

package/dist/commonjs/contracts/explain.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.explainExecution = explainExecution;
+function explainExecution({ script, result, }) {
+    const trace = [
+        {
+            step: 1,
+            type: "script_received",
+            message: `Script ${script.id} contains ${script.rules.length} rule(s).`,
+        },
+    ];
+    script.rules.forEach((rule, index) => {
+        trace.push({
+            step: trace.length + 1,
+            type: rule.options?.disabled ? "rule_skipped" : "rule_available",
+            ruleId: rule.id,
+            message: rule.options?.disabled
+                ? `Rule ${rule.id} is disabled.`
+                : `Rule ${rule.id} has ${rule.conditions?.length ?? 0} condition(s) and ${rule.actions?.length ?? 0} action(s).`,
+        });
+        if (index === script.rules.length - 1) {
+            trace.push({
+                step: trace.length + 1,
+                type: result.isSuccessful()
+                    ? "execution_completed"
+                    : "execution_failed",
+                ruleId: rule.id,
+                message: result.isSuccessful()
+                    ? `Execution completed with ${result.value ?? 0} rule(s) executed.`
+                    : "Execution failed before completing all rules.",
+            });
+        }
+    });
+    if (script.rules.length === 0) {
+        trace.push({
+            step: trace.length + 1,
+            type: "execution_completed",
+            message: "Execution completed with an empty script.",
+        });
+    }
+    return {
+        scriptId: script.id,
+        ok: result.isSuccessful(),
+        rulesEvaluated: script.rules.filter((rule) => !rule.options?.disabled)
+            .length,
+        rulesExecuted: typeof result.value === "number" ? result.value : null,
+        messages: result.messages,
+        trace,
+    };
+}
+//# sourceMappingURL=explain.js.map

package/dist/commonjs/contracts/explain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"explain.js","sourceRoot":"","sources":["../../../src/contracts/explain.ts"],"names":[],"mappings":";;AAYA,4CAqDC;AArDD,SAAgB,gBAAgB,CAAC,EAC/B,MAAM,EACN,MAAM,GACkB;IACxB,MAAM,KAAK,GAAgC;QACzC;YACE,IAAI,EAAE,CAAC;YACP,IAAI,EAAE,iBAAiB;YACvB,OAAO,EAAE,UAAU,MAAM,CAAC,EAAE,aAAa,MAAM,CAAC,KAAK,CAAC,MAAM,WAAW;SACxE;KACF,CAAC;IAEF,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE;QACnC,KAAK,CAAC,IAAI,CAAC;YACT,IAAI,EAAE,KAAK,CAAC,MAAM,GAAG,CAAC;YACtB,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,gBAAgB;YAChE,MAAM,EAAE,IAAI,CAAC,EAAE;YACf,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,QAAQ;gBAC7B,CAAC,CAAC,QAAQ,IAAI,CAAC,EAAE,eAAe;gBAChC,CAAC,CAAC,QAAQ,IAAI,CAAC,EAAE,QAAQ,IAAI,CAAC,UAAU,EAAE,MAAM,IAAI,CAAC,qBAAqB,IAAI,CAAC,OAAO,EAAE,MAAM,IAAI,CAAC,aAAa;SACnH,CAAC,CAAC;QAEH,IAAI,KAAK,KAAK,MAAM,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACtC,KAAK,CAAC,IAAI,CAAC;gBACT,IAAI,EAAE,KAAK,CAAC,MAAM,GAAG,CAAC;gBACtB,IAAI,EAAE,MAAM,CAAC,YAAY,EAAE;oBACzB,CAAC,CAAC,qBAAqB;oBACvB,CAAC,CAAC,kBAAkB;gBACtB,MAAM,EAAE,IAAI,CAAC,EAAE;gBACf,OAAO,EAAE,MAAM,CAAC,YAAY,EAAE;oBAC5B,CAAC,CAAC,4BAA4B,MAAM,CAAC,KAAK,IAAI,CAAC,oBAAoB;oBACnE,CAAC,CAAC,+CAA+C;aACpD,CAAC,CAAC;QACL,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC9B,KAAK,CAAC,IAAI,CAAC;YACT,IAAI,EAAE,KAAK,CAAC,MAAM,GAAG,CAAC;YACtB,IAAI,EAAE,qBAAqB;YAC3B,OAAO,EAAE,2CAA2C;SACrD,CAAC,CAAC;IACL,CAAC;IAED,OAAO;QACL,QAAQ,EAAE,MAAM,CAAC,EAAE;QACnB,EAAE,EAAE,MAAM,CAAC,YAAY,EAAE;QACzB,cAAc,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC;aACnE,MAAM;QACT,aAAa,EAAE,OAAO,MAAM,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI;QACrE,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,KAAK;KACN,CAAC;AACJ,CAAC"}

package/dist/commonjs/contracts/validation.d.ts

@@ -0,0 +1,40 @@
+import type { ExecutionContext } from "../types/ExecutionContext.js";
+export interface ValidationError {
+    path: string;
+    code: string;
+    message: string;
+}
+export interface ValidationResult {
+    ok: boolean;
+    errors: ValidationError[];
+}
+export declare function validateScript(script: unknown): ValidationResult;
+export declare function validateExecutionContext(context: unknown): ValidationResult;
+export declare function validateExecutionOutput(output: unknown): ValidationResult;
+export declare function validateValidationErrors(value: unknown): ValidationResult;
+export interface ExecutionExplanationEvent {
+    step: number;
+    type: string;
+    message: string;
+    ruleId?: string;
+}
+export interface ExecutionExplanation {
+    scriptId: string;
+    ok: boolean;
+    rulesEvaluated: number;
+    rulesExecuted: number | null;
+    messages: string[];
+    trace: ExecutionExplanationEvent[];
+}
+export declare function validateExecutionExplanation(value: unknown): ValidationResult;
+export declare function summarizeExecutionOutput(result: {
+    isSuccessful(): boolean;
+    value: unknown;
+    messages: string[];
+}): {
+    ok: boolean;
+    rulesExecuted: number | null;
+    messages: string[];
+};
+export type { ExecutionContext };
+//# sourceMappingURL=validation.d.ts.map

package/dist/commonjs/contracts/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../../src/contracts/validation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAErE,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,eAAe,EAAE,CAAC;CAC3B;AA+JD,wBAAgB,cAAc,CAAC,MAAM,EAAE,OAAO,GAAG,gBAAgB,CAShE;AAED,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,OAAO,GAAG,gBAAgB,CAqB3E;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,OAAO,GAAG,gBAAgB,CAmCzE;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB,CAoBzE;AAED,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,EAAE,EAAE,OAAO,CAAC;IACZ,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,KAAK,EAAE,yBAAyB,EAAE,CAAC;CACpC;AAED,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB,CAsD7E;AAED,wBAAgB,wBAAwB,CAAC,MAAM,EAAE;IAC/C,YAAY,IAAI,OAAO,CAAC;IACxB,KAAK,EAAE,OAAO,CAAC;IACf,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;;;;EAMA;AAED,YAAY,EAAE,gBAAgB,EAAE,CAAC"}