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.

Lifecycle#

Compile a playbook#

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

helixor-pack compile --playbook project_codes.yaml \
                     --license ~/.helixor/helixor.hxlic \
                     --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.hxlic
helixor-pack download-pack --pack-id compliance.regulatory_pii_guard.v1 \
                           --license ~/.helixor/helixor.hxlic

Load, run and serve a pack#

from helixor_runtime import HelixorEngine

engine = HelixorEngine.load_pack("acme.project_codes.v1.hxpack",
                                 license_file="~/.helixor/helixor.hxlic")
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 is missing, and LicenseNotFoundError (LICENSE_NOT_FOUND, also a FileNotFoundError) when no license is found; it never falls back to the built-in example pack. Without license_file, it searches HELIXOR_LICENSE_FILE, ./helixor.hxlic, then ~/.helixor/helixor.hxlic, the same order as the CLI (see where the runtime looks).

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

A loaded pack also enforces its declared actions, default_action and budget, and the license's per-minute and lifetime decision limits (changed in 0.3.0). The declarations are checked again at load, so 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.