# configuration/strings/bnf.strings.ts

> 149 lines of code and 6 definitions.

Tree: Site tree
Language: typescript
Layer: product
Canonical: https://banes-lab.com/anatomy/tree#file-configuration-strings-bnf-strings-ts
Source text: https://banes-lab.com/assets/sources/source.281c9588aa68f96e5d01bfb2a039089b13228d353e2735e8ef9f5598cf0b79ce.generated.txt

## Definitions

- `category` (lexical_declaration, line 115)
- `BNF_TITLE` (lexical_declaration, line 9)
- `PLANNING_RULES` (lexical_declaration, line 11)
- `STATEMENT_RULES` (lexical_declaration, line 55)
- `EXPRESSION_RULES` (lexical_declaration, line 88)
- `BNF_SECTION` (lexical_declaration, line 123, exported)

## Uses

- [core/converters/grammar.converter.ts](https://banes-lab.com/source/tree/core/converters/grammar.converter.ts.md)

## Source

```typescript
import { COORDINATION_RULES, FLOWCHART_RULES } from "#configuration/strings/bnf.fragment.strings";
import type { Section, Subsection } from "#types/document.types";
import { BNF_LANGUAGE } from "#configuration/constants/code.constants";
import { BNF_SECTION_ICON } from "#configuration/icons/grammar.icons";
import { BNF_SECTION_ID } from "#core/ids/grammar.ids";
import type { GrammarRule } from "#types/grammar.types";
import { joinRules } from "#core/converters/grammar.converter";

const BNF_TITLE = "BNF grammar";

const PLANNING_RULES: readonly GrammarRule[] = [
    {
        grammar:
            '<instruction> ::= <frontmatter> <optional_meta_block> <optional_document_declaration> <body>\n<frontmatter> ::= "---" <yaml_content> "---"\n<optional_meta_block> ::= <meta_block> | ε\n<optional_document_declaration> ::= <document_declaration> | ε\n<document_declaration> ::= "THIS" <document_type> <document_verb> <description>\n<document_type> ::= "AGENT" | "WORKFLOW" | "PROTOCOL" | "POLICY" | "CHECKLIST" | "TEMPLATE" | "TASK" | "INSTRUCTION" | "PROMPT" | "COMMAND" | "TEST"\n| "DEBUG" | "VERIFICATION" | "DISTILLATION" | "AUDIT" | "TRANSLATION" | "COMPOSITION"\n<document_verb> ::= "IS" | "ENFORCES" | "EXECUTES" | "HAS" | "PERFORMS" | "PROVIDES" | "IMPLEMENTS" | "DEFINES" | "MANAGES" | "COORDINATES" | "GENERATES"\n| "RESOLVES" | "FINDS" | "FIXES" | "VERIFIES" | "CLASSIFIES" | "DISTILLS" | "ABSTRACTS" | "ELIMINATES" | "AUDITS" | "MEASURES" | "SCORES" | "CORRECTS" | "RENDERS" | "COMPOSES" | "FOLDS"\n<description> ::= <text>\n<body> ::= <node>+ <repair_edge>* <optional_invariant_block> <optional_report_block>\n<optional_invariant_block> ::= <invariant_block> | ε\n<optional_report_block> ::= <report_block> | ε',
        title: "Instruction",
    },
    {
        grammar:
            '<meta_block> ::= "%%" "META" "%%" ":" <meta_field>+\n<meta_field> ::= "objective" ":" <string>\n| "priority" ":" <authority_chain>\n| "trust" ":" <trust_assignment> ("," <trust_assignment>)*\n| "jurisdiction" ":" <scope> "|" "external" ":" <scope>\n| "recursion_limit" ":" <number>\n<authority_chain> ::= <identifier> (">" <identifier>)*\n<trust_assignment> ::= <identifier> "=" ("TRUSTED" | "UNTRUSTED" | <identifier>)\n<scope> ::= <text>',
        title: "Meta block",
    },
    {
        grammar:
            '<node> ::= <node_header> <node_meta_tag>* <contract> <optional_output_contract> <handoff_gate>\n<node_header> ::= "#" "NODE" <node_number> "—" <node_title> "[" <layer> "·" <axis> "·" <math_type> "·" "yields:" <shape> "]"\n<node_number> ::= <digit>+\n<node_title> ::= <text>\n<layer> ::= "epistemic" | "conative" | "evaluative"\n<axis> ::= "ontology" | "teleology" | "analysis" | "reasoning" | "formalisation" | "verification" | "representation" | "termination"\n<math_type> ::= "set-theory" | "logic" | "graph" | "algebra" | "analysis" | "optimisation" | "topology" | "computation" | "probability" | "information-theory" | "dynamical-systems"\n<shape> ::= "set" | "boolean" | "edge-list" | "ranking" | "procedure" | "artifact" | <text>\n<node_meta_tag> ::= "@purpose" ":" <string>\n| "@axis_question" ":" <string>\n| "@cue" ":" <string>\n| "@genesis" ":" <substrate_stage>\n| "@mandatory"\n<substrate_stage> ::= "existence" | "difference" | "relation" | "structure" | "transformation" | "constraint" | "emergence"',
        title: "Node",
    },
    {
        grammar:
            '<contract> ::= "CONTRACT" ":" "input" ":" <contract_input> "transform" ":" <directive>+ <optional_preserves> <optional_constraints> "output" ":" <text> <optional_freshness> <optional_handoff_summary>\n<contract_input> ::= "NODE" <node_number> <text> | <slot> | <declared_variable> | <text>\n<optional_preserves> ::= ("preserves" ":" <distinction_set>) | ε\n<distinction_set> ::= <text> ("," <text>)*\n<optional_constraints> ::= ("constraints" ":" <text>) | ε\n<optional_freshness> ::= ("freshness" ":" <fingerprint> "+" <fingerprint>) | ε\n<fingerprint> ::= <text>\n<optional_handoff_summary> ::= ("handoff" ":" <text>) | ε\n<optional_output_contract> ::= ("#" "OUTPUT" "CONTRACT" <declaration_statement>+) | ε\n<slot> ::= "{" <identifier> ("." <identifier>)* "}"\n<declared_variable> ::= <variable_name>',
        title: "Contract",
    },
    {
        grammar:
            '<handoff_gate> ::= "HANDOFF" "GATE" <optional_gate_qualifier> ":" <optional_rule_id> <check_line>+ <optional_refusal_line> <optional_standing_line> <result_line>\n<optional_gate_qualifier> ::= ("(" <text> ")") | ε\n<optional_rule_id> ::= ("rule_id" ":" <string> "yields" ":" <shape>) | ε\n<check_line> ::= <check_marker> <check_condition> "(" "evidence" ":" <text> ")" <optional_population_clause>\n<check_marker> ::= "[check]" | "ASSERT" | "REQUIRE"\n<check_condition> ::= <boolean_expr>\n<optional_population_clause> ::= <population_clause> | ε\n<population_clause> ::= "over" ":" <set> "measured" ":" <count> "/" <count>\n<set> ::= <text>\n<count> ::= <number> | <text>\n<optional_refusal_line> ::= ("refuse" ":" <condition> "before" <write>) | ε\n<write> ::= <semantic_operation> | <text>\n<optional_standing_line> ::= ("standing" ":" "moved-set" <set>) | ε\n<result_line> ::= "result" ":" "pass" "->" <next_node> ("|" <failure_name> "->" "REPAIR" "(" "owner" ":" <owner_node> ")")+ "|" "unknown" "->" "BLOCKED"\n<verdict> ::= "pass" | "fail" | "unknown"\n<next_node> ::= "NODE" <node_number> | "TERMINATE"\n<failure_name> ::= <text>\n<owner_node> ::= "NODE" <node_number> | <identifier>\n<repair_edge> ::= "#" "REPAIR" "EDGE" <text>',
        title: "Handoff gate",
    },
    {
        grammar:
            '<invariant_block> ::= "#" "CROSS-NODE" "INVARIANTS" <invariant_record>+\n<invariant_record> ::= "INVARIANT" <name> ":" <property> "over" ":" <set> "binds" ":" <parties> "objector" ":" (<check_ref> | "none")\n<name> ::= <identifier>\n<property> ::= <text>\n<parties> ::= <text>\n<check_ref> ::= "[check]" <text>',
        title: "Invariant block",
    },
    {
        grammar:
            '<report_block> ::= "REPORT" ":" <report_field>+\n<report_field> ::= "subject" ":" <node_ref>\n| "verdict" ":" <verdict>\n| "domain" ":" "declared" <count> "measured" <count>\n| "populations" ":" <partition_list>\n| "inputs" ":" <fingerprint_list>\n| "code" ":" <fingerprint>\n| "output" ":" <fingerprint>\n| "refusals" ":" <count> <reason_list>\n| "unresolved" ":" <count> <reason_list>\n| "completion" ":" "saturated" <boolean> "complete" <boolean> "verified" <boolean>\n<node_ref> ::= "NODE" <node_number>\n<partition_list> ::= <text> <count> ("," <text> <count>)*\n<fingerprint_list> ::= <text> <fingerprint> ("," <text> <fingerprint>)*\n<reason_list> ::= "[" <text> ("," <text>)* "]"',
        title: "Report block",
    },
    { grammar: '<macro> ::= "USE" "TEMPLATE" <template_name>\n<template_name> ::= <identifier>', title: "Macro" },
    {
        grammar:
            '<rule_declaration> ::= "RULE" <rule_name> ":" <rule_body>\n<rule_name> ::= <identifier>\n<rule_body> ::= <when_clause>* <directive>+\n<when_clause> ::= "WHEN" <condition> ":" <directive>+',
        title: "Rule",
    },
];

const STATEMENT_RULES: readonly GrammarRule[] = [
    {
        grammar:
            '<directive> ::= <optional_task_marker> <optional_meta_tag> <optional_context_cue> <directive_body>\n<directive_body> ::= <action_expr>\n| <control_flow>\n| <declaration_statement>\n| <transform_statement>\n| <discovery_statement>\n| <iteration_statement>\n| <function_declaration>\n| <announcement_statement>\n| <state_machine_declaration>\n| <dag_declaration>\n| <priority_queue_declaration>\n| <priority_queue_operation>\n| <surface_declaration>\n| <wait_statement>\n| <flowchart_declaration>\n| <mermaid_declaration>\n| <ascii_flowchart_block>\n| <macro>\n<optional_task_marker> ::= <task_marker> | ε\n<task_marker> ::= "[" <task_state> "]"\n<task_state> ::= " " | "x" | ">"\n<optional_meta_tag> ::= <node_meta_tag> | ε\n<optional_context_cue> ::= ("@cue" ":" <string>) | ε',
        title: "Directive",
    },
    {
        grammar:
            '<action_expr> ::= <action_verb> <modifier>* <action_target> <optional_action_args>\n<action_verb> ::= <semantic_operation>\n| "EXECUTE" | "READ" | "WRITE" | "DELETE" | "REMOVE" | "ANALYZE"\n| "CREATE" | "FIND" | "REPORT" | "VALIDATE" | "VERIFY"\n| "COLLECT" | "EXTRACT" | "LINK" | "DETERMINE" | "CLASSIFY"\n| "INVESTIGATE" | "FILTER" | "COMPARE" | "CONVERT" | "MERGE" | "SPLIT" | "MARK"\n| "SORT" | "RANK" | "ORDER" | "INSERT" | "APPEND"\n| "ADD" | "MOVE" | "COPY" | "BACKUP" | "RESTORE" | "LOAD"\n| "ITERATE" | "ATTEMPT" | "ENFORCE" | "RENAME"\n| "FAIL" | "EXIT" | "RETURN" | "WAIT" | "SEND"\n| "REDUCE" | "PROPAGATE" | "FINALIZE" | "EVIDENCE"\n| "PREDICT" | "EXPLAIN" | "REFLECT" | "ABSTRACT" | "GENERALISE" | "DESCRIBE" | "FORMALISE"\n<semantic_operation> ::= "DISCOVER_RESOURCES" | "READ_RESOURCE" | "SEARCH_CONTENT" | "ANALYZE_CONTENT" | "EXTRACT_FACTS" | "CALCULATE_METRIC"\n| "COMPOSE_ARTIFACT" | "VALIDATE_ARTIFACT" | "PERSIST_ARTIFACT" | "EXECUTE_TOOL" | "REQUEST_DECISION" | "REPORT_RESULT"\n<modifier> ::= "MUST" | "NEVER" | "ALWAYS" | "REQUIRED" | "MANDATORY"\n<action_target> ::= <tool_name> | <path> | <variable_name>\n<tool_name> ::= "SYSTEM" | "USER" | "SERVICE"\n<optional_action_args> ::= <parenthesized_args> | <bare_args> | ε\n<parenthesized_args> ::= "(" <arg_list> ")"\n<bare_args> ::= <arg_list>\n<arg_list> ::= <arg> ("," <arg>)*\n<arg> ::= <identifier> | <literal> | <expression>',
        title: "Action expression",
    },
    {
        grammar:
            '<control_flow> ::= <if_statement>\n| <for_loop>\n| <while_loop>\n| <try_catch>\n| <goto_statement>\n| <label_declaration>\n| <flow_marker>\n<if_statement> ::= "IF" <condition> ":" <directive>+\n("ELSE" "IF" <condition> ":" <directive>+)*\n<optional_else_clause>\n<optional_else_clause> ::= ("ELSE" ":" <directive>+) | ε\n<for_loop> ::= "FOR" "EACH" <iterator> "IN" <collection> ":" <directive>+\n<while_loop> ::= "WHILE" <condition> ":" <directive>+\n<try_catch> ::= "TRY" ":" <directive>+\n"CATCH" <optional_exception_var> ":" <directive>+\n<optional_exception_var> ::= <exception_var> | ε\n<exception_var> ::= <identifier>\n<goto_statement> ::= "GOTO" <label_identifier>\n<label_declaration> ::= <label_identifier> ":"\n<label_identifier> ::= <identifier>\n<flow_marker> ::= "START" <optional_label>\n| "LOOP" <optional_backto>\n| "END"\n| "STOP"\n<optional_label> ::= <identifier> | ε\n<optional_backto> ::= ("BACKTO" <identifier>) | ε',
        title: "Control flow",
    },
    {
        grammar:
            '<declaration_statement> ::= "SET" <variable_name> "=" <expression>\n| "DECLARE" <variable_name> ":" <type_annotation>\n<type_annotation> ::= "string" | "number" | "boolean" | "array" | "object" | "file" | "context"',
        title: "Declaration statement",
    },
    {
        grammar:
            '<transform_statement> ::= <backup_directive> <edit_directive> <optional_analyze_directive>\n<backup_directive> ::= "BACKUP" <path> "TO" <backup_location>\n| "COPY" <path> "TO" <backup_location>\n<edit_directive> ::= "PERSIST_ARTIFACT" <artifact> "TO" <destination>\n| "WRITE" <path> <write_spec>\n| "EXECUTE_TOOL" <edit_command> "WITH" "timeout" ":" <number>\n<edit_command> ::= <identifier>\n<artifact> ::= <variable_name>\n<analyze_directive> ::= "VALIDATE_ARTIFACT" <artifact> "AGAINST" <verification_condition>\n<optional_analyze_directive> ::= <analyze_directive> | ε\n<backup_location> ::= <path>\n<write_spec> ::= "CONTENT" <string>\n| "FROM" <source_file>\n| "INTO" <destination>\n| <string>\n<source_file> ::= <path>\n<destination> ::= <path>\n<verification_condition> ::= <condition>',
        title: "Transform statement",
    },
    {
        grammar:
            '<discovery_statement> ::= <discovery_action> <optional_verification_check>\n<discovery_action> ::= "DISCOVER_RESOURCES" <pattern> <optional_scope> "INTO" <collection_var>\n| "SEARCH_CONTENT" <search_scope> "FOR" <search_term> "INTO" <collection_var>\n| "FIND" <search_term> "IN" <search_location>\n<verification_check> ::= "IF" "exists" ":" <directive>+\n| "ANALYZE" <expression> <comparison_op> <expression>\n<optional_verification_check> ::= <verification_check> | ε\n<optional_scope> ::= "IN" <search_scope> | ε\n<search_scope> ::= <path>\n<search_location> ::= <path>\n<search_term> ::= <string>\n<collection_var> ::= <variable_name>',
        title: "Discovery statement",
    },
];

const EXPRESSION_RULES: readonly GrammarRule[] = [
    {
        grammar:
            '<expression> ::= <pipeline_expr>\n<pipeline_expr> ::= <logical_or_expr> ("|>" <logical_or_expr>)*\n<logical_or_expr> ::= <logical_and_expr> ("OR" <logical_and_expr>)*\n<logical_and_expr> ::= <equality_expr> ("AND" <equality_expr>)*\n<equality_expr> ::= <relational_expr> (("===" | "!==") <relational_expr>)*\n<relational_expr> ::= <additive_expr> (("<" | ">" | "<=" | ">=") <additive_expr>)*\n| <additive_expr> "MATCHES" <pattern>\n| <additive_expr> "FOR" <expression>\n| <additive_expr> "BETWEEN" <expression>\n<additive_expr> ::= <multiplicative_expr> (("+" | "-") <multiplicative_expr>)*\n<multiplicative_expr> ::= <unary_expr> (("*" | "/" | "%") <unary_expr>)*\n<unary_expr> ::= ("!" | "NOT" | "-" | "+") <postfix_expr>\n| <postfix_expr>\n<postfix_expr> ::= <primary_expr> <postfix_op>*\n<postfix_op> ::= "[" <expression> "]"\n| "." <identifier>\n| "(" <optional_arg_list> ")"\n<primary_expr> ::= <array_literal>\n| <object_literal>\n| <literal>\n| <identifier>\n| "(" <expression> ")"\n<array_literal> ::= "[" <optional_expression_list> "]"\n<object_literal> ::= "{" <optional_key_value_pairs> "}"\n<expression_list> ::= <expression> ("," <expression>)*\n<optional_expression_list> ::= <expression_list> | ε\n<key_value_pair> ::= <object_key> ":" <expression>\n<object_key> ::= <identifier> | <string> | <number>\n<key_value_pairs> ::= <key_value_pair> ("," <key_value_pair>)*\n<optional_key_value_pairs> ::= <key_value_pairs> | ε\n<function_call> ::= <function_name> "(" <optional_arg_list> ")"\n<optional_arg_list> ::= <arg_list> | ε\n<condition> ::= <expression>\n<boolean_expr> ::= <logical_or_expr>\n<verification_expr> ::= <expression>\n<term> ::= <multiplicative_expr>\n<factor> ::= <primary_expr>\n<pattern> ::= <string> | <regex_literal>\n<regex_literal> ::= "/" <regex_pattern> "/" <optional_regex_flags>\n<optional_regex_flags> ::= <regex_flags> | ε\n<regex_pattern> ::= <any_regex_character>+\n<regex_flags> ::= <letter>+\n<comparison_op> ::= "===" | "!==" | "<" | ">" | "<=" | ">="',
        title: "Expressions",
    },
    {
        grammar:
            '<identifier> ::= <letter> (<letter> | <digit> | "_" | "-")*\n<variable_name> ::= <identifier>\n<function_name> ::= <identifier>\n<node_name> ::= <identifier>\n<path> ::= <directory_path> | <file_path>\n<directory_path> ::= <path_segment> ("/" <path_segment>)* "/"\n<file_path> ::= <path_segment> ("/" <path_segment>)* <optional_file_extension>\n<path_segment> ::= <identifier>\n<optional_file_extension> ::= ("." <identifier>) | ε\n<literal> ::= <number> | <string> | <boolean>\n<number> ::= <digit>+ <optional_decimal>\n<optional_decimal> ::= ("." <digit>+) | ε\n<string> ::= \'"\' <char>* \'"\' | "\'" <char>* "\'"\n<boolean> ::= "true" | "false"\n<digit> ::= "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"\n<letter> ::= "a".."z" | "A".."Z"\n<char> ::= <any_character>\n<text> ::= <char>+\n<yaml_content> ::= <text>\n<any_character> ::= <letter> | <digit> | <whitespace> | <symbol>\n<symbol> ::= "_" | "-" | "." | "," | ":" | ";" | "!" | "?" | "@" | "#" | "$" | "%" | "^" | "&" | "*" | "(" | ")" | "[" | "]" | "{" | "}" | "<" | ">" | "/" | "\\" | "|" | "=" | "+" | "`" | "~"\n<any_regex_character> ::= <letter> | <digit> | <symbol>\n<whitespace> ::= " " | "\t" | "\n" | "\r"',
        title: "Lexical",
    },
    {
        grammar:
            '<iteration_statement> ::= <loop_header> <loop_body>\n<loop_header> ::= "FOR" "EACH" <iterator> "IN" <collection>\n<loop_body> ::= ":" <directive>+ <optional_accumulation> <optional_recursion_limit>\n<accumulation_statement> ::= "APPEND" <value> "TO" <accumulator>\n| "CREATE" <structure> "FROM" <iterator>\n| "EXTRACT" <components> "INTO" <structure>\n| "WRITE" <data> "INTO" <storage>\n| "COLLECT" <items> "INTO" <collection>\n| "SET" <state_var> "=" <state_expr>\n<recursion_limit> ::= "recursion_limit" ":" <number>\n<optional_accumulation> ::= <accumulation_statement> | ε\n<optional_recursion_limit> ::= <recursion_limit> | ε\n<iterator> ::= <variable_name>\n<collection> ::= <variable_name> | <expression>\n<value> ::= <expression>\n<accumulator> ::= <variable_name>\n<structure> ::= <variable_name>\n<components> ::= <expression>\n<data> ::= <expression>\n<items> ::= <expression>\n<storage> ::= <variable_name>\n<state_var> ::= <variable_name>\n<state_expr> ::= <expression>',
        title: "Iteration statement",
    },
    {
        grammar:
            '<function_declaration> ::= "FUNCTION" <function_name> "(" <optional_param_list> ")" ":" <directive>+\n<optional_param_list> ::= <param_list> | ε\n<param_list> ::= <parameter> ("," <parameter>)*\n<parameter> ::= <variable_name>',
        title: "Function declaration",
    },
    {
        grammar: '<announcement_statement> ::= "REPORT" <message>\n<message> ::= <string> | <expression>',
        title: "Announcement statement",
    },
];

