Playbook schema

The keys a playbook file can contain, their types, and which of them the 0.3.1 runtime actually executes. Read the "What runs in 0.3.1" section before you write rules.

What runs in 0.3.1#

A playbook is a declarative description. In 0.3.1, two engines use it in different ways:

For a compiled pack in 0.3.1:

• rules are executed on every payload, together with the example pack's built-in checks. Every match is reported in triggers. The first fatal match decides the action, with your rules checked first, in file order; with no fatal match, the first warning decides.
• hard_rules and codons are limited to the built-in ones. The compiler accepts the example pack's four hard rules and six codons only if unchanged, and rejects anything else with UnsupportedPackDeclarationError. Executing your own is Planned.
• actions, when present, must list every action the pack can return: permit_clean_payload, the four built-in actions (block_glba_ssn_leakage, block_pci_dss_pan_leakage, block_hipaa_phi_leakage, redact_and_permit_contact_pii) and <block|redact>_<id> for each of your rules. A list that leaves one out fails with UnsupportedPackDeclarationError naming the missing actions. Omitting actions is allowed.
• default_action may only be permit_clean_payload, or omitted; any other value is rejected. A payload that breaks no rule always gets permit_clean_payload.
• budget accepts only max_latency_ms (positive) and max_tokens (0 or more; the engine spends none). Any other key is rejected. max_latency_ms is checked on every decision, and a slower decision raises DecisionBudgetExceededError with its result withheld.
• invariants and remedies are accepted but not executed.

The checks run at compile time and again at load, so a pack sealed by an older compiler whose declarations break them fails to load with PackDeclarationUnsealError instead of running without them; recompile it from a corrected playbook. The examples on this site list every action, so they compile with 0.3.0 and later.

Example#

A valid playbook for a compiled pack. Quote any string value that contains ": ", such as descriptions. Unquoted, YAML reads the colon as a new key and compilation fails with CompilerError: Failed to parse YAML playbook.

pack_id: custom.internal_code_guard.v1
version: 1.0.0
name: Internal Project Code Guard
kind: compliance
description: "Blocks internal project codes: never send them outside."

budget:
  max_latency_ms: 1.0
  max_tokens: 0

actions:
  - permit_clean_payload
  - block_project_code
  - block_glba_ssn_leakage
  - block_pci_dss_pan_leakage
  - block_hipaa_phi_leakage
  - redact_and_permit_contact_pii

rules:
  - id: project_code
    type: regex
    pattern: '\bPROJ-[A-Z]+-\d+\b'
    action: block

default_action: permit_clean_payload

Compiled and run, Release PROJ-ZEUS-9 today returns action block_project_code. It has one trigger, project_code, with severity FATAL, and clean_text is [BLOCKED: Prohibited Content]. See Custom rules for the full walkthrough.

Top-level keys#

Unknown top-level keys are ignored by the compiler. There is no schema validation beyond the checks listed under Compile-time checks.

rules#

The custom rules a compiled pack executes. All of them run on every payload, in order; every match is reported, and the first fatal match decides.

codons#

Codons describe how to extract typed state from input. The example pack's six codons have this shape. A compiled pack accepts only those six, with their built-in patterns.

hard_rules#

Declarative rules over state, as used in the example pack's playbook. A compiled pack accepts only the example pack's four, unchanged; your own are Planned.

Severities#

Action naming#

Name your rule IDs in lower case with underscores (project_code) so the generated action names read well. Branch on trigger severity rather than parsing action names.

Compile-time checks#

helixor-pack compile fails with an error when:

• the file is not valid YAML, or its root is not a mapping (CompilerError);
• pack_id is missing (CompilerError);
• your license neither lists the pack_id in licensed_packs nor has the custom_playbook_compilation feature (LicenseEntitlementError);
• a declared solver is not in licensed_solvers (LicenseEntitlementError), or the solver declarations cannot be read (PlaybookParseError, a CompilerError);
• a rule has no id, an unsupported type or action, no pattern, or a pattern that is not a valid regular expression; or a codon or hard rule is not one of the example pack's built-in ones, unchanged (UnsupportedPackDeclarationError, which lists every problem).

It does not check action names against actions, or the contents of invariants and remedies. See Playbooks and Testing policies.