Core concepts

Eight ideas cover everything the runtime does. Each one maps to a section of the playbook file that defines a pack and to a field on the result you get back.

Pack and playbook#

A playbook is a YAML file that describes one decision. A pack is that playbook compiled and encrypted into a .hxpack file for distribution. Every pack has a stable pack_id and a version.

The runtime also carries one pack built in, the example pack (compliance.regulatory_pii_guard.v1), so HelixorEngine() works with no files at all. It decides whether text containing sensitive data may leave a system. It is there so every guide can run with no setup; it is an example of a pack, not the purpose of the runtime.

Codons and state#

A codon is a small extraction step that turns raw input into a typed fact and binds it to the decision state. A codon can add a check to its extraction, so that only valid values count.

In the example pack, the codons are pattern extractors: each one scans the text and binds a boolean such as has_ssn or has_credit_card. The card codon adds the Luhn checksum, so random 16-digit strings do not count.

- code: PII_CARD_EXTRACT
  codon_type: extract_pattern
  trigger: on_input
  checksum: luhn
  params:
    pattern: '\b(?:\d{4}[-\s]?){3}\d{4}\b'
  binds_to: has_credit_card
  remedy_template: "[REDACTED_CARD_PAN]"

Rules never look at raw text. They look at state, which keeps them short and makes the extraction step testable on its own.

Rules and severity#

A rule is a condition over state, an action to take when it holds, and a severity:

• fatal: the payload must not proceed. Block it.
• warning: the payload may proceed once it has been repaired.

Rules are also called invariants: properties that must hold for the payload to proceed unchanged. The first fatal invariant that fires decides the action. When none fire, invariants_passed is True.

Actions#

Every pack declares a closed list of actions and a default_action for payloads that break no rule. The runtime only ever returns one of the declared actions, so you can branch on them exhaustively. In the example pack, block actions start with block_, repairs with redact_ and passes with permit_.

Remedies#

A remedy is the smallest change that would make the payload satisfy the pack's invariants. The remedy is always computed, even for fatal results, so you can show a user what the pack found and what would fix it. In the example pack, the remedy replaces each match with its codon's remedy_template, so you can show what was found without showing the value itself.

input : Draft a follow-up to david@client.com or call (415) 555-0182.
action: redact_and_permit_contact_pii
clean : Draft a follow-up to [REDACTED_EMAIL] or call [REDACTED_PHONE].

Receipts#

Each result carries a receipt_hash: a SHA-256-derived fingerprint of the pack, the action, the outcome, the rules that fired and a hash of the input. Log it next to your own request ID so you can later show which pack decided a request and what it decided. Receipts today are unkeyed and not chained; see Receipts for exactly what they prove.

Licenses and tiers#

A license (.hxlic) is a JSON document signed with Ed25519 by the Helixor license authority. It names the licensee, the tier, which packs and solvers may run, which features are enabled and the validity window. The runtime verifies the signature and dates before it will unseal a pack.

Accounts and SDK downloads#

Everything you run comes in three pieces. The SDK is the same for everyone; the license and your packs are issued to your organization through your account.

SDKs are generated from one published contract, so every language exposes the same operations, fields and errors. Every release is listed in a manifest on sdk.helixor.ai Planned that records each file's SHA-256 checksum and its software bill of materials; the package registries are mirrors of that manifest. Verify a download before you install it:

shasum -a 256 helixor_runtime-0.2.1-py3-none-any.whl
# compare with the checksum published with the release

Ontology and binding layers#

For simple integrations you pass a payload to the decision core and read the result. For advanced integrations, where decisions depend on data spread across several systems, two layers sit in front of the core.

• The ontology layer is a typed vocabulary for your domain: classes such as Customer or Policy, and the relations between them, such as placedBy and memberOf. Relations carry semantics (inverse, symmetric, transitive, sub-property, chains). A reasoner derives new edges from asserted ones and records why each derived edge exists. Incoming data is first lowered into typed assertions (entities, scalars, relations, fact-relations) and admitted against the vocabulary. In open mode unknown terms become candidates; in closed mode they are rejected.
• The binding layer connects where data lives to what a decision needs. A view binds one source (a SQL table, a REST endpoint, a sheet) to one ontology class, maps its columns to class attributes, and applies row policies written in ontology terms. Reads can happen live against the source instead of copying it. When several sources describe the same entity, a fusion step picks one value per attribute and records why it won.

These layers are covered in depth under Advanced integration: Ontology, Data binding and zero-copy access, and Resolving overlapping sources.

Putting it together#