Playbook schema

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

What runs in 0.2.1#

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

For a compiled pack in 0.2.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.
• default_action is not used. A payload that breaks no rule always gets permit_clean_payload.
• actions is not enforced. The action names come from the rule IDs (see Action naming) and are not checked against this list.
• invariants, remedies and budget are accepted but not executed.

The same checks run again when a pack is loaded, so a pack sealed by an older compiler with declarations the engine ignores fails to load instead of running without them.

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.