npm package: @sdux-vault/engine
Description: > Deterministic pipeline execution, orchestration, and state management for the SDuX platform.
Latest version: 0.0.10

# @sdux-vault/engine

> Deterministic pipeline execution, orchestration, and state management for the SDuX platform.

`@sdux-vault/engine` provides the core runtime engine for SDuX.  
It is responsible for executing pipelines, orchestrating behaviors, and managing deterministic state transitions across the system.

---

## TL;DR

For full documentation, guides, and API references:  
https://www.sdux-vault.com

---

## Overview

SDuX is built as a layered system:

```
shared → core → core-extensions → apps
           └────────────────────→ devtools
```

- **shared** → contracts, types, utilities
- **core** → runtime engine and orchestration (this package)
- **core-extensions** → framework integrations (Angular, React, etc.)
- **apps** → end-user applications
- **devtools** → observability and debugging

---

## What This Package Provides

- Pipeline execution engine
- Behavior orchestration system
- Controller coordination layer
- Deterministic state transition processing
- Event-driven execution model
- Runtime integration foundation

---

## Key Characteristics

- ✅ Deterministic execution model
- ✅ Framework-agnostic architecture
- ✅ Composable pipeline behaviors
- ✅ Predictable state transitions
- ✅ High-performance runtime orchestration

---

## Installation

```bash
npm install @sdux-vault/engine
```

---

## Usage

### Basic Import

```ts
import { createVault } from '@sdux-vault/engine';
```

This enables:

- pipeline execution
- behavior orchestration
- controller-driven state updates

---

## Example: Creating a Vault

```ts
import { createVault } from '@sdux-vault/engine';

const vault = createVault({
  // configuration
});
```

---

## How It Works

This package serves as the execution backbone of SDuX through:

- Pipeline orchestration
- Behavior execution sequencing
- Controller decision coordination
- State mutation management

It processes:

- incoming events
- pipeline stages
- controller decisions
- state updates

All in a deterministic and traceable manner.

---

## Execution Model

### Deterministic Processing

The engine ensures:

- consistent execution order
- predictable outcomes
- reproducible state transitions

---

## Pipeline Architecture

Execution is structured around:

- FeatureCell pipelines
- Behavior chains
- Controller decision layers
- Orchestrator coordination

---

## State Management

State transitions are:

- controlled
- predictable
- observable (via devtools)
- fully deterministic

---

## Environment Behavior

The engine is:

- ✅ Production-ready
- ✅ Framework-agnostic
- ✅ Compatible with SSR and browser environments
- ✅ Designed for both simple and complex state systems

---

## Side Effects

This package minimizes side effects and focuses on controlled execution.

All state mutations occur through:

- defined pipeline stages
- controlled behavior execution
- explicit controller decisions

---

## Development

### Build

```bash
npm run build:engine
```

Output:

```
dist/engine
```

---

## Test

```bash
npm run test:engine
```

---

## Verify

```bash
npm run verify
```

Includes:

- linting
- formatting
- type checking
- tests

---

## Publishing

See `RELEASE.md` for full publishing instructions.

---

## Ecosystem

- `@sdux-vault/shared` — core contracts, types, and utilities
- `@sdux-vault/core` — execution engine for pipelines and orchestration
- `@sdux-vault/addons` — optional runtime extensions
- `@sdux-vault/core-extensions/angular` — Angular integration layer
- `@sdux-vault/devtools` — observability and debugging layer

---

## Tree Shaking & Side Effects

This package is designed to be:

- tree-shakeable
- side-effect controlled

Only intentional execution paths trigger state changes.

---

## License

For full licensing details:  
https://www.sdux-vault.com/docs/welcome/license#license-texts

MIT © SDuX Vault