@arka-protocol/core

Pure, deterministic compliance rules engine for the modern enterprise

Documentation |
Quick Start |
API Reference |
Examples

---

Overview

@arka-protocol/core is a zero-dependency (runtime), pure, and deterministic rules engine designed for building sophisticated compliance, regulatory, and policy enforcement systems. It provides a powerful foundation for applications requiring auditable decision-making with full traceability.

$3

- Deterministic Evaluation - Same inputs always produce identical outputs, perfect for audit trails
- Bytecode Compilation (RTVM) - Compile rules to optimized bytecode for high-performance evaluation
- Multi-Jurisdiction Harmonization - Handle overlapping regulatory requirements across regions
- Time-Travel Simulation - Test rule changes against historical data before deployment
- Adaptive Risk Scoring - Dynamic entity risk assessment with configurable factors
- Rule Dependency Graphs - Visualize and manage complex rule relationships
- JSON Schema Validation - Built-in entity validation with comprehensive error reporting
- Zero Side Effects - Pure library with no network I/O or external dependencies

---

Installation

``bash
npm install @arka-protocol/core
`

`bash
yarn add @arka-protocol/core
`

`bash
pnpm add @arka-protocol/core
`

---

Quick Start

$3

`typescript
import { ArkaEngine } from '@arka-protocol/core';

// Create the engine
const engine = new ArkaEngine();

// Register an entity type with schema
engine.registerEntityType({
name: 'Transaction',
description: 'Financial transaction',
schema: {
type: 'object',
properties: {
amount: { type: 'number' },
currency: { type: 'string' },
country: { type: 'string' }
},
required: ['amount', 'currency']
}
});

// Register a compliance rule
engine.registerRule({
id: 'large-transaction-check',
name: 'Large Transaction Review',
description: 'Flag transactions over $10,000 for review',
severity: 'MEDIUM',
tags: ['aml', 'transaction-monitoring'],
condition: {
type: 'compare',
field: 'amount',
operator: '>=',
value: 10000
},
consequence: {
decision: 'FLAG',
message: 'Transaction exceeds $10,000 threshold - requires manual review'
}
});

// Evaluate an event
const decision = engine.evaluateRules({
event: {
id: 'evt_123',
type: 'transaction.created',
payload: { amount: 15000, currency: 'USD' },
occurredAt: new Date().toISOString()
},
entity: {
id: 'txn_456',
type: 'Transaction',
data: { amount: 15000, currency: 'USD', country: 'US' }
}
});

console.log(decision.status); // 'ALLOW_WITH_FLAGS'
console.log(decision.ruleEvaluations[0].details);
// 'Transaction exceeds $10,000 threshold - requires manual review'
`

$3

`typescript
import { evaluateCondition } from '@arka-protocol/core';

// Complex condition with AND/OR/NOT logic
const condition = {
type: 'and',
conditions: [
{
type: 'compare',
field: 'amount',
operator: '>=',
value: 5000
},
{
type: 'or',
conditions: [
{ type: 'compare', field: 'country', operator: 'in', value: ['RU', 'IR', 'KP'] },
{ type: 'compare', field: 'risk_score', operator: '>', value: 80 }
]
}
]
};

const data = { amount: 7500, country: 'RU', risk_score: 45 };
const result = evaluateCondition(condition, data); // true
`

$3

Compile rules to bytecode for faster evaluation in high-throughput scenarios:

`typescript
import { compileRule, executeProgram } from '@arka-protocol/core';

// Compile rule to bytecode
const bytecode = compileRule(myRule);

// Execute compiled bytecode
const context = {
event: eventData,
entity: entityData
};

const result = executeProgram(bytecode, context);
console.log(result.value); // true/false
console.log(result.executionTimeMs); // < 0.1ms typically
`

$3

`typescript
import { createRiskScoringEngine } from '@arka-protocol/core';

const scoringEngine = createRiskScoringEngine();

// Compute risk score for an entity
const score = await scoringEngine.computeScore({
entityId: 'user_123',
entityType: 'Customer',
entityData: { / customer data / },
decisions: [/ historical decisions /],
timestamp: new Date().toISOString()
});

console.log(score.riskScore); // 0-100
console.log(score.riskBand); // 'MINIMAL' | 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL'
console.log(score.trend); // 'IMPROVING' | 'STABLE' | 'WORSENING'
console.log(score.confidence); // 0-1 based on data availability
`

$3

Test rule changes against historical data before deploying:

`typescript
import { createTimeTravelSimulator } from '@arka-protocol/core';

const simulator = createTimeTravelSimulator({
getRulesAtTime: async (timestamp) => fetchRulesFromDB(timestamp),
getEntityAtTime: async (id, timestamp) => fetchEntitySnapshot(id, timestamp),
getEventsInRange: async (start, end) => fetchEvents(start, end),
evaluateRule: async (rule, event, entity) => evaluateWithEngine(rule, event, entity)
});

// Simulate impact of proposed rules
const result = await simulator.simulate({
asOfDate: '2024-01-01T00:00:00Z',
eventTimeRange: {
start: '2023-06-01T00:00:00Z',
end: '2023-12-31T23:59:59Z'
},
proposedRules: newRuleSet,
includeDecisionDiffs: true
});

