BranchPy
Log in

Docs-Builder

# Semantics

Version: 1.1.1
Last Updated: January 23, 2026

Purpose

Semantic layer standardizes meaning across scripts, mapping AST constructs and helper functions to canonical actions that power CFG, propagation, governance, and analytics.

Canonical Actions

  • Control Flow: JUMP, CALL, RETURN, GUARD
  • State: SET/ASSIGN (incl. increments)
  • I/O: IO (dialogue, media, input)
  • Reserved: YIELD, IMPORT, DEFINE, UNKNOWN

Core Types

  • SemanticAction / SemanticActionType — classify intent (is_control_flow/is_state_change/is_observable).
  • SemanticNode — CFG node with semantic annotations and helpers (add_action, get_actions_by_type).
  • FunctionProvider / DefaultFunctionProvider — maps functions to semantic actions; supports custom registration.
  • SemanticTraceExporter — exports semantic trace JSONL (header/actions/footer) for governance and debugging.

Pipeline

AST (PythonASTParser) → Function Provider resolution → Semantic actions attached →
CFG nodes/edges enriched → Trace export (optional)

Semantics Schema (YAML)

  • File: .branchpy/semantics/semantics.yaml (schema v1.0)
  • Entries:
    • name: function name
    • args: placeholder names
    • effects: list of effects
  • Effect types: jump, assign, inc, toggle, custom
  • Validation: placeholders must be declared; schema validated on save/update.

Example Entry

version: '1.0'
entries:
  - name: jump_to
    args: [label]
    effects:
      - op: jump
        args:
          label: "{label}"

Cross-File Semantics & Analysis (rehomed)

From deferred extract:

  • PythonASTParser.parse_file/parse_python_block → ParseResult with nodes/functions/imports/complexity.
  • CrossFileTracker → add files, resolve references, find unreachable/conflicting labels, build label graph.
  • ExpressionPropagationEngine.analyze_file → PropagationResult (variable states, warnings, confidence, timing), cacheable.

Integration Points

  • CFG: semantic metadata on nodes/edges; dynamic jump resolution uses semantics catalog.
  • Governance: traces and coverage checks feed policy engines; unresolved semantics emit warnings, not hard failures.
  • CLI: branchpy analyze --emit-semantics, branchpy semantics2 flow, semantics endpoints (/semantics/*) for config CRUD and dry-run.

Invariants

  • Semantic mapping does not read or emit project content beyond metadata needed for actions.
  • Schema validation blocks invalid placeholders/effects.
  • Trace export and flow analysis are deterministic for a given source tree.