const category = function category(title: string, content: string, rules: readonly GrammarRule[]): Subsection {
    return {
        blocks: [{ code: joinRules(rules), kind: "code", language: BNF_LANGUAGE, title: BNF_TITLE }],
        content,
        title,
    };
};

export const BNF_SECTION: Section = {
    icon: BNF_SECTION_ICON,
    id: BNF_SECTION_ID,
    intro: "PAG is defined by a context-free grammar written in Backus–Naur form (BNF), and its rules fall into five categories. The planning and coordination productions are the grammar's own records, each grounded to a reasoning record, and the statement, expression and flowchart rules expand the terminals those records leave open. The scan described in well-formedness reads tokens rather than patterns, although the grammar itself admits a pattern literal in a condition.",
    subsections: [
        category(
            "Planning rules",
            "These rules cover document structure, the meta block, nodes, contracts, handoff gates, invariant records and the report.",
            PLANNING_RULES,
        ),
        category(
            "Statement rules",
            "These rules cover directives, actions, control flow and declarations.",
            STATEMENT_RULES,
        ),
        category(
            "Expression rules",
            "These rules cover expressions, operators, literals and lexical elements.",
            EXPRESSION_RULES,
        ),
        category(
            "Coordination rules",
            "These rules cover the structure declarations, the shared surface and the semantic operations.",
            COORDINATION_RULES,
        ),
        category(
            "Flowchart rules",
            "These rules cover flowcharts written in PAG's own form, in ASCII and in Mermaid.",
            FLOWCHART_RULES,
        ),
    ],
    title: "BNF grammar",
};
```
