Mirrored from the engine repository. Prefer reading here for a consistent experience; use GitHub for file history and blame.
This page describes methodology principles for the public Kiploks Open Core engine.
Scope
Open Core includes deterministic analytics computation:
- canonical input processing
- versioned formulas
- reproducible summary outputs
- conformance vectors for regression control
Cloud and product orchestration are out of scope for this page.
Single source of truth
- Formula logic should live in
engine/packages/core. - Integration hosts should call Open Core functions instead of duplicating math.
- Clients should render server-provided payloads and avoid recomputing final analytical verdicts on the client.
Determinism policy
For the same normalized input and config:
- output summary must be stable
- metadata hashes must be stable
- conformance fixtures must pass unchanged
Determinism depends on:
- canonical serialization
- explicit decimals policy
- explicit seed defaults
- versioned contracts and formula metadata
Validation model
Open Core uses layered validation:
- Unit tests for pure helpers in
engine/packages/core/src/*.test.ts - Conformance vectors:
v1foranalyze()v2for risk/benchmark/turnover golden fixtures
- Boundary check: no cloud-side imports in Open Core packages
- Bundle safety check: npm artifact must contain only public Open Core code
Run all checks with:
npm run engine:validate
Versioning and change impact
Releases are semver-versioned together across @kiploks/engine-* packages. When you upgrade, read [CHANGELOG.md] and align your integration with engineVersion / contractVersion in outputs.
If you change formulas, contracts, or hash policy in this repo (contributors and maintainers), follow the checklist in [CONTRIBUTING.md].