Packs and manifest

What is inside a compiled .hxpack file, what it is bound to, and the fields of embedded-pack-manifest.json, the file the typed SDKs are generated from.

Runtime 0.2.1Format version 1

The .hxpack container#

helixor-pack compile turns a playbook into a .hxpack file. helixor-pack download-pack fetches a catalog pack already sealed for your license. The file holds your compiled playbook, encrypted so that only your license can open it. The runtime decrypts it in memory and never writes the plaintext to disk.

Layout#

Offset	Size	Field
0	4 bytes	Magic: ASCII `HXPK`
4	2 bytes	Format version, big-endian. `1` in 0.2.1.
6	2 bytes	Length n of the pack ID, big-endian.
8	n bytes	`pack_id`, UTF-8, in clear text.
8 + n	12 bytes	AES-GCM nonce, random per compile.
20 + n	32 bytes	SHA-256 of the plaintext playbook, used as an integrity check after decryption.
52 + n	rest	AES-256-GCM ciphertext of the compiled playbook (canonical JSON).

The pack_id is readable without a key, so you can tell which pack a file holds. Everything else, including your rules and patterns, is encrypted.

What a pack is bound to#

Your license's content key. The encryption key is derived from the content_key in your .hxlic file. A pack compiled for one license cannot be opened with another.
The pack ID and license ID. "<pack_id>:<license_id>" is authenticated as associated data. Changing the header's pack_id, or using a different license, makes decryption fail.

Renewing a license means recompiling

A renewed or reissued license has a new license_id and content key. Packs sealed for the old license fail to open with it, with PackUnsealError: Decryption failed: content key mismatch or corrupted pack envelope. Recompile or re-download every pack when you install a new license, and deploy the license and packs together. See Packs and Licensing.

Load-time checks#

When a pack is loaded (helixor-pack run or serve), the runtime checks, in order:

The license file's signature and validity window (see License file).
The file is at least 56 bytes, the magic is HXPK and the format version is 1.
The license allows the pack: pack_id matches a licensed_packs pattern, or the license has the custom_playbook_compilation feature.
Decryption succeeds with the license's content key and associated data.
The SHA-256 of the plaintext matches the header.
Every solver the pack declares matches a licensed_solvers pattern.
Every rule, codon and hard rule in the pack is one the engine executes (see Playbook schema).

Any failure stops loading with an error, and no partial pack is used. The exceptions are listed in Errors.

Not in 0.2.1

Packs are encrypted and integrity-checked, but they are not signed by Helixor. Nothing in the file proves who compiled it; anyone holding your license can compile a pack for it. Signed packs are Planned.

embedded-pack-manifest.json#

The manifest describes a pack's typed interface: its state fields, rules and actions. SDK generation reads it to produce the typed clients (see Java and the generated models in Python). The runtime does not read it when evaluating.

Top level#

Field	Type	Value
`generator`	string	`helixor-sdk-gen`
`generation_mode`	string	`embedded_decision`
`packs`	array	One entry per pack.

Pack entry#

Field	Type	Meaning
`pack_id`	string	For example `compliance.regulatory_pii_guard.v1` (the example pack).
`schema_version`	string	`helixor.pack_manifest.v1`
`domain_name`	string	Used to name generated types, for example `RegulatoryPiiGuard` → `RegulatoryPiiGuardClient`.
`goal_id`	string	The decision this pack answers, for example `evaluate_pii_compliance`.
`actions`	string[]	The pack's actions.
`floor`	number	Confidence floor, for example `0.85`.
`budget_max_latency_ms`	number	Declared latency budget.
`state_schema`	object	Map of field name to `{name, property_type, description, required, min_value, max_value, default}`. `property_type` is for example `boolean`.
`hard_rules`	array	`{id, condition, verdict, factor, operator, threshold, threshold_str, is_boolean, factors}`. `verdict` is `refuse` or `redact`; `operator` is for example `is_true`. `factors` lists every state field the condition reads when there is more than one, and is empty otherwise.
`has_decision_head`, `decision_head`	bool, object \| null	`false` and `null` for the example pack.
`merkle_root`	string	See the note below.
`sealed_at`, `raw_pack_sha256`, `is_sealed`	string \| null, string, bool	`null`, empty and `false` in 0.2.1. Manifests are not tied to a sealed pack yet.
`solvers`	array	Solvers the pack uses. Empty for the example pack.
`codons`	string[]	Codon codes only, for example `PII_SSN_EXTRACT`.
`metadata`	object	Free-form.

Known issues in 0.2.1

merkle_root is a placeholder. It is a fixed value, not a digest of the pack or of any decisions. Don't compare against it or rely on it.
The contact rule's factor names one field. In RULE-GDPR-CONTACT-REDACT, factor is still has_email although the condition also covers phone and IP. Read factors, which lists all three.

Fixed in the next release. The example pack's manifest no longer claims a Merkle root: merkle_root is empty, because none is computed. raw_pack_sha256 is now the SHA-256 of the pack's playbook as canonical JSON (keys sorted, compact separators). The contact rule's factor is null, and factors lists the three fields.

Excerpt#

{
  "generator": "helixor-sdk-gen",
  "generation_mode": "embedded_decision",
  "packs": [
    {
      "pack_id": "compliance.regulatory_pii_guard.v1",
      "schema_version": "helixor.pack_manifest.v1",
      "domain_name": "RegulatoryPiiGuard",
      "goal_id": "evaluate_pii_compliance",
      "floor": 0.85,
      "state_schema": {
        "has_ssn": {"name": "has_ssn", "property_type": "boolean",
                    "description": "SSN detected (GLBA/FCRA)", "required": true,
                    "min_value": null, "max_value": null, "default": null}
      },
      "hard_rules": [
        {"id": "RULE-GLBA-SSN-BLOCK", "condition": "state.has_ssn is True",
         "verdict": "refuse", "factor": "has_ssn", "operator": "is_true",
         "threshold": null, "threshold_str": null, "is_boolean": true,
         "factors": []}
      ],
      "codons": ["PII_SSN_EXTRACT", "PII_CARD_EXTRACT"],
      "is_sealed": false
    }
  ]
}