Architecture

This section shows you how to run the Decision Runtime in production today. Each page covers one concern. It says what the runtime does for you, what you have to add around it, and what is still Planned.

Runtime 0.2.1 Planned marks designed but unshipped capabilities

How to use this section#

Learn the parts
Read Components to see what you deploy and how a pack travels from a playbook to a decision.
Pick a deployment pattern
Deployment patterns describes five reference topologies, from an in-process library to hybrid escalation. Each one comes with a diagram and example configuration.
Work through the pillars
Each pillar page gives prescriptive guidance for one concern: security, reliability, performance, operational excellence, cost or sustainability.
Map it to your cloud
Cloud deployments shows how the patterns map to managed cloud services. AWS gives reference guidance for each pattern, and AWS Well-Architected alignment maps this framework to the six AWS pillars.
Sign off with the checklist
The Production checklist lists every item from the pillar pages. Each item links back to the page that explains it.

The six pillars#

Pillar

Security

Licenses as secrets, service authentication, sensitive values in results, egress control, receipts you can trust.

Pillar

Reliability

How the runtime fails closed, health checks, license and pack rotation, rollback and concurrency.

Pillar

Performance efficiency

Latency budgets for in-process, sidecar and remote calls, how to measure them, and how to scale.

Pillar

Operational excellence

What to log, which metrics to emit, how to promote packs across environments, how to test them in CI, and runbooks.

Pillar

Cost optimization

Where the cost goes when decisions run on your own compute, and how to size it.

Pillar

Sustainability

Decisions without model inference, right-sizing, scaling to zero and avoiding repeated work.

Shared responsibility#

The runtime is a library and a small service that run inside your infrastructure. Helixor is responsible for what the runtime does inside your process. You are responsible for everything around it: the hosts, the network, secrets, identity, logging and change control.

Area	Helixor provides	You provide
Decision logic	The evaluation engine, the built-in PII pack, and compilation of your playbooks into packs.	Playbooks, golden test sets and review of every rule change before it is promoted.
Licensing	Signed `.hxlic` files. The runtime checks the Ed25519 signature and the validity dates before it unseals a pack.	Secure storage and distribution of the license file, expiry monitoring, and renewal with pack recompilation.
Pack confidentiality and integrity	AES-256-GCM encrypted `.hxpack` files, bound to one pack ID and one license, with an integrity check on unseal.	Access control on the license file (it holds the pack key), an artifact store, and version records for promoted packs.
Network	Evaluation makes no network calls.	Network policy that enforces that property, plus authentication, TLS and CORS in front of the decision service.
Data protection	Remedies that replace sensitive values with placeholders.	Keeping raw results out of logs: `matched_items` contains the sensitive values found.
Audit	A `receipt_hash` fingerprint on every result.	Durable, tamper-evident storage of receipts: signing, anchoring and retention.
Availability and scale	An engine that holds no external dependencies once a pack is loaded.	Processes, replicas, health probes, rollout and rollback.
Observability	`latency_us` and the decision fields on each result.	Logs, metrics, dashboards and alerts.
Hosted reasoning	The hosted Helixor reasoning API and its authentication.	The decision about which data may leave your perimeter, plus the escalation logic until the escalation contract ships Planned.

Design principles#

Decide close to the data#

Run the decision in the same process as the data, or next to it on loopback. Every network hop you remove is latency you do not pay and a path for sensitive data you do not have to secure. Move a decision further away only when you have a reason, such as callers in other languages or central change control.

Fail closed#

The runtime refuses to load a pack whose license is missing, tampered with, expired or not entitled. Keep that property all the way through your stack. If evaluate() raises or the decision service is unreachable, treat the payload as blocked. Never fall back to letting it through.

Keep packs versioned#

Treat a playbook like code. Keep it in source control, review every change, test it against a golden set, and promote the compiled pack through environments. Record which pack version made each decision.

Treat licenses as secrets#

A license file contains the key that decrypts the packs issued for it. Store it in a secret manager and mount it read-only. Never bake it into an image, commit it or pass it in a URL.

Enforce what the code promises#

Zero egress is a property of the evaluation code. It is not a sandbox. Back it with network policy. Receipts are fingerprints, not signatures. If you need tamper evidence, sign or anchor them yourself.

Prefer processes to threads#

Evaluation is CPU-bound. The engine's counters are not synchronized. Give each worker process its own engine and scale out with processes or replicas.

Scope of this release#

Capability	Status
In-process evaluation, streaming, HTTP/SSE/WebSocket decision service, CLI	Available
Ed25519-signed licenses, AES-256-GCM encrypted packs bound to a license	Available
Compiled native runtime library	Planned
Hardware-isolated execution: the decision core running inside a SmolVM microVM, with only the pack, license and approved inputs mounted	Planned
Signed packs, keyed and chained receipts	Planned
Host-bound licenses, license revocation, customer-managed key wrapping	Planned
Bearer-token authentication, loopback-by-default binding and CORS configuration on the decision service	Available
Readiness endpoint that reports license state on the decision service	Planned
Escalation contract between the embedded runtime and the hosted reasoning API	Planned