console.log(result.comparison);
// { unchanged: 950, allowToDeny: 30, denyToAllow: 15, otherChanges: 5 }
`

---

API Reference

$3

| Export | Description |
|--------|-------------|
| ArkaEngine | Main engine class coordinating rules, entities, and evaluation |
| getDefaultEngine() | Get or create the singleton engine instance |
| setDefaultEngine(engine) | Set the default engine instance |
| resetDefaultEngine() | Reset the default engine to initial state |

$3

| Export | Description |
|--------|-------------|
| evaluateRules(input) | Evaluate multiple rules against an event/entity |
| evaluateSingleRule(input) | Evaluate a single rule and return detailed result |
| evaluateCondition(condition, data) | Evaluate a condition against data |
| getApplicableRules(rules, event, entity) | Filter rules applicable to event/entity |

$3

| Export | Description |
|--------|-------------|
| RuleRegistry | In-memory registry for rule management |
| EntityTypeRegistry | In-memory registry for entity type schemas |
| getDefaultRuleRegistry() | Get singleton rule registry |
| getDefaultEntityTypeRegistry() | Get singleton entity type registry |

$3

| Export | Description |
|--------|-------------|
| validateEntity(entity, type) | Validate entity against its type schema |
| validateEntityOrThrow(entity, type) | Validate and throw on failure |
| validateAgainstSchema(data, schema) | Validate data against JSON Schema |
| createValidator(schema) | Create reusable validator function |

$3

| Export | Description |
|--------|-------------|
| compileRule(rule) | Compile rule to bytecode program |
| compileRules(rules) | Batch compile multiple rules |
| executeProgram(program, context) | Execute compiled bytecode |
| validateProgram(program) | Validate bytecode program integrity |

$3

| Export | Description |
|--------|-------------|
| TimeTravelSimulator | Main simulator class |
| createTimeTravelSimulator(options) | Create simulator with data providers |

$3

| Export | Description |
|--------|-------------|
| RiskScoringEngine | Adaptive risk scoring engine |
| createRiskScoringEngine(model?) | Create scoring engine with optional model |
| DEFAULT_RISK_BANDS | Default risk band configuration |
| DEFAULT_SCORING_MODEL | Default scoring model configuration |

$3

| Module | Description |
|--------|-------------|
| harmonization/* | Multi-jurisdiction rule harmonization |
| diff/* | Rule set comparison and diff generation |
| grl/* | Global Rule Language (GRL) specification |
| graph/* | Global compliance graph representation |
| temporal/* | Point-in-time entity snapshots |
| rule-graph/* | Rule dependency graph management |

---

Condition Operators

The engine supports a rich set of comparison operators:

| Operator | Description | Example |
|----------|-------------|---------|
| == | Equal | { field: 'status', operator: '==', value: 'active' } |
| != | Not equal | { field: 'type', operator: '!=', value: 'internal' } |
| < | Less than | { field: 'age', operator: '<', value: 18 } |
| <= | Less than or equal | { field: 'score', operator: '<=', value: 100 } |
| > | Greater than | { field: 'amount', operator: '>', value: 0 } |
| >= | Greater than or equal | { field: 'balance', operator: '>=', value: 1000 } |
| in | Value in array | { field: 'country', operator: 'in', value: ['US', 'CA'] } |
| not_in | Value not in array | { field: 'status', operator: 'not_in', value: ['blocked'] } |
| contains | String/array contains | { field: 'tags', operator: 'contains', value: 'vip' } |
| starts_with | String starts with | { field: 'email', operator: 'starts_with', value: 'admin' } |
| ends_with | String ends with | { field: 'domain', operator: 'ends_with', value: '.gov' } |
| matches | Regex match | { field: 'phone', operator: 'matches', value: '^\\+1' } |
| exists | Field exists | { field: 'metadata.verified', operator: 'exists', value: true } |
| not_exists | Field does not exist | { field: 'deleted_at', operator: 'not_exists', value: true } |

---

TypeScript Support

This package is written in TypeScript and includes full type definitions. All exports are fully typed:

`typescript
import type {
ArkaEngineConfig,
EvaluationContext,
EvaluateRulesInput,
ValidationResult,
EntityRiskScore,
RiskBandConfig,
TimeTravelSimulationResult
} from '@arka-protocol/core';
`

---

Use Cases

- Financial Compliance - AML transaction monitoring, sanctions screening, fraud detection
- Healthcare - HIPAA compliance, clinical decision support, patient data access control
- Insurance - Underwriting rules, claims adjudication, policy compliance
- Government - Regulatory enforcement, benefits eligibility, permit processing
- E-commerce - Order validation, seller compliance, marketplace policies
- Gaming - Responsible gaming limits, age verification, regional restrictions

---

Documentation

For comprehensive documentation, tutorials, and best practices, visit:

https://www.arkaprotocol.com/docs

---

Contributing

We welcome contributions! Please see our Contributing Guide for details.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature`)
5. Open a Pull Request

---

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

---

Built with care by ARKA Protocol