helixordevelopers
User Guide

Packs

A pack is a playbook compiled for one license: encrypted, bound to that license, and loaded into memory at startup. This page covers the pack lifecycle from compile to rollout.

Developer and above

Lifecycle#

Authorplaybook.yaml Compile+ license Distribute.hxpack artifact Loadverify, unseal Evaluatein memory
The plaintext rules exist only in the author's source and in the memory of a running engine.

Compile a playbook#

helixor-pack compile --playbook project_codes.yaml \
                     --license ~/.helixor/helixor.lic \
                     --out acme.project_codes.v1.hxpack

helixor-pack compile --playbook project_codes.yaml \
                     --license ~/.helixor/helixor.lic \
                     --out acme.project_codes.v1.hxpack --remote

Compilation checks that the YAML parses and has a pack_id, and rejects any declaration a compiled pack would not execute (an unknown rule type or action, an invalid regular expression, or codons and hard rules other than the built-in ones) with UnsupportedPackDeclarationError. It then encrypts the pack with AES-256-GCM using your license's content key. The pack is bound to both the pack ID and the license ID, so it only unseals with the license it was compiled for. It is not a full schema check: test the decisions a playbook makes before you ship it (see Testing policies).

Use a catalog pack#

Helixor publishes prebuilt packs. List those your license can use and download one sealed to your license. This example downloads the example pack:

helixor-pack catalog --license ~/.helixor/helixor.lic
helixor-pack download-pack --pack-id compliance.regulatory_pii_guard.v1 \
                           --license ~/.helixor/helixor.lic

Load, run and serve a pack#

from helixor_runtime import HelixorEngine

engine = HelixorEngine.load_pack("acme.project_codes.v1.hxpack",
                                 license_file="~/.helixor/helixor.lic")
assert engine.pack_id == "acme.project_codes.v1"
print(engine.evaluate("Status of PROJ-ZEUS-9X?").action)

helixor-pack run --pack acme.project_codes.v1.hxpack --text "Status of PROJ-ZEUS-9X?"
helixor-pack serve --pack acme.project_codes.v1.hxpack --host 127.0.0.1 --port 18734

Loading a pack verifies the license, checks the container header and version, confirms the license is entitled to the pack and its solvers, decrypts it, checks its integrity digest, and validates its declarations again. Any failure raises PackUnsealError or a license error and the engine does not start. load_pack() raises FileNotFoundError when the pack or the license file is missing; it never falls back to the built-in example pack. Without license_file, it uses HELIXOR_LICENSE_FILE or ~/.helixor/helixor.lic.

A loaded pack is sealed: its rules are fixed when it is compiled, so compile_custom_rule() on it raises EnclaveCapabilityError. To change a rule, edit the playbook and compile again. In the next release compile_custom_rule() is removed from every engine and raises RemovedCapabilityError, an EnclaveCapabilityError.

In the next release a loaded pack also enforces its declared actions, default_action and budget, and the license's per-minute and lifetime decision limits. A pack compiled by 0.2.1 with an incomplete actions list fails to load with PackDeclarationUnsealError; recompile it. See Playbook schema.

Versions and promotion#

  • Treat packs as build artifacts. Compile in CI from a tagged playbook, name the file after pack_id and version, and store it in your artifact repository with its SHA-256.
  • Promote the same artifact through test, staging and production when those environments share a license. If each environment has its own license, compile once per license from the same tagged source.
  • Roll back by redeploying the previous artifact. The runtime does not prevent downgrades, so your deployment tooling should record which version is live.
  • Reload by restarting. Packs are loaded once at startup; hot reload is Planned. Roll processes gradually.

What is inside#

The container is a short header (magic bytes, format version, pack ID), a nonce, a SHA-256 of the plaintext, and the ciphertext. Details are in the pack format reference. Signing packs, so that their origin can be checked independently of the license, is Planned.