Docs-Builder

# State Analysis Engine (SAE)

Version: 1.1.1
Last Updated: January 23, 2026

Purpose

Track variable mutations across execution paths with statement-level granularity, enabling state-aware validation, cosmetic/mechanical classification, and governance-friendly mutation logs.

Core Concepts

• StateChange dataclass — variable name, type, operation, values, location, label, path, guard, timestamp.
• StateChangeTracker — manages paths/labels, records changes, summarizes mutations per path/label.
• Type & Operation Inference — infers type (number/bool/string/enum/collection/unknown) and operation (set/inc/dec/toggle/append/remove/merge/clear/assign) using AST and value history.
• Cosmetic vs Mechanical — classifies labels/paths that only affect presentation vs game state.
• AST + CFG Integration — maps mutations to CFG nodes; supports dynamic jump resolution via semantics catalog.

Workflow

1. Initialize tracker → start_path(path_id).
2. Traverse labels → enter_label(label).
3. Record mutations → record_change(...) as statements execute.
4. Query results → get_changes_for_path, get_changes_for_label, get_summary, get_all_paths.
5. Classify branches → classify_path_labels using semantic context.

Architecture Notes

• Statement-level CFG underpins SAE (nodes = statements; edges model SEQ/BRANCH/JUMP/RETURN).
• Terminal statements cut SEQ edges; menu choices modeled as choice nodes with BRANCH edges.
• Dynamic jumps resolved via semantics + dataflow; unresolved emit warnings but do not halt.

Use Cases

• Identify mechanical vs cosmetic branches for narrative design.
• Audit variable mutations for governance and regression tests.
• Support stat analysis (PFI) with SAE-derived symbolic evaluation.

Invariants

• Engine-agnostic: no hardcoded variable names or engine semantics.
• Pure analysis: no runtime code execution; relies on AST/CFG metadata.
• Structured logging only; no telemetry/PII content captured.