koura-core

The projection engine kernel. Provides the core types, engine loop, policy resolver, default executor, and all interfaces needed to build rule-driven projection systems.

Key Exports

| Export | Kind | Description | |--------|------|-------------| | createProjectionEngine() | Factory | Creates a projection engine instance | | resolveRulePolicy() | Function | Merges default, tag, and rule-specific policies | | isRuleActive() | Function | Checks whether a resolved policy keeps a rule active | | createDefaultExecutor() | Factory | Creates the built-in sequential executor (supports set-field) | | ProjectionDomain | Type | Bundles Source, Facts, State, Derived into one generic | | ProjectionRule | Type | The rule contract — ProjectionRule<D> | | ProjectionPolicy | Type | Top-level policy controlling a run | | ProjectionResult | Type | Complete result including state, trace, violations | | ProjectionEffect | Type | Union of all effect types |

Usage

import { createProjectionEngine } from 'koura-core';
import type { ProjectionDomain, ProjectionRule, ProjectionPolicy } from 'koura-core';

interface MyDomain extends ProjectionDomain {
  Source: MySource;
  Facts: MyFacts;
  State: MyState;
  Derived: MyDerived;
}

const engine = createProjectionEngine<MyDomain>();
const result = engine.run(input, rules, policy);

Concepts

Rules emit effects (derive, require, prefer, transform, diagnose) as pure data — no closures or callbacks. The engine collects effects per phase, delegates to an executor, and records a trace of everything that happened.

Transform effects are declarative descriptors with target, operation, and params fields. The default executor supports the built-in set-field operation; domain adapters provide custom executors for domain-specific operations.

See docs/CONCEPTS.md for details and docs/INVARIANTS.md for architectural constraints.