This is a work in progress. The harness described here reflects the current state of the tooling, but it is actively evolving: new gates get added as pain points emerge, non-blocking warnings get promoted to blockers as violation counts drop, and the hook and skills infrastructure grows alongside the codebase. Treat this as a snapshot, not a finished design.

Table of Contents

• CLAUDE.md: The LLM Guidance Layer
• Language Feature Coverage Tracking
  • Feature Enums: Self-Documenting Members
  • The @covers Decorator
  • The Coverage Audit Script
  • What Uncovered Means
• The Pre-commit Pipeline
  • Talisman: Secret Detection
  • Terminology Guard
  • Black: Auto-format
  • Python FP Lint: Functional Programming Warnings
  • import-linter: Architectural Contracts
  • Full Test Suite
  • Beads Backup
• Claude Code Hooks: Pre/Post Tool Use
  • UserPromptSubmit: Contextual Invariant Injection
  • PreToolUse: The Gate Layer
• Skills and Workflow Automation
  • Superpowers: Core Development Lifecycle Skills
  • Project-Level Skills
  • Plugins: Context Injector and Python FP Lint
• The Full Picture
• Conclusion

CLAUDE.md: The LLM Guidance Layer

CLAUDE.md is Claude Code’s project instruction file. It is loaded at the start of every session and provides the model with baseline knowledge about the project. RedDragon’s CLAUDE.md is thin by design: it delegates to a set of imported files rather than encoding everything inline.

# RedDragon: Agent Instructions

#import .claude/core/project-context.md
#import .claude/core/workflow.md
#import .claude/core/implementation.md
#import .claude/core/tools-search.md
#import .claude/conditional/design-principles.md

The four core files cover: what the project is and how it is structured (project-context.md), how to interact and commit (workflow.md), coding conventions and guard rules (implementation.md), and when to use which search tool (tools-search.md). The conditional design-principles.md is also always loaded here, in addition to being injected dynamically by the UserPromptSubmit hook when relevant prompts are classified.

This layer tells the model how to work: which test directories to use, when to brainstorm before coding, how to handle Talisman warnings, which formatting tool to run. It is effective for orienting the model and establishing defaults.

What it cannot do is guarantee those defaults are followed. Guidance in a prompt is a suggestion; it degrades across long contexts, gets overridden by competing instructions, and fails silently. Liu et al. (2023), Lost in the Middle showed that retrieval performance degrades most severely for information in the middle of the context window, which is exactly where CLAUDE.md ends up as conversation history grows. The UserPromptSubmit hook re-injects invariant files on every prompt to keep guidance recent, but even that is probabilistic. “Most cases” is not a constraint. Everything below this section exists because LLM guidance alone is not sufficient.

Language Feature Coverage Tracking

Each of the 16 language frontends has a feature enum that enumerates every construct the language supports, implemented or not. A decorator on test methods links tests to enum members. An audit script computes the gap.

Feature Enums: Self-Documenting Members

Each of the 16 language frontends has a dedicated features.py file at interpreter/frontends/{lang}/features.py (COBOL lives at interpreter/cobol/features.py). Each file contains a single XxxFeature(Enum) class whose members use string values as documentation rather than auto():

class PythonFeature(Enum):
    """Semantic features of the Python language."""

    # Declarations
    VARIABLE_DECLARATION = "simple name = value assignments at statement level"
    FUNCTION_DECLARATION = "def f(...): function definitions"
    CLASS                = "class C: class body definitions"

    # Control flow
    IF_ELSE          = "if / elif / else conditional branching"
    WHILE_LOOP       = "while cond: loop statements"
    FOR_LOOP         = "for x in iterable: loop statements"
    MATCH_STATEMENT  = "match subject: structural pattern matching (Python 3.10+)"

    # Pattern Matching
    CAPTURE_PATTERN  = "case x: name capture in match cases"
    SEQUENCE_PATTERN = "case [a, b]: sequence destructuring patterns"
    MAPPING_PATTERN  = 'case {"key": v}: mapping destructuring patterns'
    ...

The string value serves a dual purpose: it acts as human-readable documentation when the enum is displayed in audit reports, and it confirms at a glance what the feature covers. There are currently 948 features defined across the 16 language enums.

The @covers Decorator

Every test method that exercises a language feature is annotated with @covers:

from tests.covers import covers
from interpreter.frontends.java.features import JavaFeature

class TestJavaInterface:
    @covers(JavaFeature.INTERFACE)
    def test_interface_method_lowering(self):
        result = run("""
            interface Greeter { String greet(String name); }
        """, "java")
        assert result == ...

The decorator is a no-op at runtime; it just attaches a _covers frozenset to the function object:

def covers(*features: Enum) -> Callable[[_F], _F]:
    def _decorator(func: _F) -> _F:
        func._covers = frozenset(features)
        return func
    return _decorator

This means zero test overhead. The metadata only matters to the audit script.

The Coverage Audit Script

scripts/feature_coverage_audit.py performs a three-phase static analysis:

Phase 1: Feature module discovery. It globs interpreter/frontends/*/features.py and interpreter/cobol/features.py, imports each module, and collects every enum member along with its string description.

Phase 2: Test file scanning. It uses Python’s ast module (not regex) to walk all test_*.py files under tests/unit/ and tests/integration/, extracting every @covers(XxxFeature.MEMBER) reference without executing any code:

def _covers_refs_in_file(path: Path) -> frozenset[FeatureRef]:
    tree = ast.parse(path.read_text())
    return frozenset(
        FeatureRef(enum_class_name=arg.value.id, member_name=arg.attr)
        for node in ast.walk(tree)
        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef))
        and node.name.startswith("test_")
        for dec in node.decorator_list
        if isinstance(dec, ast.Call)
        and isinstance(dec.func, ast.Name)
        and dec.func.id == "covers"
        for arg in dec.args
        if isinstance(arg, ast.Attribute) and isinstance(arg.value, ast.Name)
    )

Phase 3: Gap computation. For each language, the covered set (enum members that appear in at least one @covers) is subtracted from the full member set to produce the uncovered list.

The output is a JSON coverage report plus a summary table:

  c           :  33 /  48 covered  (15 uncovered)
  cobol        :  87 / 106 covered  (19 uncovered)
  cpp          :  38 /  84 covered  (46 uncovered)
  csharp       :  71 /  94 covered  (23 uncovered)
  go           :  40 /  44 covered  (4 uncovered)
  java         :  50 /  72 covered  (22 uncovered)
  javascript   :  33 /  38 covered  (5 uncovered)
  kotlin       :  51 /  59 covered  (8 uncovered)
  lua          :  19 /  25 covered  (6 uncovered)
  pascal       :  38 /  47 covered  (9 uncovered)
  php          :  46 /  55 covered  (9 uncovered)
  python       :  35 /  55 covered  (20 uncovered)
  ruby         :  67 /  72 covered  (5 uncovered)
  rust         :  46 /  60 covered  (14 uncovered)
  scala        :  43 /  53 covered  (10 uncovered)
  typescript   :  16 /  36 covered  (20 uncovered)
  ──────────────────────────────────────────────────
  TOTAL: 948 features across 16 languages, 205 uncovered

The script also supports --gaps-doc docs/frontend-lowering-gaps.md to regenerate a full Markdown report with a summary table and per-language uncovered feature lists.

What Uncovered Means

The feature enums are meant to be a comprehensive inventory of the language: every feature the language has, whether or not RedDragon supports it yet. An enum member with no @covers annotation is not a mistake in the enum; it is a documented gap: RedDragon’s frontend does not yet handle this construct.

This makes the coverage audit a living gap analysis as much as a test quality report. Running the audit tells you two things simultaneously: which features are implemented and tested, and which features are known to be missing. As of this writing there are 948 features across 16 languages, with 205 uncovered. The uncovered features are documented gaps: constructs the language has that RedDragon does not yet implement. The number moves as new features are added to the enums and implementation catches up.

The Pre-commit Pipeline

Seven gates run in sequence on every git commit. The hook logic lives in .claude/hooks/pre-commit (versioned in the repo); .git/hooks/pre-commit simply delegates to it. Blocking gates exit non-zero to abort the commit; non-blocking gates warn and continue.

flowchart TD
    classDef gate    fill:#b91c1c,stroke:#7f1d1d,color:#fff
    classDef autofix fill:#0f766e,stroke:#134e4a,color:#fff
    classDef warn    fill:#b45309,stroke:#78350f,color:#fff
    classDef stop    fill:#1f2937,stroke:#111827,color:#f87171
    classDef start   fill:#1e3a8a,stroke:#1e3a8a,color:#fff
    classDef done    fill:#15803d,stroke:#14532d,color:#fff

    GC(["git commit"]):::start

    GC        --> TAL
    TAL       -->|pass| TG
    TAL       -->|fail| S1

    TG        -->|pass| BLK
    TG        -->|violation| S2

    BLK       --> FPL
    FPL       --> IMP

    IMP       -->|pass| PYT
    IMP       -->|fail| S3

    PYT       -->|pass| BD
    PYT       -->|fail| S4

    BD        -->|pass| OK
    BD        -->|fail| S5

    TAL["Talisman\nsecret detection"]:::gate
    TG["Terminology guard\nchecks staged diff"]:::gate
    BLK["Black\nauto-format + re-stage"]:::autofix
    FPL(["python-fp-lint\nFP warnings only"]):::warn
    IMP["import-linter\n5 architectural contracts"]:::gate
    PYT["pytest\n13k+ tests  -x -q"]:::gate
    BD["Beads\nbackup"]:::gate

    S1["blocked"]:::stop
    S2["blocked"]:::stop
    S3["blocked"]:::stop
    S4["blocked"]:::stop
    S5["blocked"]:::stop

    OK(["commit created"]):::done

Talisman: Secret Detection

Talisman scans all staged files for patterns that look like secrets: API keys, tokens, private key headers, high-entropy strings. It runs before everything else. If it flags something, the commit is blocked and you must either fix the content or add an explicit whitelist entry to .talismanrc. The .talismanrc policy is append-only: existing entries are never modified, new entries are added at the end.

Terminology Guard

The terminology guard is a two-part system that prevents sensitive terms from entering tracked artifacts. A custom script at scripts/check-terminology scans staged content for a blocklist of domain-specific vocabulary that should not appear in a public repository. This operates independently of Talisman: Talisman looks for secrets, the terminology guard looks for project-specific identifiers. Both block on failure. This matters because RedDragon is used in consulting contexts where client names, system codes, and vendor identifiers must never appear in a public repository.

The blocklist lives at ~/.config/git/blocklist.txt, one regex pattern per line, case-sensitive, applied via grep -E. It covers project names, government domain identifiers, vendor framework names, and reference system codes. An exclude-list at ~/.config/git/blocklist-exclude.txt can whitelist specific file glob patterns.

At commit time, scripts/check-terminology scans the staged diff using git diff --cached --diff-filter=ACMR -U0. It only looks at added lines (lines starting with +, excluding the +++ header). If a forbidden term appears in a new or modified line, the commit is blocked with a formatted table showing the commit reference, file:line location, matched term, and 60-character context snippet with the term highlighted:

 Forbidden terms in staged changes
──────────────────────────────────────────────────────────────────────────────────────────
  COMMIT         LOCATION                       TERM       CONTEXT
──────────────────────────────────────────────────────────────────────────────────────────
  staged         src/parser.py:42               "REDACTED" ...client = REDACTEDClient()...
──────────────────────────────────────────────────────────────────────────────────────────
  1 hit(s)

  Blocklist: ~/.config/git/blocklist.txt
  Fix the content or update the blocklist to proceed.

For history scanning, scripts/scan-history performs a retroactive audit of the entire git history using the same blocklist. It runs two passes:

1. File contents: uses git log --all -G "$PATTERN" to find commits that introduced the pattern, then walks each affected file at that commit SHA with git show "$sha:$file" to extract matching lines and their locations.
2. Commit messages: scans git log --all --format='%h %s %b' for forbidden terms in the subject and body of every commit message.

Both scans produce the same formatted table output. The script is run manually (not as a hook) to audit historical exposure, typically when the blocklist is updated.

The shared formatting logic (print_table_header, print_table_row, snippet_around) lives in scripts/lib-terminology.sh, which both the pre-commit guard and the history scanner source. This ensures consistent output format between the commit gate and the retrospective scan.

At the AI agent level, the bd-terminology-guard.sh PreToolUse hook intercepts Beads write commands before they reach the issue tracker. This catches the case where the AI composes an issue title or body containing a sensitive term; without this hook, the term could end up in the issue database even though it never touches a file.

Black: Auto-format

Black runs on the entire repository and is non-blocking in the sense that it auto-corrects and re-stages the formatted files (git add -u) before the later gates run. If you commit with non-Black-formatted code, the commit still goes through, but the staged content becomes Black-formatted.

Python FP Lint: Functional Programming Warnings

python-fp-lint is a custom linter that enforces functional programming conventions across interpreter/. It runs three backends in sequence, each responsible for a different class of violation.

The obvious alternative for structural rules would be Semgrep, but Semgrep’s rule registry and advanced features are gated behind account creation and a paywall, and I firmly believe that useful software should be free. ast-grep is fully open, runs entirely offline, and its YAML rule format is simpler for custom rules. For the patterns needed here (single-node structural matches on mutation syntax), it is more than sufficient.

Backend 1: ast-grep (structural pattern rules). Twenty-eight custom YAML rules match syntactic mutation patterns that ast-grep can detect with a single-node structural match. The rules cover direct mutation (subscript assignment d[k] = v, augmented assignment x += y, attribute mutation self.x = y, loop mutation), collection mutation methods (list.append/insert/remove/pop/extend, set.add/discard, dict.update/clear/setdefault), and annotation hygiene (list/dict parameter types, unfrozen dataclasses, None-defaulted parameters). Using ast-grep here rather than regex is deliberate: these are multi-token structural patterns ($OBJ[$KEY] = $VAL, @dataclass without frozen=True) that span more than one token and would require fragile regexes or a full parser to match correctly otherwise.

Backend 2: Ruff (general code quality). The selected rule sets are E/W (pycodestyle), F (Pyflakes), I (isort), B (flake8-bugbear), UP (pyupgrade), SIM (flake8-simplify), RUF (Ruff-specific), BLE (blind-except), T20 (print statements), TID252 (tidy-imports), and C901 (McCabe complexity). These cover standard quality checks that have nothing to do with FP style but are useful to have in a single pass.

Backend 3: beniget (def-use chain reassignment detection). Variable reassignment (binding the same name twice in the same scope) cannot be detected by ast-grep, because the pattern spans multiple statements and requires knowing whether a name was already defined earlier in the same scope. beniget builds a def-use chain for each Python module by walking the AST and tracking every definition and use of every name. The ReassignmentGate queries duc.locals to find names with more than one definition node in the same scope and reports the second and subsequent assignments as violations.

Current limitation: this only catches local variable reassignment. Object member reassignment (self.x = y) is not detected by this backend; those cases are caught by the no-attribute-augmented-mutation ast-grep rule, which covers augmented assignment only (self.x += y), not simple attribute writes.

Currently non-blocking (|| true): the codebase has accumulated violations from before the linter existed, and the migration toward functional patterns is incremental. The intent is to make it blocking once the violation count reaches zero.

The linter lives in its own venv at ~/.claude/plugins/python-fp-lint/venv/ and is invoked directly:

~/.claude/plugins/python-fp-lint/venv/bin/python \
    -m python_fp_lint check "$REPO_ROOT/interpreter/" || true

import-linter: Architectural Contracts

import-linter enforces five architectural contracts:

These are blocking. A contract violation fails the commit.

Full Test Suite

poetry run python -m pytest tests/ -x -q runs all 13,000+ tests with fail-fast (-x). This is the most expensive gate (~50 seconds) but it runs last, after all the cheaper gates have passed. It is blocking.

One deliberate omission: coverage measurement (--cov) is not part of the pre-commit hook. At 13,000+ tests, adding coverage instrumentation locally would push commit time past the point of acceptability. Coverage runs in CI instead, where the cost is paid asynchronously and doesn’t interrupt the development loop.

Beads Backup

Beads is the issue tracker used for this project. The pre-commit hook calls bd backup to snapshot the issue database before the commit lands. This ensures the issue tracker state is always in sync with the code history. Blocking: if the backup fails, the commit is blocked.

Claude Code Hooks: Pre/Post Tool Use

Shell scripts wired into Claude Code’s event system. UserPromptSubmit injects project invariants into every prompt. PreToolUse blocks edits that violate architectural or terminology constraints.

Claude Code’s hook system allows shell scripts to intercept tool calls before they execute (PreToolUse). RedDragon uses this to enforce workflow discipline at the point where the AI agent is making edits, not just at commit time.

All hooks are configured in .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      { "matcher": "Grep",  "hooks": [{ "command": "...ast-grep advisory..." }] },
      { "hooks":            [{ "command": "bd-terminology-guard.sh" }] },
      { "matcher": "Edit",  "hooks": [{ "command": "lint-check.sh" }] },
      { "matcher": "Write", "hooks": [{ "command": "lint-check.sh" }] }
    ],
    "UserPromptSubmit": [{ "hooks": [{ "command": "user-prompt-submit.sh" }] }],
  }
}

UserPromptSubmit: Contextual Invariant Injection

Every time a message is submitted, user-prompt-submit.sh classifies the prompt using keyword matching and injects the relevant invariant files into the conversation context. The classification is purely lexical (no LLM involved):

# Keyword families → context categories
if grep -qiEw 'implement|add|build|create|fix|feature|...'; then
  DESIGN=1; TESTING=1; REFACTORING=1; SKILLS=1
fi
if grep -qiEw 'test|tdd|assert|coverage|...'; then
  TESTING=1
fi
if grep -qiEw 'refactor|rename|extract|move|...'; then
  DESIGN=1; REFACTORING=1; SKILLS=1
fi
if grep -qiEw 'review|pr|diff|...'; then
  REVIEW=1
fi

The injected invariant files live in .claude/core/ (always injected) and .claude/conditional/ (injected when the corresponding category fires). This means a prompt like “implement COBOL array support” automatically injects design principles, testing patterns, and tools/skills context, while a prompt like “what does this function do?” only injects core context.

What gets injected. The invariant files are split into two directories:

• .claude/core/: four files injected on every prompt regardless of classification: project-context.md (language, toolchain, module map), workflow.md (interaction style, commit protocol), implementation.md (coding conventions, guard rules), tools-search.md (when to use ast-grep vs grep vs the graph MCP).
• .claude/conditional/: five files injected only when the corresponding category fires: design-principles.md (DESIGN), testing-patterns.md (TESTING), refactoring.md (REFACTORING), tools-skills.md (SKILLS), code-review.md (REVIEW).

A prompt classified as DESIGN+TESTING+REFACTORING+SKILLS (e.g. “implement COBOL array support”) injects all nine files. A prompt classified as none of the above (e.g. “what does this function do?”) injects only the four core files.

The /ctx slash command controls the injection gate. It is implemented as a Claude Code user command at ~/.claude/commands/ctx.md, which delegates to the ctx binary at ~/.claude/plugins/context-injector/bin/ctx:

/ctx          # toggle on ↔ off
/ctx on       # enable injection
/ctx off      # disable injection
/ctx status   # print {"active": true|false}

%%{init: {'theme': 'base', 'themeVariables': {'edgeLabelBackground': '#ffffff'}, 'flowchart': {'curve': 'basis'}}}%%
flowchart TD
    CTX["🔒 /tmp/ctx-locks/&ltmd5&gt\n<i>ctx toggle</i>"]:::lock

    subgraph hooks["Claude Code Hooks"]
        UPS["📨 UserPromptSubmit\n<i>user-prompt-submit.sh</i>"]:::hook
        PTU["🔧 PreToolUse\n<i>pre-tool-use.sh</i>"]:::hook
        SS["🚀 SessionStart\n<i>session-start.sh</i>"]:::hook
    end

    subgraph content["Project Context"]
        CORE["📁 .claude/core/*.md\n<i>always injected</i>"]:::core
        COND["📂 .claude/conditional/*.md\n<i>keyword-matched</i>"]:::cond
    end

    CTX -->|"ctx on?"| UPS
    CTX -->|"ctx on?"| PTU
    CTX -->|"ctx on?"| SS

    UPS -->|"inject"| CORE
    UPS -->|"classify keywords → inject"| COND
    PTU -->|"code-review agent? → inject"| COND
    SS -->|"inject once at start"| CORE

    classDef hook fill:#dbeafe,stroke:#3b82f6,color:#1e3a5f
    classDef lock fill:#fef9c3,stroke:#ca8a04,color:#713f12
    classDef core fill:#dcfce7,stroke:#16a34a,color:#14532d
    classDef cond fill:#fce7f3,stroke:#db2777,color:#831843

The state is a per-project lockfile at /tmp/ctx-locks/<project-hash>. The hash is derived from $PWD, so each project has an independent toggle; switching it off in one repo doesn’t affect another. The hook user-prompt-submit.sh checks for the lockfile at the start of every run; if absent, it exits immediately without injecting anything.

The injection mechanism works through Claude Code’s UserPromptSubmit hook return value: the hook writes its output to stdout, and Claude Code prepends that output to the user’s message before it reaches the model. From the model’s perspective, the invariants appear at the top of the incoming message, not as a separate system prompt. This means the injected content is visible in the conversation and can be referenced explicitly.

/ctx off is useful when you want a raw conversation without the invariant overhead: exploring an unfamiliar part of the codebase, doing a quick calculation, or asking a question where the injected design principles would be noise. /ctx on (or toggling back) restores normal operation; no session restart required.

PreToolUse: The Gate Layer

Three hooks run before tool calls:

1. ast-grep advisory (on Grep): When the agent is about to run a Grep, an advisory fires reminding it to prefer ast-grep for structural patterns (constructor shapes, multi-line call sites) and reserve Grep for simple keyword/import/constant searches.

2. Terminology guard (all Bash tool calls with bd write commands): The bd-terminology-guard.sh hook intercepts any bd create, bd update, bd note, or similar Beads write commands and checks them against the blocklist. If a sensitive term appears in the issue text, the command is blocked (exit 2) before it reaches Beads.

3. Python FP lint gate (on Edit and Write): The lint-check.sh hook receives the full tool event JSON on stdin (including the file path and the new/modified content), runs python_fp_lint hook-check, and blocks the edit if violations appear in the modified line range. Critically, this operates on the diff range: it only flags violations introduced or modified by the current edit, not pre-existing violations in unchanged lines. This prevents the linter from blocking edits in files that already had violations before you touched them.

# Exit 0 = allow, Exit 2 = block
cat | $LINT_CMD hook-check

The gate is toggled with /lint on and /lint off, which create/remove a lockfile at /tmp/ctx-lint/<project-hash>.

Skills and Workflow Automation

Hooks enforce runtime constraints at the tool level. Skills encode workflow knowledge at the task level: how to approach a problem, what questions to ask, what patterns to follow. They are loaded on demand via Claude Code’s Skill tool.

Superpowers: Core Development Lifecycle Skills

The Superpowers plugin provides a suite of lifecycle skills that cover the full development loop:

The key constraint from using-superpowers is that skills are loaded before any response, even before a clarifying question. The rule: if there is even a 1% chance a skill applies, invoke it first. Crucially, the developer does not need to explicitly trigger a skill; the agent is expected to recognise when one applies and invoke it without being asked.

Project-Level Skills

RedDragon has six project-specific skills in .claude/skills/:

tdd: The project’s TDD skill extends the Superpowers TDD skill with RedDragon-specific conventions: where integration tests go (tests/integration/), what a correct @covers annotation looks like, how to use run() to exercise the VM rather than unit-testing the lowering step in isolation.

audit-asserts: Periodic audit of test name vs. assertion mismatches. Batches test files across parallel agents (batches of ~20), collects P0/P1/P2 violations, deduplicates against existing Beads issues, and files new ones. The most recent audit (#16 as of this writing) covered 331 files and found 0 P0 violations.

grill-me: Interview mode. When invoked, the AI asks probing questions about every aspect of a plan or design, walking each branch of the decision tree and providing a recommended answer for each question. Used before committing to significant architectural changes. Useful for surfacing assumptions that haven’t been examined.

migration-planner: Activates during brainstorming when the task is a large-scale type migration (e.g., replacing str with a domain type across function signatures, dict keys, and data classes). Provides a scope-first discipline: count before you plan, don’t estimate. Provides three migration strategies (big-bang, parallel-run, incremental) with trade-off analysis.

documentation: Updates all living docs (README, ADRs, IR lowering gaps, frontend design docs, HTML presentations) to reflect current codebase state. Does not touch immutable spec files under docs/superpowers/specs/.

improve-codebase-architecture: Explores the codebase for deep module opportunities (à la Ousterhout), surfaces integration risk at module seams, and proposes refactors as Beads RFC issues.

Plugins: Context Injector and Python FP Lint

Context Injector is the plugin that powers the UserPromptSubmit hook described above. Toggle: /ctx on / /ctx off.

Python FP Lint enforces functional programming conventions at edit time. The PreToolUse gate blocks edits that introduce FP violations into the modified lines. Toggle: /lint on / /lint off. The same linter runs in the pre-commit hook as a non-blocking warning pass over the full interpreter/ directory.

Additional plugins and skill sources used in this project:

• code-review-graph: builds a Tree-sitter AST graph of the codebase for token-efficient, impact-aware code review via MCP
• claude-mem: persistent cross-session memory with timeline, search, and smart-outline MCP tools
• ast-grep agent-skill: structural code search skill; the CLAUDE.md mandate to prefer ast-grep over plain grep is enforced by a PreToolUse advisory wired to every Grep call

The Full Picture

flowchart LR
    classDef skill    fill:#6d28d9,stroke:#4c1d95,color:#fff
    classDef hook     fill:#1d4ed8,stroke:#1e3a8a,color:#fff
    classDef blocker  fill:#b91c1c,stroke:#7f1d1d,color:#fff
    classDef autofix  fill:#0f766e,stroke:#134e4a,color:#fff
    classDef advisory fill:#b45309,stroke:#78350f,color:#fff
    classDef coverage fill:#374151,stroke:#111827,color:#d1d5db
    classDef hdr      fill:#0f172a,stroke:#0f172a,color:#94a3b8

    subgraph L1["LAYER 1  ·  DESIGN TIME  ·  skills, invoked on demand"]
        direction TB
        D0["SKILL · on-demand"]:::hdr
        D1["brainstorming · structured option exploration"]:::skill
        D2["writing-plans · phased implementation plan"]:::skill
        D3["tdd · red / green / refactor loop"]:::skill
        D4["grill-me · stress-test designs before coding"]:::skill
        D5["audit-asserts · test name vs. assertion audit"]:::skill
        D6["migration-planner · scope before estimate"]:::skill
        D0 --- D1 --- D2 --- D3 --- D4 --- D5 --- D6
    end

    subgraph L2["LAYER 2  ·  EDIT TIME  ·  Claude Code hooks"]
        direction TB
        H0["HOOK · every tool call"]:::hdr
        H2["UserPromptSubmit · keyword classify + invariant inject  ·  toggleable"]:::hook
        H3["PreToolUse / Grep · prefer ast-grep advisory  ·  warn"]:::advisory
        H4["PreToolUse / Bash bd · terminology guard  ·  BLOCKING"]:::blocker
        H5["PreToolUse / Edit+Write · FP lint gate, diff-range  ·  BLOCKING"]:::blocker
        H0 --- H2 --- H3 --- H4 --- H5
    end

    subgraph L3["LAYER 3  ·  COMMIT TIME  ·  pre-commit hook, sequential"]
        direction TB
        C0["GATE · git commit"]:::hdr
        C1["Talisman · secret detection  ·  BLOCKING"]:::blocker
        C2["Terminology guard · staged diff  ·  BLOCKING"]:::blocker
        C3["Black · auto-format + re-stage  ·  AUTO-FIX"]:::autofix
        C4["python-fp-lint · FP warnings  ·  non-blocking"]:::advisory
        C5["import-linter · 5 architectural contracts  ·  BLOCKING"]:::blocker
        C6["pytest · 13k+ tests, fail-fast  ·  BLOCKING"]:::blocker
        C7["Beads backup  ·  BLOCKING"]:::blocker
        C0 --- C1 --- C2 --- C3 --- C4 --- C5 --- C6 --- C7
    end

    FC["@covers decorator + audit script\n948 features  ·  16 languages  ·  205 uncovered\ncontinuous / run anytime"]:::coverage

    L1 ==> L2 ==> L3
    FC -.-> L3

The harness operates at three layers, with feature coverage sitting orthogonal as a continuous property rather than a gate:

Layer 1, design time (skills): brainstorming structures option exploration before coding begins; tdd enforces red/green/refactor discipline; grill-me examines designs before committing to them; audit-asserts audits test name vs. assertion consistency; migration-planner scopes large changes before estimating.

Layer 2, edit time (Claude Code hooks): Every prompt gets relevant invariants injected (UserPromptSubmit). Every edit to interpreter/ is checked for FP violations in the modified line range (PreToolUse). Every Beads write is screened for sensitive terms (PreToolUse).

Layer 3, commit time (pre-commit pipeline): Secret detection, terminology, formatting, FP warnings, architectural contracts, the full test suite, and issue tracker backup run in sequence. Most are blocking; a violation stops the commit.

The three layers are designed so that violations are caught close to where they are introduced: design problems during brainstorming, bad edits before they are written to disk, and bad commits before they enter the history.

Conclusion

The goal behind this harness is reliability, discoverability, and rigour in an AI-assisted development context. Each of those properties requires a different kind of investment.

Reliability / Repeatability / Reproducibility means that a constraint either holds or it does not; it does not depend on whether the AI had the right context, or whether the right instruction was in scope, or whether the model happened to follow it this session. Every gate in the pre-commit pipeline, every PreToolUse hook, every import-linter contract, and every @covers annotation is a deterministic check. It runs the same way every time and produces the same result for the same input. Asking the AI to “remember not to import across module boundaries” or “make sure you annotate every new test with @covers” is a prompt instruction, not a constraint. Prompt instructions degrade across context boundaries, get overridden by other instructions, and fail silently. A blocking git hook does not forget.

Discoverability requires that the codebase itself be automation-friendly:

• The @covers decorator exists so that coverage auditing can be done statically, without executing tests or parsing output.
• The feature enum string values exist so that audit reports are self-describing without a separate documentation file.
• The VAR_DEFINITION_OPCODES frozenset in ir.py exists so that dataflow analysis can identify definition sites without pattern-matching over opcode names scattered across the codebase.

These are small structural choices that make the codebase queryable by scripts and agents without interpretation. A codebase that lacks these hooks forces automation to guess; a codebase that provides them allows automation to be exact.

Rigour comes from a specific division of labour: build constraints using AI, but do not rely on the AI to impose them. The terminology blocklist was written with AI assistance; the blocklist itself is a flat text file checked by a shell script. The import-linter contracts were designed with AI help; the contracts run as a deterministic linter step. The skills encode workflow knowledge refined through conversation; the skills themselves are Markdown files loaded and followed mechanically. In each case, the AI did the authoring work, but the resulting artifact is a static, executable constraint that runs without the AI. The non-deterministic layer is reserved for work that genuinely requires judgment: exploring design trade-offs, writing implementation code, interpreting test failures, deciding what to file as an issue.

Nested feedback loops. The harness is structured as a set of loops, each operating at a different granularity and cost:

• Design time (skills): fire before a line of code is written; a skill invocation costs nothing.
• Edit time (Claude Code hooks): fire before a change is saved; a PreToolUse block costs one rejected edit.
• Commit time (pre-commit pipeline): fires before a change enters history; a failed commit costs a full test run.
• Continuous (coverage audit): runs orthogonal to all three; a gap costs a backlog issue.

Each loop catches a different class of problem. The loops are deliberately ordered so that the cheapest checks run first. Problems caught in an inner loop are cheaper to fix than problems that escape to an outer one. The design goal is not to make any single gate comprehensive, but to ensure that each class of violation has a loop it cannot escape.

This is not a finished design. Some gates are still non-blocking warnings that will become blockers as violation counts drop. Some constraints that currently exist only as prompt instructions will eventually become code. The direction is consistent: push enforcement into deterministic mechanisms wherever possible, and make what remains explicit and auditable.

The code is at avishek-sen-gupta/red-dragon. RedDragon’s design is described in Designing RedDragon. The completed elimination plan is at the design document. Previous posts in this series: Building Non-Trivial Systems with an AI Coding Assistant, Anatomy of a Refactoring Using AI.

Table of Contents

• Context
• What GSD 2 Is
• What I Adopted
  • 1. Enforced Phases Per Unit of Work
  • 2. Complexity Classification
  • 3. Verification Gate
  • 4. Fresh Context for Heavy Tasks
  • 5. State on Disk
• Teething Issues
  • The Patch-on-Patch Problem
  • Brainstorm Wasn’t Enforced
  • Retroactive Issue Filing
  • Weak Integration Test Assertions
  • The Theoretical Bug
• The Reorganised CLAUDE.md
• The Test: Replacing a Stringly-Typed IR with Domain Types
  • The Problem: Strings All the Way Down
• Chapter 1: CodeLabel, The First Domino
  • The Attempted Cascade
  • The Revert and the Lesson
  • What Actually Shipped
  • The Coercion Validator Mistake
  • The Refactoring Principles That Crystallised
• Chapter 2: Register, The Pydantic Problem
  • The Boolean Truthiness Problem
  • The BRANCH_IF Comma Convention
• Chapter 3: Typed Instructions
  • The Decision: One Class Per Opcode
  • The Original Four-Phase Plan
  • The Plan That Replaced the Plan
  • The Missing Length Field
  • Layer 1 Execution
• Chapter 4: Completing the Migration with Superpowers
  • Why GSD v2 Stalled After Layer 1
  • What Superpowers Did Differently
  • The Audit That Revised the Plan
  • Layers 2 Through 5: Execution
  • Layer 5 Was Not Cleanup
• Learnings
  • On Type Hints in Python
  • On Scope
  • On Type Migrations
  • On Plans
  • On Tooling
• Takeaways

Context

I’ve been building RedDragon, a multi-language code analysis engine, across 400+ sessions with Claude Code. I wrote about that experience earlier: how CLAUDE.md rules evolved reactively, how structured memory (Beads issues, ADRs, gap analyses) solved the session-to-session continuity problem, how TDD changed the quality of AI-generated tests.

What I didn’t have was a systematic workflow framework. My CLAUDE.md was a collection of individually sensible rules, accumulated reactively over months. It worked, but it was disorganised: duplicate rules scattered across sections, no enforced phase ordering, no complexity-aware ceremony.

The entire refactoring started because I turned on Pyright. I come from statically typed languages (Java, C#, C++), and writing a 13,000-line Python project without a type checker had been bothering me. When I enabled Pyright with strict settings, the IR layer lit up with errors. label: str | None caused 83+ narrowing failures at sites that assumed non-None. operands: list[Any] was a black hole that Pyright couldn’t reason about at all. result_reg: str with "" as a sentinel meant every presence check was invisible to the type checker. The type errors weren’t bugs in the running code. They were a map of every place where the code was fragile, where a wrong assumption would pass silently.

Fixing those errors properly meant replacing the stringly-typed IR with domain types and per-opcode instruction classes. That became the refactoring.

I’d been using Claude Code with Superpowers for most of the project’s development. I wanted to try something different, both to evaluate GSD 2 as a tool and to see what workflow ideas I could take away from it. Then I stress-tested those ideas against the refactoring: replacing the single flat instruction class with a union of 31 per-opcode typed dataclasses, and migrating registers and labels from raw strings to domain types.

This post covers both: what I adopted from GSD 2 and later from Superpowers, and what happened when those patterns met a 13,000-test type migration.

What GSD 2 Is

I’d been aware of the original Get Shit Done prompt framework for a while, and had started using it lightly through Claude Code, but I’d never fully embraced it. GSD 2 gave me the opportunity to try the framework whole-heartedly. GSD 2 is a standalone CLI built on the Pi SDK that controls a coding agent’s session programmatically. It’s the evolution of the original GSD, from markdown prompts injected into Claude Code to a TypeScript application that manages context windows, dispatches work, tracks cost, detects stuck loops, and recovers from crashes. Importantly, GSD 2 let me keep using my existing infrastructure (my own ADR documents, Beads for issue tracking, and the CLAUDE.md conventions I’d built up over months) while layering its workflow discipline on top.

The workflow patterns I’m describing here (enforced phases, complexity classification, verification gates, fresh-context discipline, state-on-disk) are not GSD-2-specific. They’re engineering discipline that applies to any AI coding assistant: Claude Code directly, Cursor, Windsurf, Codex, or whatever comes next. The patterns are about how you structure work, not which tool runs it.

Here’s what I took from it.

What I Adopted

1. Enforced Phases Per Unit of Work

GSD 2 has a dispatch pipeline: research → plan → implement → verify. Every unit of work goes through these phases in order. The agent doesn’t skip ahead.

My previous CLAUDE.md had “The workflow is Brainstorm → Discuss → Plan → Write tests → Implement → Fix → Commit → Refactor”, but it was a suggestion, not an enforcement. Multiple times during the multi-file linker work, implementation started before brainstorming was complete. The linker went through four rounds of compensating patches because the initial design was written without understanding the VM’s dispatch model. A proper brainstorm phase (reading the actual VM code, not just designing on paper) would have caught the mismatch on day one.

The new rule: every non-trivial task goes through brainstorm → plan → test-first → implement → self-review → verify → commit, in that order. Do not skip phases.

flowchart LR
    B("🧠 Brainstorm"):::phase1 --> P("📐 Plan"):::phase2 --> T("🧪 Test first"):::test --> I("⚙️ Implement"):::phase3 --> R("🔍 Self-review"):::review --> V("✅ Verify gate"):::gate --> C("📦 Commit"):::done

    classDef phase1 fill:#e8f4fd,stroke:#4a90d9,stroke-width:2px,color:#1a3a5c
    classDef phase2 fill:#fff3e0,stroke:#e8a735,stroke-width:2px,color:#5c3a0a
    classDef test fill:#fce4ec,stroke:#c62828,stroke-width:2px,color:#5c0a0a
    classDef phase3 fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#3a0a3a
    classDef review fill:#fff9c4,stroke:#f9a825,stroke-width:2px,color:#5c4a0a
    classDef gate fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px,color:#1a3a1a
    classDef done fill:#e8f5e9,stroke:#2e7d32,stroke-width:3px,color:#1a3a1a

I also added a self-review step between implement and verify: scan your own diff for workaround guards, weak assertions, mutation in loops, stale docs, and missing tests before running the verification gate.

2. Complexity Classification

GSD 2 classifies each unit as light, standard, or heavy before dispatching. The classification determines model selection and timeout.

I adapted this for ceremony level:

• Light (< 50 lines, single file): brief brainstorm. Adding a node type to a dispatch table.
• Standard (50–300 lines, follows existing patterns): brainstorm identifies the pattern being followed.
• Heavy (300+ lines, new abstractions, multiple subsystems): brainstorm must produce a written design with trade-offs before any code. Break into independently-committable units. Do not attempt in a single pass.

The multi-file linker was Heavy (500+ lines, new package, touched VM, registry, API, MCP). It should have been broken into smaller units from the start. Instead it was attempted as one continuous stream, which led to the patch-on-patch problem.

flowchart TD
    T("📋 New task"):::start --> C{"Classify<br/>complexity"}:::decide

    C -- "< 50 lines,<br/>single file" --> L("💡 Light<br/><i>Brief brainstorm</i><br/><i>e.g., add node to dispatch table</i>"):::light
    C -- "50–300 lines,<br/>2–5 files" --> S("📦 Standard<br/><i>Identify pattern being followed</i><br/><i>e.g., import extraction for new lang</i>"):::standard
    C -- "300+ lines,<br/>new abstractions" --> H("🏗️ Heavy<br/><i>Written design + trade-offs</i><br/><i>Break into committable units</i><br/><i>Re-read code before each phase</i>"):::heavy

    classDef start fill:#e8f4fd,stroke:#4a90d9,stroke-width:2px,color:#1a3a5c
    classDef decide fill:#fff3e0,stroke:#e8a735,stroke-width:2px,color:#5c3a0a
    classDef light fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#1a3a1a
    classDef standard fill:#fff9c4,stroke:#f9a825,stroke-width:2px,color:#5c4a0a
    classDef heavy fill:#fce4ec,stroke:#c62828,stroke-width:2px,color:#5c0a0a

3. Verification Gate

GSD 2 runs automated verification (lint, test, typecheck) with auto-fix retries before marking a unit complete.

My CLAUDE.md had “run black” and “run tests” as separate bullet points in different sections. The .importlinter check wasn’t mentioned at all, which is how the CI pipeline broke silently with stale module paths for who knows how long.

The new rule: three checks in order before every commit: black, lint-imports, pytest. All three must pass.

poetry run python -m black .         # formatting
poetry run lint-imports               # architectural contracts
poetry run python -m pytest tests/    # full test suite

Having this as a single named concept (“verification gate”) instead of scattered bullets makes it harder to skip.

4. Fresh Context for Heavy Tasks

GSD 2 creates a fresh agent session for every dispatched unit. The LLM starts with a clean context window containing only the pre-inlined artifacts it needs. This prevents quality degradation from context accumulation.

I can’t create fresh sessions mid-conversation. But the underlying insight applies: design documents can anchor you to a flawed model. During the linker work, the initial design document described a 7-step linking process with import tables, CALL_FUNCTION rewriting, and entry-module-first ordering. Every one of those assumptions was wrong. But because the design document was in context, the implementation followed it faithfully, then spent four patches compensating for the mismatches.

The new rule: for Heavy tasks, re-read the actual code before each phase. Don’t implement from a design document without verifying its assumptions against the code you’re modifying.

5. State on Disk

GSD 2’s .gsd/ directory is the sole source of truth. No in-memory state survives across sessions. This enables crash recovery and session resumption.

I already had Beads for issue tracking and ADRs for decisions. What I was missing was the discipline of backup before every commit. Beads state lives in a Dolt database; if a session dies before backup, the issue state is lost. The bd backup command exports everything to JSONL files committed to the repo.

The new rule: bd backup before every commit. Issues filed before work starts. Prefer committed partial results over uncommitted complete attempts. If a session might end, commit with a WIP: prefix and file an issue for the remainder.

flowchart TB
    S(("🚀 Session start")):::start
    S --> R("📜 CLAUDE.md<br/><i>Rules: how to behave</i>"):::rules
    S --> A("📚 ADRs<br/><i>Why past decisions<br/>were made</i>"):::adrs
    S --> B("📋 Beads issues<br/><i>What to work on next</i>"):::issues
    S --> D("📊 Docs<br/><i>Living design docs</i>"):::docs
    R & A & B & D --> O("✅ Agent is oriented"):::done

    O --> W("⚙️ Work"):::work
    W --> BK("💾 bd backup"):::backup
    BK --> CM("📦 git commit + push"):::commit
    CM -->|"more work"| W
    CM -->|"session ending"| END("🏁 Clean state on disk"):::done

    classDef start fill:#e8f4fd,stroke:#4a90d9,stroke-width:3px,color:#1a3a5c
    classDef rules fill:#fce4ec,stroke:#c62828,stroke-width:2px,color:#5c0a0a
    classDef adrs fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#3a0a3a
    classDef issues fill:#fff3e0,stroke:#e8a735,stroke-width:2px,color:#5c3a0a
    classDef docs fill:#e8f4fd,stroke:#4a90d9,stroke-width:2px,color:#1a3a5c
    classDef done fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#1a3a1a
    classDef work fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#3a0a3a
    classDef backup fill:#fff9c4,stroke:#f9a825,stroke-width:2px,color:#5c4a0a
    classDef commit fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px,color:#1a3a1a

Teething Issues

The Patch-on-Patch Problem

The linker was where this adoption was most tested. The original design promised “zero downstream changes”: namespace labels, merge IR, and the existing VM/CFG/registry would just work. It didn’t.

The VM resolves function calls by looking up variable names in the scope chain, not by label. The VM’s CONST handler converts label strings into BoundFuncRef/ClassRef via symbol tables. Constructor dispatch uses the class name from ClassRef to look up methods. None of this is label-based. The design document didn’t account for any of it.

What followed: patch 1 (rewrite import stubs as CONST label bindings), patch 2 (pass symbol tables to ExecutionStrategies), patch 3 (keep bare names in symbol tables, not namespaced), patch 4 (insert BRANCH instructions to chain module entries), patch 5 (drop variable import stubs so they don’t overwrite concrete values).

Five patches. Each one “fixed” the immediate symptom. The underlying problem was that the design was wrong: linking at the label level doesn’t work when the VM dispatches at the scope level.

flowchart TD
    D("📄 Design:<br/>namespace labels,<br/>rewrite references"):::design
    D --> P1("🩹 Patch 1:<br/>rewrite import stubs<br/>as CONST bindings"):::patch
    P1 --> P2("🩹 Patch 2:<br/>pass symbol tables<br/>to ExecutionStrategies"):::patch
    P2 --> P3("🩹 Patch 3:<br/>bare names in<br/>symbol tables"):::patch
    P3 --> P4("🩹 Patch 4:<br/>BRANCH chains<br/>between modules"):::patch
    P4 --> P5("🩹 Patch 5:<br/>drop variable<br/>import stubs"):::patch
    P5 --> STOP("🛑 Stop.<br/>The design is wrong."):::stop
    STOP --> RW("♻️ Rewrite:<br/>499 → 311 lines<br/>one clean model"):::rewrite

    classDef design fill:#e8f4fd,stroke:#4a90d9,stroke-width:2px,color:#1a3a5c
    classDef patch fill:#fce4ec,stroke:#c62828,stroke-width:2px,color:#5c0a0a
    classDef stop fill:#ffcdd2,stroke:#b71c1c,stroke-width:3px,color:#5c0a0a
    classDef rewrite fill:#e8f5e9,stroke:#2e7d32,stroke-width:3px,color:#1a3a1a

The fix was a rewrite: strip per-module entry labels, concatenate in dependency order, drop import stubs, emit one shared entry label. 499 lines → 311 lines. One clean model instead of five compensating transforms.

If I’d had the “stop and consult when patching” rule from the start, the rewrite would have happened after patch 2, not patch 5.

Brainstorm Wasn’t Enforced

Several times during the session, I had to redirect: “brainstorm with me first”, “don’t go haring off on your own”, “should this have been a separate issue?”

The phase ordering was written down but not enforced by habit. The AI’s default is to start implementing the moment it understands the problem. The brainstorm phase needs to be explicit: present options, discuss trade-offs, take input. Not a brief internal consideration before diving into code.

This led to a new interaction rule: brainstorm collaboratively. Present options and trade-offs to the user. Do not pick an approach and start implementing without discussion.

Retroactive Issue Filing

The multi-file work started without filing issues. Bugs were discovered and fixed inline: no issue, no claim, no close. Three linker bugs (red-dragon-khfp, red-dragon-qyvn, red-dragon-q00i) were filed retroactively after I noticed the gap.

The fix was simple: make issue filing the first step, not an afterthought. “File an issue before starting work” was already in CLAUDE.md but wasn’t being followed consistently.

Weak Integration Test Assertions

After shipping multi-file support for all 16 languages, I discovered that 9 of the 15 tree-sitter language integration tests had weak assertions like assert "add" in result instead of assert result["answer"] == 30. These tests would pass even if the cross-module call returned symbolic.

This was a violation of the self-review checklist that I’d just added. The checklist says “weak assertions” is an anti-pattern to scan for. The tests were written before the checklist existed.

Strengthening them exposed two additional bugs: a Pascal frontend gap (begin...end. block not lowered) and a Pascal function return bug (Result variable not returned). Both were pre-existing single-file bugs, not linker issues, but the weak multi-file assertions had masked them.

This prompted two new rules. First: after writing tests, review every assertion for specificity. Replace assert x is not None and assert "name" in result with concrete value assertions like assert result == 30. If a concrete assertion isn’t possible, document why. Weak assertions that would pass even when the feature is broken are worse than no assertions because they give false confidence.

Second: every xfail must have a corresponding Beads issue, and the xfail reason string must reference the issue ID. An xfail without a tracked issue is a gap that never gets fixed. It just sits there, green in the test report, invisible in the backlog.

The Theoretical Bug

One of the review findings (red-dragon-lzae) was about a fragile state machine in the import stub dropper. After brainstorming, we determined the bug was theoretical: no frontend currently produces the problematic instruction pattern, and adding “just in case” code would violate the “no speculative code without tests” principle. We closed it as won’t-fix with a documentation note.

It took a brainstorming session to reach that conclusion. The first instinct (mine and the AI’s) was to write a test and fix it. Brainstorming first (“is this actually a bug?”) saved time.

The Reorganised CLAUDE.md

The adoption process surfaced how disorganised my CLAUDE.md had become. “Run black” appeared in three places. “Run tests” appeared in three places. “Brainstorm before work” appeared twice. The verification gate was split across two sections.

I rewrote it from scratch: deduplicated, restructured into a logical reading order (Project Context → Task Tracking → Workflow → Design Principles → Programming Patterns → Testing → Code Review → Implementation → Interaction), and consolidated related guidance.

245 lines → 168 lines. Same rules, less duplication, clearer structure.

The Test: Replacing a Stringly-Typed IR with Domain Types

With the GSD 2 patterns in place, the next major piece of work was replacing the IR’s instruction representation. This was where the patterns would be tested under sustained pressure.

By late March 2026, RedDragon had ~12,900 tests, 121 architectural decision records, 550+ tracked issues, and a problem: the IR was stringly-typed. Every instruction was an IRInstruction with an opcode: Opcode enum and operands: list[Any]. Labels were str | None. Registers were bare strings like "%r0". Field names, variable names, function names, operator symbols, and register references were all str, distinguished only by position in the operands list.

The Problem: Strings All the Way Down

The core instruction type looked like this:

@dataclass
class IRInstruction:
    opcode: Opcode
    operands: list[Any] = field(default_factory=list)
    result_reg: str = ""
    label: str | None = None
    source_location: SourceLocation | None = None

A BINOP instruction had operands = ["+", "%r1", "%r2"]. The operator is at index 0. The left register is at index 1. The right register is at index 2. Nothing in the type system distinguishes them. A STORE_FIELD had operands = ["%r0", "name", "%r1"]: object register, field name, value register. Swap indices 0 and 2 and you get a silent data corruption, not a type error.

The label field was str | None. 72% of instructions had label=None, causing 83+ pyright type errors at sites that assumed non-None. The result_reg field was str, with the empty string "" as the sentinel for “no result register.” Comparing a register to "" to check presence was scattered across dozens of files.

This stringly-typed design had served the project well through rapid prototyping. 15 frontends were built against it, plus a VM, a CFG builder, a dataflow analysis engine, a type inference system, an interprocedural analysis pipeline, a multi-file linker, and an MCP server. But as pyright and import-linter tightened the quality gates, the strings became the dominant source of type errors, and every new feature required the same positional-indexing boilerplate.

The goal: replace IRInstruction entirely with a union of per-opcode frozen dataclasses, where every register is a Register object, every label is a CodeLabel object, and every field is named.

What actually happened was messier. The migration proceeded in three chapters, each teaching its own lessons.

Chapter 1: CodeLabel, The First Domino

IRInstruction.label was str | None. The plan was straightforward: introduce a CodeLabel(value: str) type and a NoCodeLabel null-object singleton, replace str | None everywhere, and push the type through adjacents.

The Attempted Cascade

The first session went well. CodeLabel and NoCodeLabel were defined. IRInstruction.label was updated. 49 files were touched. 12,850 tests passed. The issue was closed.

Then I looked at the adjacents. BasicBlock.label was str. cfg.blocks was dict[str, BasicBlock]. StateUpdate.next_label was str. label_to_idx used string keys. The CodeLabel type existed, but 19 sites in the interpreter still accessed .value directly, breaking the abstraction.

I opened a new issue: “CodeLabel: eliminate .value leaks, propagate CodeLabel into BasicBlock, StateUpdate, cfg.blocks.”

And then I tried to do it in one pass.

The cascade touched ~40 files. Changing BasicBlock.label from str to CodeLabel cascaded into cfg.blocks dict keys, which cascaded into build_cfg(), which cascaded into build_registry(), which cascaded into the executor’s block lookup, which cascaded into the linker’s namespace operations, which cascaded into the type inference engine’s function signature lookup. Each change was individually simple. Together they formed a dependency chain that crossed every layer of the architecture.

The Revert and the Lesson

I reverted everything. The commit message reads:

Attempted CodeLabel propagation into cfg_types/cfg.py. Cascade touches ~40 files. Reverted to clean state, needs a dedicated session.

The lesson was not “the scope was too large.” The lesson was that I had violated my own complexity classification. This was obviously Heavy work (300+ lines, new abstractions, multiple subsystems) but I’d treated it as Standard because each individual change seemed small. The individual changes were small. The cascade was not.

What Actually Shipped

The next session took a different approach. Instead of propagating CodeLabel into all adjacents at once, I identified three independently-committable rings:

1. Eliminate .value leaks in the immediate adjacents. Push CodeLabel into BasicBlock.label, cfg.blocks keys, StateUpdate.next_label, and the handler/registry layer. One commit. 12,850 tests.

2. Push wrapping upstream. branch_targets() was returning list[str] and callers were wrapping each element in CodeLabel(...). Change branch_targets() to return list[CodeLabel] directly. Remove downstream wrapping. One commit.

3. Remove _coerce_label. A helper function that auto-converted strings to CodeLabel. It was masking call sites that should have been explicitly updated. One commit.

Each ring was a session. Each ring had its own issue. Each ring went through the verification gate independently. The result was the same as the abandoned single-pass attempt, but arrived safely.

The Coercion Validator Mistake

During the CodeLabel work, the AI proposed a Pydantic field_validator that would auto-convert incoming strings to CodeLabel. I initially accepted this. It made tests pass immediately, with no caller needing an update.

That was the problem. The validator masked every call site that was passing a raw string. Instead of failing loudly (forcing me to find and fix each caller), it silently converted. When I later tried to remove the validator, I discovered dozens of sites that had never been updated.

This produced a rule that went into CLAUDE.md’s new “Refactoring Principles” section:

No coercion validators. Do not add Pydantic field_validator or __post_init__ hacks that auto-convert strings to the domain type. These mask call sites that should be explicitly updated. If Pydantic rejects a value, the caller is wrong. Fix the caller.

The Refactoring Principles That Crystallised

The CodeLabel experience generated a full set of type-propagation guidelines. Each one came from a specific mistake:

These principles were extracted from the CodeLabel work and written into CLAUDE.md before the Register migration began. They saved significant time on every subsequent step.

Chapter 2: Register, The Pydantic Problem

With CodeLabel done, the next target was result_reg: str. The pattern was established: introduce Register(name: str) and NoRegister singleton, replace str, push through adjacents.

The definition was clean:

@dataclass(frozen=True)
class Register:
    name: str
    def __str__(self) -> str:
        return self.name
    def __eq__(self, other: object) -> bool:
        if isinstance(other, str):
            return self.name == other  # compatibility bridge
        if isinstance(other, Register):
            return self.name == other.name
        return NotImplemented

NoRegister was the null object: __str__ returned "", is_present() returned False.

The Boolean Truthiness Problem

IRInstruction.result_reg was str, and the empty string "" was the sentinel for “no result register.” Throughout the codebase, truthiness checks like if inst.result_reg: were used to test whether an instruction produced a result.

When result_reg became Register, the truthiness semantics broke. A Register("") is truthy in Python (it’s a dataclass instance, not an empty string). NoRegister is also truthy (same reason). Every if inst.result_reg: check now always evaluated to True.

The initial fix was to add __bool__ to Register:

def __bool__(self) -> bool:
    return bool(self.name)

This restored the old behaviour: Register("") was falsy, Register("%r0") was truthy, NoRegister was falsy.

But __bool__ on a domain type is a code smell. It couples the type to the semantics of one particular usage pattern (truthiness as “is present”). The better fix was explicit: replace every if inst.result_reg: with if inst.result_reg.is_present(). This was 30+ sites across the codebase.

The __bool__ method was added, used as a temporary bridge, and then removed in a separate commit after all call sites were migrated to is_present(). The commit message: “Register: remove __bool__, use explicit is_present() everywhere.”

The CodeLabel principles applied directly: push semantics to the domain type, don’t rely on Python’s implicit protocols.

The BRANCH_IF Comma Convention

BRANCH_IF stored its branch targets as operands = ["%r0", "L_true,L_false"]. Two labels concatenated with a comma in a single string. Callers split on comma to recover the label list.

This was not a design choice. It was an accidental constraint from the early days when operands was list[Any] and nobody thought about it. The comma string had survived hundreds of sessions and 12,000+ tests because it worked.

Replacing it was the right time, since we were already touching BRANCH_IF for the Register migration. The fix introduced a branch_targets: tuple[CodeLabel, ...] field on the typed BranchIf instruction, eliminating the comma-separated string entirely.

But the migration was tricky because the comma convention was load-bearing in cfg.py, dataflow.py, and registry.py. Each file had its own slightly different approach to splitting the string:

# cfg.py
targets = inst.operands[-1].split(",")

# dataflow.py
for target in inst.operands[-1].split(","):

# registry.py
branches = inst.operands[-1].split(",") if "," in str(inst.operands[-1]) else [inst.operands[-1]]

Three files, three variations, one undocumented convention. The structured branch_targets field eliminated all of them.

Chapter 3: Typed Instructions

Chapters 1 and 2 had fixed the metadata fields on IRInstruction: label became CodeLabel, result_reg became Register. But the actual payload of each instruction, the thing that made a BINOP different from a STORE_FIELD, still lived in operands: list[Any].

This was the field that Pyright couldn’t reason about at all. It accepted anything: strings, ints, CodeLabel objects, lists of CodeLabel objects, SpreadArguments wrappers. The type checker saw list[Any] and gave up. Every read from operands was untyped, every write was unchecked, and every positional convention was invisible to static analysis.

The operands bag was also the source of the most insidious class of bugs: silent positional swaps. A STORE_FIELD had operands = [obj_reg, field_name, value_reg]. If a frontend accidentally emitted operands = [field_name, obj_reg, value_reg], the type system had nothing to say. All three values were strings. The bug would surface as wrong runtime behaviour, not a type error. Every consumer of the IR had its own positional destructuring logic, and every one was a potential source of index bugs that no tool could catch statically.

The Decision: One Class Per Opcode

The IR had a single IRInstruction class carrying every instruction in the system. A CONST loading a literal, a CALL_METHOD dispatching to an object, a TRY_PUSH setting up an exception handler: all the same class, distinguished only by the opcode enum and the contents of the operands bag. Every consumer had to destructure positionally:

# What is operands[0]? Depends on the opcode.
if inst.opcode == Opcode.BINOP:
    operator = inst.operands[0]   # str: "+"
    left_reg = inst.operands[1]   # str: "%r0"
    right_reg = inst.operands[2]  # str: "%r1"
elif inst.opcode == Opcode.STORE_FIELD:
    obj_reg = inst.operands[0]    # str: "%r0"
    field_name = inst.operands[1] # str: "name"
    value_reg = inst.operands[2]  # str: "%r1"

The same index meant different things depending on the opcode. Swap two operands in a STORE_FIELD and the error is silent: both are strings, both fit in operands[2], and the type system has nothing to say about it.

The alternative was a discriminated union: one frozen dataclass per opcode, each with named fields of the correct type. A Binop has operator: str, left: Register, right: Register. A StoreField has obj_reg: Register, field_name: str, value_reg: Register. Swapping obj_reg and value_reg is still possible, but swapping field_name and value_reg is a type error because one is str and the other is Register.

The trade-off was migration cost. A single IRInstruction class was the interface for every frontend (15 tree-sitter frontends, an LLM frontend, a COBOL frontend), every handler (28 VM handlers), the CFG builder, the dataflow engine, the type inference system, the interprocedural analysis pipeline, the linker, and the MCP server. Replacing it required touching all of them. The compatibility bridge (to_typed()/to_flat() converters, Register.__eq__(str), operands properties on the typed classes) existed to make this migration incremental rather than big-bang.

The design produced 31 frozen dataclasses sharing a common InstructionBase with source_location, plus per-class fields for registers, labels, operators, names, and branch targets. The Instruction union type was the discriminant:

Instruction = (
    Const | LoadVar | DeclVar | StoreVar | Symbolic |
    Binop | Unop |
    CallFunction | CallMethod | CallUnknown |
    LoadField | StoreField | LoadFieldIndirect |
    LoadIndex | StoreIndex |
    LoadIndirect | StoreIndirect | AddressOf |
    NewObject | NewArray |
    Label_ | Branch | BranchIf |
    Return_ | Throw_ |
    TryPush | TryPop |
    AllocRegion | LoadRegion | WriteRegion |
    SetContinuation | ResumeContinuation
)

Consumer dispatch changed from dict[Opcode, handler] to dict[type, handler], and opcode checks from inst.opcode == Opcode.LABEL to isinstance(inst, Label_). Generic transformations (register rebasing in the linker, label namespacing in multi-file compilation) went from operand-by-operand iteration to inst.map_registers(fn) and inst.map_labels(fn), which introspect the dataclass fields and return a new frozen instance via dataclasses.replace().

The Original Four-Phase Plan

The initial design session produced a four-phase plan:

1. Define typed instruction classes: 30 frozen dataclasses, one per opcode
2. Migrate handler consumers: VM handlers use to_typed() for named field access
3. Migrate remaining consumers: CFG, dataflow, type inference, linker, etc.
4. Migrate frontend producers: replace emit(Opcode.X, ...) with emit_inst(TypedInstruction(...))

Phases 1–3 were completed first. Phase 4 started with common/ (190 calls migrated) and the emit_inst() infrastructure.

Then came the realisation: the plan was incomplete. The register operand fields inside typed instructions were still str. A Binop had left: str and right: str. Changing those to Register was a separate layer of work that the original plan hadn’t accounted for.

The Plan That Replaced the Plan

The original four phases were dissolved into a five-layer plan, documented in ADR-121 and a dedicated design document:

flowchart TD
    L1("Layer 1<br/>Register fields in<br/>instruction classes<br/><i>str → Register</i>"):::layer
    L2("Layer 2<br/>map_registers/map_labels<br/>on InstructionBase"):::layer
    L3("Layer 3<br/>Migrate consumers<br/><i>5 sub-issues</i>"):::layer
    L4("Layer 4<br/>Migrate producers<br/><i>19 sub-issues</i>"):::layer
    L5("Layer 5<br/>Remove the bridge<br/><i>delete IRInstruction</i>"):::layer

    L1 --> L2
    L1 --> L3
    L1 --> L4a("Layer 4a<br/>lower_expr() → Register"):::sub
    L2 --> L3a("3a: handlers<br/>+ executor"):::sub
    L2 --> L3d("3d: linker<br/>+ compiler"):::sub
    L1 --> L3b("3b: type<br/>inference"):::sub
    L1 --> L3c("3c: CFG +<br/>dataflow"):::sub
    L1 --> L3e("3e: LLM +<br/>COBOL + misc"):::sub
    L4a --> L4f("17 frontend<br/>sub-issues<br/><i>~1,357 emit() calls</i>"):::sub

    L3 --> L5
    L4f --> L5

    classDef layer fill:#e8f4fd,stroke:#4a90d9,stroke-width:2px,color:#1a3a5c
    classDef sub fill:#fff3e0,stroke:#e8a735,stroke-width:2px,color:#5c3a0a

The five-layer plan had 28 independently-trackable sub-issues. Each sub-issue was a self-contained commit with a test gate. The Register.__eq__(str) compatibility bridge would remain until Layer 5, making all preceding layers individually safe.

The key insight was decomposition granularity. Layer 4 alone had 17 sub-issues, one per frontend, because each frontend could be migrated independently. The Rust frontend had 127 emit() calls. The COBOL emit context had 9. Mixing them in one commit would have made review and revert impossible.

The Missing Length Field

Phase 1 of the original plan defined 30 typed instruction classes. Each class was a frozen dataclass with named fields instead of positional operands. The round-trip test (to_typed(inst).to_flat() == inst) was the primary verification.

The LoadRegion instruction was defined as:

@dataclass(frozen=True)
class LoadRegion(InstructionBase):
    result_reg: Register = NO_REGISTER
    region_reg: str = ""
    offset_reg: str = ""

But LOAD_REGION in the IR had four operands: region register, offset register, length, and a field name. The length field was missing from the typed class. The round-trip test caught this immediately (the to_flat() output had fewer operands than the input) but the bug existed in the first commit and had to be fixed as a follow-up.

The cause was straightforward: the AI generated the class from the opcode name and the most common operand patterns, without checking the actual _handle_load_region handler for the full operand list. The IR reference document listed the correct operands, but the class definition was generated from pattern inference, not from the spec.

Commit message: “fix: LoadRegion typed instruction, add missing length field.”

The lesson: generated code that passes a round-trip test is not necessarily correct; the test verifies internal consistency, not completeness. A class with 3 fields that round-trips perfectly to a 3-operand instruction is still wrong if the real instruction has 4 operands.

Layer 1 Execution

Layer 1 was the riskiest single commit: changing 31 fields across 21 instruction classes from str to Register, plus updating all operands properties, to_typed() converters, and to_flat() converters.

The Register.__eq__(str) bridge was supposed to make this safe: all existing string comparisons would continue to work. And it did, mostly. But several edge cases escaped the bridge:

1. COBOL literal-in-call-operand. COBOL frontends occasionally put literal values (not register names) in call argument positions. These weren’t registers; they were strings like "SPACES" or "100". Wrapping them in Register(...) was semantically wrong. The fix was an _as_register() helper that checked whether the operand looked like a register name before wrapping.

2. _resolve_reg fallback path. When the VM’s _resolve_reg couldn’t find a register in the frame, it returned the raw operand as a fallback (for symbolic execution of incomplete programs). After the migration, this fallback returned a Register object instead of a string, which leaked into TypedValue wrappers and broke downstream comparisons. The fix: _resolve_reg fallback returns str(operand), not the raw Register.

3. _is_temporary_register in dataflow. This function subscripted the register name to check character patterns: reg[1] == 'r' and reg[2:].isdigit(). After migration, reg was a Register object, and subscripting it didn’t work. The fix: convert to str before subscripting.

4. StoreIndex with SpreadArguments. Some frontends emitted STORE_INDEX with a SpreadArguments in the value_reg position, a convention for array unpacking. The value_reg field was typed as Register, not Register | SpreadArguments, so the type system rejected it. The fix: preserve SpreadArguments in StoreIndex.value_reg with a note documenting the frontend convention.

Each of these was a small fix. Together they took as long as the main migration. The commit message for Layer 1 runs to 14 lines documenting the edge cases.

All 12,924 tests passed. 22 xfailed. 1 skipped.

Chapter 4: Completing the Migration with Superpowers

Layer 1 was the riskiest single commit, and the GSD v2 workflow patterns had gotten me through it. But the five-layer plan sat at roughly 15% complete. Layers 2 through 5 still needed ~2,200 sites migrated across ~100 files. The GSD v2 patterns had gotten me through the riskiest single commit, but the remaining work stalled.

Why GSD v2 Stalled After Layer 1

The GSD v2 patterns I’d adopted were rules in CLAUDE.md: enforce phases, classify complexity, run the verification gate. They worked as guardrails. But they didn’t help with the orchestration problem: who breaks down the next 4 layers into sub-issues? Who dispatches work? Who reviews each piece before moving to the next?

With GSD v2 patterns, the agent was too eager. It would see the five-layer plan, start implementing Layer 2, hit an edge case, make a judgment call without consulting me, then discover the judgment was wrong three layers later. The “stop and consult when patching” rule was in CLAUDE.md, but the agent treated it as a suggestion, not a gate.

GSD v2 gave me process discipline (phases, verification, state on disk) but not decision discipline (when to pause, when to decompose, when to ask).

There were also practical issues. As the session grew long, GSD v2’s TUI would behave erratically: freezing the terminal window, scrolling to random sections of the session unprompted. This made it harder to stay oriented during multi-hour work.

A caveat: I did not investigate all of GSD v2’s configuration options in depth. It has settings for model selection, timeout behaviour, stuck-loop detection, and other knobs that might have helped. What I’m describing is the out-of-the-box experience with default settings applied to a Heavy refactoring.

What Superpowers Did Differently

I switched back to the Superpowers plugin for Claude Code, which I’d used for much of the project’s earlier development.

Brainstorming was a real gate. Superpowers’ brainstorming skill forced a structured conversation before any implementation. When I said “execute this plan,” it first asked five clarifying questions, one at a time, with multiple choice options and a recommendation. Layer 4 decomposition strategy? One sub-issue per frontend (option A), grouped by size tier (B), or grouped by language family (C)? I picked A. The lower_expr() signature change: bundled with frontend migration or separate atomic commit? I picked separate. These decisions shaped the entire execution.

With GSD v2 patterns alone, the agent would have made these decisions silently and started coding.

Two-stage review after every task. Superpowers dispatched a fresh subagent per task, then ran a spec compliance review (“did you build what was requested?”) followed by a code quality review (“is it well-built?”). The spec reviewer caught the Layer 1 StoreIndex.value_reg SpreadArguments guard issue. The code quality reviewer caught the types.UnionType vs typing.Union problem for Python 3.13 that would have broken map_registers() at runtime.

With GSD v2, self-review was a checklist item. With Superpowers, review was a separate agent with adversarial instructions.

Issues filed for discovered work. During Layer 3e, the agent discovered that registry.py had 3 opcode== comparisons that couldn’t be migrated because the instruction list was mixed-type. With GSD v2 patterns, this would have been noted in a commit message and forgotten. With Superpowers, I asked “are there issues filed for any of the new-found follow-up work?” The agent checked, found 4 undocumented items, and filed them immediately, each blocking the epic. The dependency graph stayed honest.

The plan was revised during execution. After Layer 3 completed, the agent checked whether the plan’s assumptions still held. The Layer 3a estimate of “~100 sites” turned out to be 4 sites (the executor was already clean). Layer 3e estimated “~40 sites” turned out to be 128 (COBOL ir_encoders dominated). The plan was rewritten mid-execution with corrected counts, updated dependency graphs, and new prerequisite issues. The design document became a living record rather than a stale spec.

The Audit That Revised the Plan

The session started with an audit. I asked the agent to examine red-dragon-0ibe and its design doc. It dispatched an exploration subagent that surveyed the entire codebase: every to_typed() call, every inst.operands[ access, every opcode== comparison, every IRInstruction( construction. The findings were a table with file, line, and count for each migration marker.

The audit revealed that the design doc’s estimates were wrong in both directions. Handlers had 0 to_typed() calls (not the estimated 72). COBOL ir_encoders.py had 106 IRInstruction constructions (not counted in the original plan at all). Type inference had a full Opcode-keyed dispatch table that needed replacement (described as “~30 sites, annotation changes only”).

This upfront survey took 10 minutes. It saved hours of mid-implementation replanning.

Layers 2 Through 5: Execution

With the revised plan, execution was systematic:

Layer 2 (2 commits, small): Register.rebase(offset) and map_registers()/map_labels() on InstructionBase. The types.UnionType fix (caught by the plan reviewer) was baked into the implementation. 22 new tests.

Layer 3 (4 commits, 5 sub-issues): Consumer migration. The agent dispatched sub-issues in parallel where dependencies allowed — 3b, 3c, 3e could start immediately after Layer 1, without waiting for Layer 2. Layer 3a was deferred entirely (blocked by COBOL literal operands). Layer 3d used the new map_registers() in the linker, deleting the old _rebase_operand helper.

Layer 4a (1 commit): lower_expr() -> Register signature change across 33 files, ~316 methods. Single atomic mechanical commit.

Layer 4 (15 commits): One per frontend. The agent dispatched batches: 5 small frontends first (C, Lua, TypeScript, C++, Scala), then 4 medium (Go, Python, JavaScript, Pascal), then 6 large (PHP, C#, Java, Kotlin, Ruby, Rust). Plus _base.py/context.py and COBOL emit_context.py. ~1,300 emit() calls converted to emit_inst().

Prerequisites (3 commits): Before Layer 5 could start, 4 discovered issues needed resolution. COBOL ir_encoders.py literal operands → emit CONST instructions for literals instead. 59 remaining COBOL frontend emit() calls. Registry mixed-type list. VM/dataflow boundary cleanup.

Layer 5 (3 commits): Delete emit() methods. Add standalone __str__ (replacing to_flat() delegation). Delete to_flat() and all flat-to-typed converters. Remove Register.__eq__(str) — which broke ~300 test sites that were fixed in a single commit. Delete IRInstruction class.

Total: ~32 commits, ~100 files modified, zero test regressions at any point. 12,944 tests passing throughout.

The subagent execution times (including test suite runs after each change) give a sense of effort per layer:

The wall clock time was longer than the subagent time because of the planning, brainstorming, review, and consultation work between subagent dispatches. The brainstorming conversation at the start of the session (decomposing layers, choosing strategies, resolving open questions) took roughly an hour before any code was written.

timeline
    title IRInstruction Elimination
    Layer 1-2 : L1 Register fields, 33 fields
               : L2a rebase method
               : L2b map_registers, map_labels
    Layer 3   : 3b type inference dispatch
               : 3c CFG, dataflow isinstance
               : 3d linker map_registers
               : 3e LLM, COBOL, registry, 128 sites
    Layer 4   : 4a lower_expr to Register
               : 15 frontends, 1300 sites
    Prerequisites : COBOL literal operands
                  : COBOL frontend emit
                  : registry cleanup
    Layer 5   : inline_ir refactor
               : delete emit, to_flat
               : remove Register eq str
               : delete IRInstruction

Layer 5 Was Not Cleanup

The plan described Layer 5 as “remove the bridge.” The actual scope was larger.

The plan said “delete IRInstruction, to_typed/to_flat, operands properties, Register.eq(str).” The survey said ~100 sites. The reality was that IRInstruction was referenced in 116 imports across 36 files. to_typed() was called at 6 normalization entry points. Register.__eq__(str) was load-bearing in ~300 test assertions and ~100 production sites.

Removing Register.__eq__(str) was the most labour-intensive step. Every assert inst.left == "%r0" became assert inst.left == Register("%r0"). Every frame.registers["%r0"] became frame.registers[Register("%r0")]. The agent fixed 300+ sites across 46 test files in a single commit — a mechanical migration, but one that required understanding each comparison’s context to choose the right fix pattern (.name extraction vs Register() wrapping vs dict key normalisation).

The IRInstruction class itself was replaced with a factory function of the same name: callers keep the same IRInstruction(opcode=Opcode.X, operands=[...]) interface, but the return value is now a typed InstructionBase subclass. This preserved backward compatibility for ~50 remaining construction sites (mostly in test helpers and COBOL inline_ir) while eliminating the class.

The remaining work — converting those ~50 construction sites to direct typed instruction construction and removing the factory — is tracked as a follow-up. The factory is a thin shim, not a compatibility bridge. The bridge is gone.

Learnings

On Type Hints in Python

I spent years writing Java, C#, C, C++, and Ruby before this project, and tried Scala and Haskell along the way. In the statically typed ones, the compiler catches the kind of errors that were invisible in this codebase for months: passing a variable name where a register was expected, comparing a label to None without narrowing, indexing into a bag of Any and hoping the position was right. Python’s dynamism made the rapid prototyping phase fast. Fifteen frontends, a VM, a type inference engine, an interprocedural analysis pipeline, all built in a few months. But the cost accumulated silently.

Turning on Pyright made that cost visible. The 83+ errors in the IR layer were not bugs in the running code. They were a map of fragility: every place where a wrong assumption would pass at runtime and corrupt data quietly. Fixing them properly required domain types, not just annotations. str with "" as a sentinel became Register with a NoRegister null object. str | None became CodeLabel with NoCodeLabel. operands: list[Any] became 31 frozen dataclasses with named typed fields.

The investment was significant: 32 commits, 100 files, two days of migration. The type hint tightening is still a work in progress; 18 primitive str and int fields remain on the instruction classes, and the broader codebase has areas where annotations are loose or absent. But the return is already visible: Pyright now catches at the edit site what previously surfaced as a wrong value three layers deep in the VM. For a project of this size, built primarily through AI-assisted development where the AI generates most of the code, that static safety net is worth more than any number of runtime tests. Tests verify behaviour you thought to check. Types prevent mistakes you didn’t think to check for.

On Scope

Scope is measured by the cascade, not the initial change. Changing BasicBlock.label from str to CodeLabel was 5 lines. That change cascaded into 40 files because the label was used as a dict key, a lookup value, a comparison target, and a format string argument across every architectural layer. I treated it as “lots of small changes” and attempted it in one session. The session was reverted. The same work, decomposed into four rings with separate issues and separate sessions, shipped cleanly.

File issues for the next ring. The CodeLabel migration into IRInstruction.label was one commit. Propagation into BasicBlock and cfg.blocks was a separate issue. Propagation into FuncRef.label and ClassRef.label was a third. Each ring was bounded, independently committable, and went through the verification gate on its own.

flowchart TD
    R0("Ring 0<br/>IRInstruction.label<br/><i>CodeLabel / NoCodeLabel</i>"):::ring0
    R1("Ring 1<br/>BasicBlock, CFG,<br/>StateUpdate, handlers"):::ring1
    R2("Ring 2<br/>FuncRef, ClassRef,<br/>FunctionEntry, InstructionLocation"):::ring2
    R3("Ring 3<br/>Remove _coerce_label,<br/>push wrapping upstream"):::ring3

    R0 -- "separate issue" --> R1
    R1 -- "separate issue" --> R2
    R2 -- "separate issue" --> R3

    classDef ring0 fill:#e8f4fd,stroke:#4a90d9,stroke-width:3px,color:#1a3a5c
    classDef ring1 fill:#fff3e0,stroke:#e8a735,stroke-width:2px,color:#5c3a0a
    classDef ring2 fill:#fce4ec,stroke:#c62828,stroke-width:2px,color:#5c0a0a
    classDef ring3 fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#1a3a1a

Classify complexity before starting, not after. The multi-file linker was obviously Heavy (500+ lines, new package, touched VM, registry, API, MCP). It was treated as a single unbroken implementation session. Breaking it into independently-committable units from the start would have produced cleaner history and caught issues earlier.

On Type Migrations

Never auto-coerce during a migration. A Pydantic validator that auto-converted str to CodeLabel made all tests pass immediately. It also masked every call site that needed updating. A failing test at a call site is information: the caller hasn’t been migrated. Silencing it with auto-coercion destroys that information.

Audit implicit protocol usages. Replacing str result registers with Register objects broke every if inst.result_reg: check because dataclass instances are always truthy in Python. When replacing a primitive with a domain type, audit bool(), len(), in, [], comparison operators, and string formatting. Each one is a potential semantic break that passes silently.

Edge cases cluster at boundaries. The four Layer 1 edge cases (COBOL literals in call operands, _resolve_reg fallback, _is_temporary_register subscripting, SpreadArguments in StoreIndex) all occurred where the type change met a convention or assumption from a different subsystem. The type change itself was mechanical. The boundary interactions were where the bugs lived.

Stringly-typed representations accumulate hidden conventions. BRANCH_IF stored branch targets as a comma-separated string. This survived 10 months and 12,000+ tests. Three files independently implemented the same split logic. None of it was documented. Discovering it during a refactoring is how it was always going to be discovered.

On Plans

The end state was clear; the intermediate steps were not. The original four-phase plan correctly described the goal (typed instructions with Register fields, no IRInstruction). What it underestimated was the number of intermediate layers needed to get there safely. Operand-level register migration was a whole layer the plan didn’t account for. The plan had to be replaced mid-execution with a five-layer plan decomposed into 28 sub-issues. Getting the destination right is the easy part. Mapping the route, with each step independently committable and testable, is where the planning effort belongs.

Round-trip tests verify consistency, not completeness. LoadRegion was defined with 3 fields. The actual instruction had 4 operands. The round-trip test passed perfectly because a 3-field class round-trips correctly to a 3-operand instruction. The bug was that the real instruction has 4 operands. Verification should cross-reference against the authoritative source (the handler, the IR spec), not just test internal consistency.

Start with an audit, not implementation. The Superpowers session started by surveying every to_typed() call, every inst.operands[ access, every opcode== comparison, every IRInstruction( construction. This took 10 minutes and revealed that the design doc’s estimates were wrong in both directions: handlers had 0 to_typed() calls (not 72), COBOL ir_encoders.py had 106 constructions (not counted at all). The upfront survey saved hours of mid-implementation replanning.

On Tooling

Start with the verification gate from day one. The .importlinter failure was avoidable. Having “run black” and “run tests” as separate loose rules instead of a single named gate made it easy to skip lint-imports entirely.

Enforce brainstorm-before-implement from session one. The linker patch-on-patch problem cost more time than the proper rewrite. A brainstorm phase that reads actual code, not just designs on paper, would have caught the VM dispatch mismatch immediately.

File issues before work, not after. Retroactive issue filing loses the intent: why was this work started? What was the expected outcome? Issues filed before work serve as specifications. Issues filed after are bookkeeping.

Takeaways

The GSD 2 patterns held up as guardrails. Five workflow patterns adopted from GSD 2, then tested against the largest refactoring in the project:

Superpowers added what GSD v2 lacked. GSD v2 gave me process discipline. Superpowers gave me decision discipline and orchestration:

The distinction matters. GSD v2 tells the agent what to do (brainstorm, then plan, then implement). Superpowers tells the agent when to stop and ask (is this the right decomposition? did the spec reviewer approve? should this discovered issue block the epic?). For a refactoring that took 32 commits across 100 files, the stopping points were where the real decisions happened.

They serve different sweet spots. I would still reach for GSD v2 for greenfield work of moderate complexity where I want to move fast: adding a new frontend, building a new analysis pass, scaffolding a new module. GSD v2’s autonomous dispatch is an advantage when the work is well-understood and doesn’t require mid-stream design decisions. For Heavy refactoring work that crosses architectural boundaries and accumulates edge cases, Superpowers’ consultation model is the better fit.

The patterns are tool-agnostic. They work whether you’re using GSD 2, Superpowers, Cursor, or any other AI coding assistant. The common thread is treating AI-assisted development as an engineering practice that needs the same discipline as human development: phase gates, complexity awareness, verification, and persistent state.

Compatibility bridges make incremental migration possible. Register.__eq__(str) was a deliberate compatibility bridge: it made Register compare equal to raw strings, letting 12,924 tests pass without modification during the migration. The plan explicitly called for removing it in Layer 5, after all consumers had been updated. Without the bridge, every layer would have been a big-bang change.

Reverts are progress. The abandoned CodeLabel cascade, attempted, reverted, and documented in the Beads issue, was not wasted time. It produced the scope analysis that made the ring-by-ring approach possible.

The plan will be wrong. Plan for that. The four-phase plan became a five-layer plan with 28 sub-issues. The CodeLabel single-pass attempt became a four-ring incremental approach. In both cases, the revised plan was better than the original, not because planning was futile, but because the first attempt revealed the real shape of the work.

Write down your refactoring principles before the next refactoring. The “Refactoring Principles” section of CLAUDE.md, written after the CodeLabel experience, prevented at least three of the same mistakes during the Register migration. Rules extracted from failures and codified before the next attempt compound over time.

The AI writes the code. You manage the scope. Across this entire migration, the AI’s code was overwhelmingly correct at the mechanical level: updating 31 fields, threading kwargs, updating converters, formatting with Black. Where it failed was scope: generating a class without checking the handler spec, proposing coercion validators that masked call sites, not flagging that operand fields needed their own migration layer. The human’s job in a type migration is not typing. It’s asking “what does this cascade into?” at every step.

The AI writes code faster than I can. It doesn’t write better code without guardrails.

Table of Contents

• The Problem
• The Tools
  • Superpowers: Enforced Design Discipline
  • Beads: Local-First Task Tracking
  • Code Simplifier: Automated Cleanup After Every Change
• Phase 1: TypedValue and BinopCoercionStrategy
  • The Design Decision That Shaped Everything
  • The Boundary Table
• Phase 2: Handler Migration
  • The Serialize/Deserialize Roundtrip
• Phase 3: Return Values
  • The Constructor Bug
• Phases 4–6: Heap and Closures
  • The Double-Wrapping Landmine
• Phase 7: Cleaning Up After Ourselves
• Detour: Builtins
  • BuiltinResult: Side Effects Should Be Declarative
  • Builtin Args: The Atomic Commit Problem
• More Detours
  • BinopCoercionStrategy Return Type
  • UnopCoercionStrategy
  • Demo Scripts and LLM Path Leaks
  • The Question That Came After
• The Shape of the Work
• Takeaways

The Problem

RedDragon is a multi-language code analysis engine with a universal IR, deterministic VM, and a type system. It parses 15 languages, lowers them to IR, and executes the IR on a virtual machine.

The VM stored values as raw Python primitives — int, str, float, bool. Type information lived in a completely separate structure: a TypeEnvironment built by a static inference pass before execution. The operators themselves never saw types. They received raw values via _resolve_reg and used Python’s native operators.

This created an obvious problem. When Java code did "int:" + 42, Python raised TypeError because it can’t concatenate str and int. The VM caught the exception and degraded the result to a SymbolicValue — a placeholder meaning “I don’t know what this is.” The concrete information was gone. Java, C#, Kotlin, and Scala all auto-stringify non-string operands in string concatenation. The VM had no way to implement this because type information was absent at the point of operation.

The fix looked straightforward: make type information available to operators. What followed was a refactoring that touched almost every layer of the VM, exposed hidden assumptions in constructor handling, revealed that builtins were bypassing the state management contract, and prompted several side detours into coercion protocols, demo scripts, and the question of whether two separate type-tracking mechanisms were still both necessary.

This post traces that arc. It’s written partly as documentation and partly because the shape of the work — the way a focused fix expanded into a system-wide migration, the side detours, the bugs that only surfaced because something else changed — is characteristic of refactoring work in general. The AI didn’t change the nature of that work. It changed the speed.

All of this was done through conversations with Claude Code, using three tools that shaped the work as much as the code decisions did: Superpowers for enforced design discipline, Beads for local-first task tracking, and Code Simplifier for automated post-implementation cleanup. The next section describes all three.

The refactoring spanned about a dozen sessions over two days. I’m including specific moments from those conversations — places where I had to course-correct, where I got frustrated with the codebase or the AI’s approach, where a question I asked led to discovering something unexpected — because the texture of those interactions is part of the story.

The Tools

Three tools ran alongside Claude Code throughout this migration. None are part of Claude Code itself — they’re open-source plugins that layer structure on top of it. I’m describing them here because the post references them repeatedly, and their constraints shaped how the work unfolded.

Superpowers: Enforced Design Discipline

Superpowers is a skill system for Claude Code. Skills are structured prompts that activate automatically based on the task at hand. They don’t add capabilities the AI doesn’t have — they enforce workflows the AI would otherwise skip.

The skills that mattered for this migration:

Brainstorming. Every major phase started here. The brainstorming skill runs a structured dialogue: it asks one clarifying question at a time, proposes alternative approaches with explicit trade-offs, and refuses to produce a design spec until you’ve agreed on the direction. It won’t let you skip to implementation. This is the skill that caught the serialize/deserialize split (Phase 2) and the BuiltinResult design (Detour) — cases where the obvious approach wasn’t the best one, and the skill’s insistence on proposing alternatives surfaced something simpler.

The brainstorming pipeline looks like this:

flowchart LR
    Q("🔍 Clarifying<br/>questions<br/><i>one at a time</i>"):::ask --> A("⚖️ Alternative<br/>approaches<br/><i>with trade-offs</i>"):::think
    A --> D{"🎯 Design<br/>decision<br/><i>user chooses</i>"}:::decide
    D -- "more questions" --> Q
    D -- "agreed" --> S("📋 Design spec"):::output

    classDef ask fill:#e8f4fd,stroke:#4a90d9,stroke-width:2px,color:#1a3a5c
    classDef think fill:#fff3e0,stroke:#e8a735,stroke-width:2px,color:#5c3a0a
    classDef decide fill:#fce4ec,stroke:#c62828,stroke-width:2px,color:#5c0a0a
    classDef output fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#1a3a1a

    linkStyle 2 stroke:#2e7d32,stroke-width:2px

The early phases (1–3) had longer brainstorming cycles — eight questions in Phase 1 before any code was discussed. By the later phases, the cycles were shorter because the patterns were established: the skill would propose an approach, I’d confirm it matched the established pattern, and we’d move to planning.

Writing-plans. Takes the design spec from brainstorming and breaks it into granular TDD steps — test first, then implementation, then verification. Each step is small enough to be a single commit. The plan for Phase 5 (heap fields) had 12 steps; the plan for the builtin args migration (Detour) explicitly mandated zero intermediate commits because the interface change was atomic.

Subagent-driven development. Dispatches fresh Claude Code agents per task from the plan, each with its own context window. The dispatching agent reviews each sub-agent’s work before accepting it. This is where the review caught the value is not None guard in Phase 3 — a sub-agent had taken a shortcut that violated the design spec, and the reviewing agent flagged it. Without the two-stage review, that shortcut would have shipped.

The full pipeline:

flowchart LR
    B("🧠 Brainstorm"):::phase1 --> SP("📋 Spec"):::phase2
    SP --> PL("📐 Plan<br/><i>TDD steps</i>"):::phase2
    PL --> SA("🤖 Sub-agents<br/><i>one per task</i>"):::phase3
    SA --> RV("🔎 Review<br/><i>two-stage</i>"):::phase4
    RV --> CM("✅ Commit"):::phase5

    classDef phase1 fill:#e8f4fd,stroke:#4a90d9,stroke-width:2px,color:#1a3a5c
    classDef phase2 fill:#fff3e0,stroke:#e8a735,stroke-width:2px,color:#5c3a0a
    classDef phase3 fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#3a0a3a
    classDef phase4 fill:#fce4ec,stroke:#c62828,stroke-width:2px,color:#5c0a0a
    classDef phase5 fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#1a3a1a

The discipline this pipeline enforces is not novel — brainstorm, spec, plan, implement, review is how careful engineering has always worked. What’s different is that a tool enforces the steps. When you’re twelve sessions into a migration and tempted to just start coding the next phase, the skill doesn’t let you. It asks its questions first.

Beads: Local-First Task Tracking

Beads is a local-first issue tracker that lives alongside the repo as flat files. No server, no web UI, no syncing. Tasks are created and queried from the command line: bd create, bd ready, bd update <id> --status closed.

The features that mattered:

Dependencies. Every Beads task can declare dependencies on other tasks. bd ready shows only tasks whose dependencies are all closed — the next unblocked work. This turned the dependency graph in The Shape of the Work from a diagram into an operational tool. After closing a phase, bd ready surfaced whatever was next — the next planned phase or a detour that had just become unblocked.

Instant triage. When a detour surfaced mid-session — the constructor bug in Phase 3, the builtin side-effect problem after Phase 7 — it got filed as a new Beads task in two seconds: bd create "BuiltinResult: builtins bypass apply_update" --dep red-dragon-xyz. The dependency was set, and the task appeared in bd ready at the right time. Without this, mid-session discoveries would have been either fixed immediately (derailing the current work) or forgotten.

Mid-session pivots. The clearest example: midway through brainstorming the heap fields migration (red-dragon-f6i), I realized handlers needed to be migrated first. I interrupted, ran bd update red-dragon-f6i --status deferred, created the handler migration task, and pivoted. When the handler migration was done and closed, bd ready surfaced the deferred heap fields task automatically. The tracker absorbed the pivot without losing the deferred work.

Session boundaries. Each Beads task has an ID (like red-dragon-gsl) that appears in commit messages and in the brainstorming/planning conversations. When a new Claude Code session starts, the first thing I do is bd ready — the task list is the handoff between sessions. The AI doesn’t need to remember what happened last session; the tracker tells it what’s next.

Over a dozen sessions and five detours, the pattern was: close a task → bd ready → claim the next one → brainstorm → plan → implement → commit → close. The tracker turned “I should also fix this other thing I just noticed” from a context-switching hazard into a two-second operation.

Code Simplifier: Automated Cleanup After Every Change

Code Simplifier is a Claude Code plugin that runs as a dedicated review agent after implementation work completes. It focuses on code that was just modified — not the entire codebase — and refines it for clarity, consistency, and maintainability without changing behaviour.

In a migration like this, where sub-agents are churning out handler-by-handler changes across dozens of files, the code that lands is functional but not always clean. A sub-agent focused on migrating _handle_store_field to produce TypedValue will get the types right but might leave behind redundant intermediate variables, unnecessarily verbose conditionals, or naming inconsistencies with the surrounding code. Code Simplifier catches this.

What it does:

• Reduces unnecessary complexity. Nested ternaries become if/else chains. Three-line variable assignments that exist only to be passed once get inlined. Guard clauses replace deep nesting.
• Eliminates redundant code. During the transition phases, handlers accumulated isinstance checks, temporary unwrap/rewrap sequences, and defensive guards that were necessary mid-migration but dead after the phase completed. Code Simplifier flagged many of these before Phase 7’s explicit cleanup pass.
• Enforces consistency. When 15 handler groups are migrated one at a time across multiple sessions, naming conventions drift. One handler might call the coerced value lhs_coerced, another coerced_lhs, another left. Code Simplifier normalises these.

The key constraint: it only touches recently modified code. It won’t “improve” stable code you didn’t ask about. This prevents the scope creep that happens when cleanup tools audit everything — you end up with a 200-file diff when you wanted a 3-file fix.

In practice, I invoked it after each major phase commit. The simplifier would produce a small follow-up diff — typically 10–30 lines changed — that tightened the code the sub-agents had just written. These were fast reviews because the behavioural correctness was already established by the tests; the simplifier was only adjusting form, not function.

Phase 1: TypedValue and BinopCoercionStrategy

The first design session used the brainstorming skill to work through the problem space. The skill’s process is structured: it asks one clarifying question at a time, proposes approaches with trade-offs, and won’t let you skip to implementation until a design is approved. In this case, the dialogue went through eight questions before code was discussed.

The skill started with motivation: “What’s the primary goal — language-correct operators, eliminating the side-car type system, or both?” I said both. Then it asked whether TypedValue should wrap everything (even values with unknown types) or only values with known types. It recommended wrapping everything — even with UNKNOWN — to eliminate all “is this typed or raw?” branching. I agreed, and this turned out to be the single most important design decision of the entire migration.

The next questions drilled into specifics. Should TypedValue subsume SymbolicValue and Pointer, or wrap them? The skill proposed wrapping — keeping SymbolicValue as a value inside TypedValue rather than replacing it — which preserved the existing constraint-tracking machinery without duplication. Then: how should BINOP consume types? The skill proposed two approaches: (A) unwrap, operate on raw values, rewrap with inferred type, or (B) full type-driven dispatch where operators receive TypedValue throughout. It recommended A as the simpler path. I agreed, but added a requirement: “BINOP should have access to a pluggable language-specific TypeConversionStrategy.” That addition — mine, not the skill’s — became BinopCoercionStrategy.

The skill then proposed three migration approaches:

1. Big Bang — change everything at once. Rejected as too risky.
2. Incremental with accessor protocol — wrap at apply_update, migrate handlers one by one. Recommended and chosen.
3. Transparent wrapper with magic methods — TypedValue.__add__ delegates to the underlying value. The skill flagged this as violating the simplest-mechanism principle: isinstance(val, int) checks throughout the codebase would silently fail.

The last question was about scope: “Where should language information live — on the value or on the strategy?” The skill recommended the strategy: “A Java Int and a C# Int are the same value with the same type; the difference is in the coercion rules applied to them.” I agreed.

That session produced two things: TypedValue and BinopCoercionStrategy.

TypedValue is a frozen dataclass:

@dataclass(frozen=True)
class TypedValue:
    value: Any       # The raw Python value
    type: TypeExpr   # The inferred or declared type

BinopCoercionStrategy is a protocol with two methods:

class BinopCoercionStrategy(Protocol):
    def coerce(self, op: str, lhs: TypedValue, rhs: TypedValue) -> tuple[TypedValue, TypedValue]:
        ...
    def result_type(self, op: str, lhs: TypedValue, rhs: TypedValue) -> TypeExpr:
        ...

coerce() transforms operands before the operator runs. result_type() infers the output type. The executor calls both, wraps the result in TypedValue, and stores it.

Here’s the full round trip of a binary operation like "int:" + 42 in Java:

flowchart TD
    subgraph read ["① Read"]
        R1("%r1 → TypedValue('int:', String)"):::reg --> RESOLVE1("_resolve_binop_operand"):::fn
        R2("%r2 → TypedValue(42, Int)"):::reg --> RESOLVE2("_resolve_binop_operand"):::fn
    end

    subgraph coerce ["② Coerce"]
        RESOLVE1 --> LHS("lhs: TypedValue('int:', String)"):::tv
        RESOLVE2 --> RHS("rhs: TypedValue(42, Int)"):::tv
        LHS --> COERCE("⚖️ BinopCoercionStrategy.coerce('+', lhs, rhs)<br/><i>JavaBinopCoercion: stringify rhs</i>"):::strategy
        RHS --> COERCE
        COERCE --> COERCED_L("TypedValue('int:', String)"):::tv
        COERCE --> COERCED_R("TypedValue('42', String)"):::tvchanged
    end

    subgraph compute ["③ Compute"]
        COERCED_L -- ".value" --> EVAL("Operators.eval_binop('+', 'int:', '42')"):::fn
        COERCED_R -- ".value" --> EVAL
        EVAL --> RESULT("result = 'int:42'"):::raw
    end

    subgraph typeinfer ["④ Type + Wrap"]
        LHS --> RTYPE("BinopCoercionStrategy.result_type()"):::strategy
        RHS --> RTYPE
        RTYPE --> TYPE("String"):::type
        RESULT --> WRAP("typed('int:42', String)"):::fn
        TYPE --> WRAP
    end

    subgraph store ["⑤ Store"]
        WRAP --> STORE("%r3 → TypedValue('int:42', String)"):::reg
        STORE --> APPLY("apply_update()"):::fn
    end

    classDef reg fill:#e8f4fd,stroke:#4a90d9,stroke-width:2px,color:#1a3a5c
    classDef fn fill:#f5f5f5,stroke:#616161,stroke-width:1px,color:#212121
    classDef tv fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#1a3a1a
    classDef tvchanged fill:#fff9c4,stroke:#f9a825,stroke-width:2px,color:#5c3a0a
    classDef strategy fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#3a0a3a
    classDef raw fill:#fff3e0,stroke:#e8a735,stroke-width:1px,color:#5c3a0a
    classDef type fill:#fce4ec,stroke:#c62828,stroke-width:1px,color:#5c0a0a

DefaultBinopCoercion is a no-op — it passes operands through unchanged and infers types from operator categories (comparisons return Bool, arithmetic follows numeric promotion rules). JavaBinopCoercion overrides coerce() to auto-stringify non-string operands when + is used with a String.

The Design Decision That Shaped Everything

The critical decision was: “language on strategy, not value.” A Java Int and a C# Int are the same TypedValue. The difference is in the injected coercion strategy. This meant we didn’t need a JavaInt vs. CSharpInt distinction. The coercion strategy is selected once at the top of the execution pipeline based on the source language, then threaded through via dependency injection.

The other critical decision: every value is TypedValue, even when the type is UNKNOWN. This eliminated all branching on “is this typed or raw?” throughout the codebase. It sounded like over-wrapping at first. It turned out to be the decision that kept the migration tractable.

The Boundary Table

The spec documented five boundary crossings where values moved between storage locations and what wrapping/unwrapping happened at each. This table became the roadmap for every subsequent phase. Each phase was essentially: pick a boundary, push TypedValue one layer deeper, update the read sites, run the tests.

flowchart LR
    subgraph Frame ["Stack Frame"]
        direction TB
        REG("📦 Registers<br/><code>%r1 → TypedValue</code>"):::reg
        VAR("📌 Local Vars<br/><code>x → TypedValue</code>"):::var
    end

    subgraph Heap ["Heap"]
        OBJ("🗄️ HeapObject.fields<br/><code>name → TypedValue</code>"):::heap
    end

    subgraph Closure ["Closure Environment"]
        BIND("🔗 Bindings<br/><code>captured_x → TypedValue</code>"):::closure
    end

    REG -- "STORE_FIELD" --> OBJ
    OBJ -- "LOAD_FIELD" --> REG
    VAR -- "capture" --> BIND
    BIND -- "function entry" --> VAR
    REG -- "CALL_FUNCTION" --> VAR
    VAR -- "STORE_VAR" --> VAR
    REG -- "LOAD_VAR" --> REG

    classDef reg fill:#e8f4fd,stroke:#4a90d9,stroke-width:2px,color:#1a3a5c
    classDef var fill:#fff3e0,stroke:#e8a735,stroke-width:2px,color:#5c3a0a
    classDef heap fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#1a3a1a
    classDef closure fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#3a0a3a

Each arrow is a boundary crossing. Before the migration, values were unwrapped to raw primitives and re-wrapped at each crossing. After: TypedValue flows through intact.

After this phase: ~11,274 tests passing.

Phase 2: Handler Migration

Phase 1 wrapped values in TypedValue at the apply_update boundary — the function that takes a StateUpdate and applies it to the VM state. Every handler still produced raw values. apply_update wrapped them.

This worked but created a pointless roundtrip. Handlers called _serialize_value() to flatten objects into JSON-compatible structures, then apply_update called _deserialize_value() to reconstruct them. For locally-executed instructions (the vast majority), this was a no-op. The serialization path only existed for the LLM fallback, where an LLM returns a JSON StateUpdate that needs deserialization.

This phase had an interesting origin. I was partway through brainstorming the heap fields migration (Phase 5) when I realized that handlers were still producing raw values — the heap fields work would be building on a half-migrated foundation. I interrupted: “I think then we pause this plan for now, and do red-dragon-132, so that values always arrive as TypedValue.” The heap fields task was deferred in Beads (bd update red-dragon-f6i --status deferred), and the handler migration jumped the queue. This is one of those moments where the issue tracker earned its keep — deferring a task mid-brainstorm without losing it.

The Serialize/Deserialize Roundtrip

The brainstorming for the apply_update split was another case where I had to push back on the AI’s first instinct. The AI proposed a dual-path apply_update with isinstance branching — check if the incoming value is TypedValue and take one path, otherwise take the raw path. I said: “I think apply_update should be split into apply_update (which accepts only TypedValue) and apply_update_raw (the path which LLMs take).” Then, on reflection: “On second thoughts, what should probably happen is that in the else clause (the LLM path), the raw update should be transformed into a TypedValue update… that way, the updates from both clauses are the canonical TypedValue update.” The AI adopted this — a materialize_raw_update function that converts LLM responses into TypedValue updates before they enter the standard pipeline.

The fix split apply_update into two paths:

• Local path: Handlers produce TypedValue directly. apply_update stores them with lightweight type coercion.
• LLM path: A new materialize_raw_update function takes raw values from LLM JSON responses, deserializes them, coerces them, and wraps them in TypedValue.

Before: serialize → deserialize roundtrip

flowchart LR
    H1("Handler"):::fn -- "_serialize_value()" --> SU1("StateUpdate<br/><i>raw/JSON</i>"):::raw
    SU1 -- "_deserialize_value()" --> AU1("apply_update()"):::fn
    AU1 -- "wrap" --> VM1("VM State"):::state

    classDef fn fill:#f5f5f5,stroke:#616161,stroke-width:1px,color:#212121
    classDef raw fill:#fce4ec,stroke:#c62828,stroke-width:1px,color:#5c0a0a
    classDef state fill:#e8f4fd,stroke:#4a90d9,stroke-width:2px,color:#1a3a5c

After: dual path — local handlers and LLM backends converge on the same apply_update()

flowchart TD
    H2("🖥️ Local Handler"):::local -- "produces TypedValue" --> SU2("StateUpdate<br/><i>TypedValue</i>"):::tv
    LLM("🌐 LLM Backend"):::llm -- "JSON response" --> RAW("Raw StateUpdate"):::raw
    RAW -- "materialize_raw_update()" --> SU2
    SU2 -- "coerce_local_update()" --> AU2("apply_update()"):::fn
    AU2 --> VM2("VM State"):::state

    classDef fn fill:#f5f5f5,stroke:#616161,stroke-width:1px,color:#212121
    classDef raw fill:#fce4ec,stroke:#c62828,stroke-width:1px,color:#5c0a0a
    classDef tv fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#1a3a1a
    classDef state fill:#e8f4fd,stroke:#4a90d9,stroke-width:2px,color:#1a3a5c
    classDef local fill:#e8f5e9,stroke:#2e7d32,stroke-width:1px,color:#1a3a1a
    classDef llm fill:#fff3e0,stroke:#e8a735,stroke-width:1px,color:#5c3a0a

The local path — the common case — is a direct pipeline with no serialization overhead. The LLM path gets its own materialization function that handles the JSON-to-TypedValue conversion before merging into the same StateUpdate.

The migration touched every handler in the executor — about 15 handler groups — done one at a time in dependency order: simple value handlers first (_handle_const, _handle_store_var), then loads (_handle_load_var, _handle_load_field), then objects, then operators, then the call chain. Each group was a separate commit.

The spec documented six different serialization patterns across handlers (raw value, _serialize_value(val), sym.to_dict(), SymbolicValue object directly, Pointer object directly, heap address string). Each had its own migration path.

After this phase: ~11,449 tests passing.

Phase 3: Return Values

_handle_return was still serializing return values via _serialize_value(val), and _handle_return_flow was deserializing them back. This was the same roundtrip as Phase 2, just for return values.

The migration exposed a conflation that had been hiding in the return value semantics.

The Constructor Bug

This was the most frustrating part of the migration, and the brainstorming conversation around it was contentious.

Before TypedValue, return_value = None meant two different things: “this instruction doesn’t have a return value” and “the function returned None/null.” These were indistinguishable. For most code this didn’t matter. For constructors, it did.

Constructors in RedDragon work by allocating a heap object, running the constructor body (which stores fields via STORE_FIELD), and returning self. The return mechanism had a guard: if return_value is not None. This guard prevented constructors from accidentally clobbering their result register with None — constructors return the this pointer via a different mechanism (STORE_VAR into the caller’s local), not via return_value.

When return_value became a TypedValue, the guard broke. TypedValue(None, Void) is not None — the isinstance check passes, and the constructor’s result register gets overwritten with a void value.

The brainstorming for the fix started with me pushing on the void/None distinction. The AI’s initial proposal had a value is not None guard on the return path — essentially preserving the old ambiguity under a new name. I pushed back: “Why is there a None check though?” This forced an explicit discussion of void vs null semantics. Then: “I’m not comfortable with passing a naked None back.” And finally: “I want the ‘no return value is possible because it is void’ scenario to also be represented by a different TypedValue.” This led to adding VOID to the type system.

But the real frustration came after implementation. The implementer agent had used value is not None as a guard anyway — silently discarding both Void and None TypedValues. I caught this in review: “So you completely discarded creating Void and None TypedValues?” followed by “Produce a plan which accommodates the proper behaviour of using TypedValue, and not your coding convenience.” The fix was redesigned from scratch.

The eventual fix came in two commits:

1. Constructor detection via scope chain inspection — if the current frame is a constructor, skip return value writes to the result register.
2. Replace the result_reg=None hack (constructors had been setting their result register to None to prevent writes) with a clean is_ctor flag on StackFrame.

The is_ctor idea came from me during the brainstorming: “Tentative idea: _try_class_constructor_call pushes is_ctor onto the constructor frame… the _handle_return_flow guard only assigns the return value if it is not Void.” The AI refined this into the implementation pattern.

This was a classic refactoring discovery: the old code worked, but only because of an accidental coupling between “None means no value” and “constructors shouldn’t write return values.” TypedValue made the coupling visible by removing the ambiguity. But it was also a case where the brainstorming process — the back-and-forth about what void means, the insistence on not taking shortcuts — produced a cleaner design than either party would have reached alone.

The fix introduced a three-state return type:

• typed(None, scalar("Void")) — void return (no value to write)
• typed(None, UNKNOWN) — explicit return None
• typed(42, scalar("Int")) — concrete return value

flowchart TD
    RET("_handle_return()"):::fn

    RET --> CTOR{"🏗️ Constructor?<br/><i>frame.is_ctor</i>"}:::decide
    CTOR -- "yes" --> VOID("TypedValue(None, Void)"):::void
    CTOR -- "no, has operand" --> RESOLVE("_resolve_reg(operand)"):::fn
    CTOR -- "no, no operand" --> VOID

    RESOLVE --> TV("typed_from_runtime(val)"):::fn
    TV --> SU("StateUpdate<br/><i>return_value + call_pop</i>"):::state
    VOID --> SU

    SU --> POP("⬆️ Pop frame"):::fn
    POP --> FLOW{"_handle_return_flow()"}:::decide
    FLOW -- "Void" --> SKIP("🚫 Skip result_reg write"):::void
    FLOW -- "concrete" --> WRITE("✅ caller.registers[result_reg]<br/>= TypedValue"):::tv

    classDef fn fill:#f5f5f5,stroke:#616161,stroke-width:1px,color:#212121
    classDef decide fill:#fff3e0,stroke:#e8a735,stroke-width:2px,color:#5c3a0a
    classDef void fill:#fce4ec,stroke:#c62828,stroke-width:1px,color:#5c0a0a
    classDef state fill:#e8f4fd,stroke:#4a90d9,stroke-width:2px,color:#1a3a5c
    classDef tv fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#1a3a1a

After this phase: ~11,449 tests, plus the constructor fix.

Phases 4–6: Heap and Closures

Three more storage locations to migrate: HeapWrite.value (Phase 4), HeapObject.fields (Phase 5), and ClosureEnvironment.bindings (Phase 6).

Phase 4 was modest: HeapWrite.value carries TypedValue, but apply_update unwraps it before storing in HeapObject.fields. The heap stays raw for now.

Phase 5 pushed TypedValue into the heap itself. HeapObject.fields stores TypedValue directly. This was the largest single phase because every read site — _handle_load_field, _handle_load_index, constructor field access, builtin method dispatch — had to stop re-wrapping values that were already wrapped.

Phase 6 was the simplest: three write sites and one read site for closure bindings.

The Double-Wrapping Landmine

Phase 5 was where I spent the most time reading code and trying to understand the flow. The heap is read from many places — field access, index access, constructor field initialization, alias variable resolution — and each site had its own slightly different wrapping logic. I kept asking “what does this value look like when it arrives here?” and tracing through the call chain to find out. The codebase had grown large enough that I couldn’t hold the full picture in my head, and the AI’s summaries sometimes glossed over details that mattered.

The persistent source of bugs was that typed_from_runtime() is not idempotent. If you pass it a TypedValue, it wraps it inside another TypedValue:

typed_from_runtime(TypedValue(42, Int))
→ TypedValue(value=TypedValue(42, Int), type=UNKNOWN)

Every read site that previously called typed_from_runtime(raw_value) unconditionally had to get an isinstance guard to prevent double-wrapping. The plan warned about intermediate breakage: tasks 1–4 changed write sites to store TypedValue, but read sites still called typed_from_runtime() unconditionally until tasks 5–7. The test suite was broken between those groups. This was acceptable because both groups were committed atomically.

flowchart TD
    subgraph write ["Write Site (Phase 4–5)"]
        HANDLER("Handler"):::fn -- "typed_from_runtime(val)" --> TV1("TypedValue(42, Int)"):::tv
        TV1 -- "HeapWrite" --> HEAP("🗄️ heap.fields['x']<br/>= TypedValue(42, Int)"):::heap
    end

    HEAP --> SPLIT{"Read site calls<br/>typed_from_runtime()?"}:::decide

    subgraph bad ["❌ Before fix: double-wrapped"]
        SPLIT -- "yes" --> DOUBLE("TypedValue(<br/>  value = TypedValue(42, Int),<br/>  type = UNKNOWN<br/>)"):::danger
    end

    subgraph good ["✅ After fix: pass-through"]
        SPLIT -- "no" --> PASS("TypedValue(42, Int)<br/><i>intact</i>"):::tv
    end

    classDef fn fill:#f5f5f5,stroke:#616161,stroke-width:1px,color:#212121
    classDef tv fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#1a3a1a
    classDef heap fill:#e8f4fd,stroke:#4a90d9,stroke-width:2px,color:#1a3a5c
    classDef decide fill:#fff3e0,stroke:#e8a735,stroke-width:2px,color:#5c3a0a
    classDef danger fill:#ffcdd2,stroke:#c62828,stroke-width:3px,color:#b71c1c

After Phase 6: ~11,481 tests passing.

Phase 7: Cleaning Up After Ourselves

All storage locations now stored TypedValue. The isinstance guards added during the transition — if isinstance(val, TypedValue) — were dead code. Phase 7 removed them all and narrowed type annotations. This was a cleanup commit, not a behavioral change.

Detour: Builtins

The TypedValue migration was “done” after Phase 7. But the work exposed two more problems in the builtin system.

BuiltinResult: Side Effects Should Be Declarative

This detour started with me asking “what else?” after the main migration was done. The AI ran an audit and flagged the builtins. The fix went through another round of brainstorming — a shorter one this time, since the pattern was established. The brainstorming skill proposed three approaches: (A) builtins return ExecutionResult directly, (B) a lightweight BuiltinResult dataclass with value + side effects, or (C) split builtins into two tables (pure vs heap-mutating). I chose B.

But the interesting moment was a correction I made to the AI’s initial proposal. It had suggested that only the heap-mutating builtins return BuiltinResult, while pure builtins continue returning raw values. I pushed back: “Pure builtins should also return BuiltinResult.” The point was uniform interface — the caller shouldn’t need isinstance branching to figure out what a builtin returned. This was the same principle that drove the “every value is TypedValue, even when the type is UNKNOWN” decision in Phase 1. A Beads task was filed (red-dragon-vva), and the plan was generated from the spec.

RedDragon has about 40 built-in functions (len, range, print, slice, plus 25 COBOL-specific byte manipulation builtins). Most are pure — they take arguments and return a value. Two are not: _builtin_array_of creates a heap object, and _builtin_object_rest copies fields from an existing heap object. These two wrote directly to vm.heap as a side effect, bypassing the apply_update pipeline.

This had always been the case, but it became conspicuous once every other state change flowed through StateUpdate. I hadn’t been thinking about builtins at all during the TypedValue planning — they seemed orthogonal. They weren’t. The fix introduced BuiltinResult:

@dataclass(frozen=True)
class BuiltinResult:
    value: TypedValue
    new_objects: list[NewObject] = field(default_factory=list)
    heap_writes: list[HeapWrite] = field(default_factory=list)

All builtins return BuiltinResult. The executor unpacks it into the StateUpdate. No builtin directly mutates vm.heap.

Before: builtins bypass StateUpdate

flowchart LR
    B1("_builtin_array_of()"):::fn -- "⚡ direct write" --> HEAP1("vm.heap"):::danger
    B1 -- "raw value" --> H1("Handler"):::fn
    H1 -- "StateUpdate<br/><i>value only</i>" --> AU1("apply_update()"):::fn
    AU1 --> VM1("VM State"):::state

    classDef fn fill:#f5f5f5,stroke:#616161,stroke-width:1px,color:#212121
    classDef danger fill:#ffcdd2,stroke:#c62828,stroke-width:3px,color:#b71c1c
    classDef state fill:#e8f4fd,stroke:#4a90d9,stroke-width:2px,color:#1a3a5c

After: all effects are declarative

flowchart LR
    B2("_builtin_array_of()"):::fn --> BR("📋 BuiltinResult<br/><i>value + new_objects<br/>+ heap_writes</i>"):::builtin
    BR --> H2("Handler unpacks"):::fn
    H2 --> AU2("apply_update()"):::fn
    AU2 --> VM2("VM State<br/><i>atomic update</i>"):::state

    classDef fn fill:#f5f5f5,stroke:#616161,stroke-width:1px,color:#212121
    classDef state fill:#e8f4fd,stroke:#4a90d9,stroke-width:2px,color:#1a3a5c
    classDef builtin fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#1a3a1a

The migration was done in eight commits, with an isinstance bridge during the transition so that old-style builtins (returning raw values) and new-style builtins (returning BuiltinResult) could coexist. The bridge was removed in the last commit.

Builtin Args: The Atomic Commit Problem

After builtins returned TypedValue via BuiltinResult, they still received raw Python primitives. _resolve_reg stripped the TypedValue wrapper before passing arguments. This was a hole: type information was available at the call site but discarded before the builtin could see it.

The fix was conceptually simple: change all builtins from list[Any] to list[TypedValue] arguments. The implementation was not, because every builtin and every call site had to change simultaneously. Changing the executor to pass TypedValue args without changing the builtins (which do things like args[0] + args[1]) would break all 11,530+ tests.

The plan explicitly mandated: no intermediate commits. All production code changes happen without committing; the single commit occurs after the full test suite passes. This was the only phase where the atomic commit constraint was hard — in every other phase, at least some intermediate states were testable.

This phase touched all 40+ builtins, all method builtins, all 25 COBOL builtins, and the parameter binding code in user function and constructor calls.

After builtins: ~11,530 tests passing.

More Detours

The main migration was done. But work kept surfacing.

BinopCoercionStrategy Return Type

This one came from me staring at the code and asking: “Why does BinopCoercionStrategy.coerce() return tuple[Any, Any]?”

We’d just spent two days making every value in the system a TypedValue. The protocol that coerces binary operands — the thing that started this entire migration — was still stripping types at its return boundary. The AI had implemented it that way in Phase 1, before the rest of the migration made TypedValue universal. Nobody caught it because the callers immediately re-wrapped the values. But it meant type information was being discarded and re-inferred at the coercion boundary, which defeated the purpose.

It was a one-commit fix, but I insisted it be filed as its own Beads task and done separately — changing the protocol return type is a distinct concern from the builtin migration, and mixing them would have muddied the commit history. Beads made this easy: file a task, give it a dependency on the current work, and it shows up in bd ready at the right time.

UnopCoercionStrategy

Phase 1 introduced BinopCoercionStrategy for binary operators. Unary operators (-x, not x, ~x, #x) had no equivalent — _handle_unop still used _resolve_reg (raw values) and typed_from_runtime (runtime type inference). The fix followed the same pattern: a UnopCoercionStrategy protocol with coerce() and result_type(), a DefaultUnopCoercion implementation, and threading through the executor pipeline via kwargs.

Demo Scripts and LLM Path Leaks

After the main migration, the AI reported “all tests pass” and I asked: “Do any of the script files need to be updated?” They did. Five demo scripts in the scripts/ directory used _format_val to display VM state. None of them handled TypedValue. After the heap fields migration, the scripts showed output like fields={'x': TypedValue(value=42, type=ScalarType(name='Int'))} instead of fields={'x': 42}.

The AI’s first fix added an _unwrap() helper with isinstance guards. I pushed back: “Why can’t _unwrap() unconditionally take a TypedValue and unwrap it instead of all the isinstance nonsense?” The local variables always store TypedValue now — that was the whole point. The guard was leftover thinking from the transition period. The fix was to just use .value directly.

Then I asked the AI to actually run each of the scripts. Not just run tests — the scripts aren’t tests, they’re demos that call live LLM backends. The AI had been saying “all tests pass” as if that covered everything. It didn’t. Running the scripts exposed formatting bugs that the test suite couldn’t catch.

This prompted creating an external test infrastructure: a pytest marker @pytest.mark.external and a configuration that excludes external tests by default in both local runs and CI. The scripts now have real tests, they just don’t run in the normal suite.

A separate leak was found in LLMPlausibleResolver._parse_llm_response, which parsed LLM JSON responses into StateUpdate values. The parser produced bare values — not TypedValue — which entered the now-TypedValue-only pipeline. I’d asked “Are there still any bare values passed around anywhere else in the system?” and the audit found three sites in the LLM resolver. The main migration had been so focused on the local execution path that the LLM fallback path was missed.

The Question That Came After

After the migration was done, the documentation updated, and the detours resolved, I looked at the codebase and asked: “We’re now storing types alongside every value in TypedValue. Are the separate register_types and var_types dictionaries in TypeEnvironment still required?”

The answer turned out to be yes — but for a narrower reason than before. TypedValue.type carries the runtime-inferred type (what the computation produced). TypeEnvironment carries the declared type (what the source code said). These can differ: Python’s 4 / 2 produces 2.0 (a float), but if the variable was declared int d, the declared type is Int. Write-time coercion exists to reconcile the two.

But the overlap is real. If the pre-operation coercion strategies were made aware of declared types, they could produce the correct type directly, and write-time coercion would become a no-op for locally-executed instructions. It would only remain necessary for LLM-produced updates. I filed this as a future investigation task. The two-layer architecture works, but it’s worth asking whether both layers are still earning their keep now that TypedValue has changed the landscape.

This is the kind of question that only becomes askable after a migration is done. Before TypedValue, the question was meaningless — types and values lived in different structures by necessity. After TypedValue, the redundancy is visible.

The Shape of the Work

Here’s what the migration looked like as a dependency graph:

flowchart TD
    P1("Phase 1<br/>TypedValue + BinopCoercion"):::main
    P2("Phase 2<br/>Handler migration"):::main
    P3("Phase 3<br/>Return values"):::main
    P4("Phase 4<br/>HeapWrite.value"):::main
    P5("Phase 5<br/>HeapObject.fields"):::main
    P6("Phase 6<br/>Closure bindings"):::main
    P7("Phase 7<br/>Guard cleanup"):::main

    B1("Detour<br/>BuiltinResult"):::detour
    B2("Detour<br/>Builtin TypedValue args"):::detour
    D1("Detour<br/>BinopCoercion return type"):::detour
    D2("Detour<br/>UnopCoercionStrategy"):::detour
    D3("Detour<br/>Demo scripts"):::detour
    D4("Detour<br/>LLM path leak"):::detour
    D5("Detour<br/>External tests"):::detour

    DOC("📄 Doc<br/>Type system update"):::doc

    P1 --> P2 --> P3 --> P4 --> P5 --> P6 --> P7
    P5 --> B1 --> B2
    P1 --> D1 --> D2
    P5 --> D3 --> D5
    B2 --> D4
    P7 --> DOC
    D2 --> DOC

    classDef main fill:#e8f4fd,stroke:#4a90d9,stroke-width:2px,color:#1a3a5c
    classDef detour fill:#fff3e0,stroke:#e8a735,stroke-width:2px,color:#5c3a0a
    classDef doc fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#1a3a1a

    linkStyle 0,1,2,3,4,5 stroke:#4a90d9,stroke-width:3px
    linkStyle 6,7,8,9,10,11 stroke:#e8a735,stroke-width:2px,stroke-dasharray:5

The main sequence (Phases 1–7) was planned. The detours were not. Most of them started with me asking “what next?” or “what else?” after a phase completed — essentially asking the AI to audit the codebase for things I hadn’t thought of. This is a pattern I use a lot: finish a unit of work, commit, then ask the AI to look for fallout. It’s more effective than trying to anticipate everything upfront.

Beads kept this manageable. Each node in the graph above was a Beads task — red-dragon-gsl for the initial TypedValue design, red-dragon-132 for handler migration, red-dragon-vva for BuiltinResult, red-dragon-x9r for builtin args, red-dragon-d5c for the BinopCoercion return type fix, and so on. When a detour surfaced — the constructor bug, the builtin side-effect problem, the PHP enum — it got filed immediately as a new task with its dependencies. Running bd ready after closing a task showed me the next unblocked item, which might be the next planned phase or a detour that had just become unblocked.

There was a concrete example of this working well. Midway through brainstorming the heap fields migration (red-dragon-f6i), I realized handlers needed to be migrated first. I interrupted the brainstorming, ran bd update red-dragon-f6i --status deferred, created the handler migration task, and pivoted. When the handler migration was done and closed, bd ready surfaced the deferred heap fields task automatically. Without the tracker, that kind of mid-session pivot would have meant losing track of the deferred work.

Each major phase also went through the brainstorming skill before implementation began. The early phases (1–3) had longer brainstorming cycles because the patterns weren’t established yet. By the later phases, the brainstorming rounds were shorter — the skill would propose an approach, I’d confirm it matched the established pattern, and we’d move to planning. The skill’s insistence on proposing alternatives before committing to a direction caught at least two cases where the obvious approach wasn’t the best one (the serialize/deserialize split in Phase 2, and the BuiltinResult design over direct StateUpdate returns).

Each detour emerged from one of three causes:

1. The migration exposed a pre-existing problem (constructor bug, builtins bypassing apply_update, BinopCoercionStrategy return type).
2. The migration broke something downstream (demo scripts, LLM path leak).
3. The migration created an obvious gap (UnopCoercionStrategy — if binops have injectable coercion, why don’t unops?).

This is, I think, the normal shape of a refactoring. The plan covers the main sequence. The detours are where the actual learning happens.

Some numbers:

Takeaways

A refactoring is a sequence of discoveries, not a sequence of steps. The plan covered the main migration. The constructor bug, the builtin side-effect problem, the double-wrapping landmine, the LLM path leak — none of these were in the original plan. They emerged because changing one thing made something else visible.

“Every value is TypedValue, even when the type is UNKNOWN” was the single most important decision. It eliminated all branching on “is this typed or raw?” and made the migration monotonic — each phase pushed TypedValue one layer deeper without introducing conditional paths. Every phase that added isinstance guards for transition purposes removed them later. The guards were temporary scaffolding, not permanent complexity.

Splitting the local and LLM execution paths was worth the upfront cost. The serialize/deserialize roundtrip existed because one code path served both local execution and LLM fallback. Once we split them, local execution became a direct path (handler produces TypedValue, apply_update stores it) and the LLM path got its own materialize_raw_update function. This separated two concerns that had been coupled since the beginning.

Side effects should be declarative. The BuiltinResult migration wasn’t in the original plan. It became obvious once every other state change flowed through StateUpdate — two builtins were writing directly to vm.heap, and that was suddenly conspicuous. Making heap mutations declarative via BuiltinResult(new_objects=..., heap_writes=...) was the natural conclusion. The refactoring didn’t create this problem; it made it visible.

Non-idempotent wrapping functions are dangerous. typed_from_runtime(TypedValue(...)) produces a double-wrapped value. This was the single most error-prone aspect of the migration. In hindsight, making typed_from_runtime idempotent (detecting and passing through already-wrapped values) would have prevented an entire class of bugs.

Atomic commits are sometimes unavoidable. Most phases allowed incremental commits. The builtin args migration did not — changing the interface without changing all callers simultaneously would break 11,530+ tests. The plan explicitly mandated no intermediate commits. This is a real constraint when doing interface-level changes in a system with high test coverage.

The brainstorm → spec → plan → implement pipeline prevented false starts. Every phase that went through the brainstorming skill produced a spec before any code was written. The spec forced me to articulate what was changing, what the boundary conditions were, and what the migration path looked like. Twice, the brainstorming skill proposed an approach I hadn’t considered that turned out to be simpler (the serialize/deserialize split, the BuiltinResult design). The discipline of writing down the design before implementing it is not new — but having a tool that enforces the step, asks the right questions, and proposes alternatives makes it harder to skip when you’re tempted to just start coding.

A local issue tracker changes how you handle surprises. Detours are the normal shape of a refactoring. The question is whether they derail you or get absorbed into the work. Beads made it trivial to file a new task the moment a detour surfaced, set its dependencies, and continue with the current work. When the current task was done, bd ready surfaced whatever was next — planned phase or newly-filed detour. The tracker turned “I should also fix this other thing I just noticed” from a context-switching hazard into a two-second operation. Over a dozen sessions and five detours, that added up.

The AI didn’t change the nature of the work. It changed the throughput. The design decisions, the boundary table, the phase ordering, the detour triaging — all of that is the same work a human would do. The AI handled the mechanical parts: updating 40+ builtins to accept TypedValue args, threading kwargs through five layers of function signatures, updating test assertions across eight test files. The refactoring took two days. Without the AI, the same refactoring would have taken longer, but the intellectual structure would have been identical. The bottleneck was never typing speed. It was understanding what needed to change and in what order.

The code is at avishek-sen-gupta/red-dragon. The type system documentation, updated after this migration, is at docs/type-system.md.

Table of Contents

• Context
• RedDragon: How the Architecture Emerged
  • The Initial Session (Feb 25–26)
  • The Determinism Pivot
  • Deterministic Frontends for 15 Languages
  • The Implementation Rhythm
• Growing the Test Suite
  • Cross-Language Testing via Rosetta and Exercism
  • The Dispatch Audit Loop
• The Assertion Audit, or, Why Green Tests may not imply a working system
  • Weak Assertion Patterns
  • The Audit Process
  • Bugs Found Behind Weak Assertions
  • Assertion Audit Lessons
• Guardrails: CLAUDE.md
  • Build Rules
  • Testing Rules
  • Programming Rules
  • The Workflow Evolution
• Structured Agent Memory
  • The Continuity Problem
  • Issue Tracking with Beads
  • Gap Analysis as Planning
  • The Type System Evolution
  • Memory Files
  • The Quick Win Trap
• Patterns and Observations
  • The Anonymous Class Story, or, Why the AI Reaches for New Infrastructure
• What I Would Change
• Conclusion

Context

Over February–March 2026, I built RedDragon — a multi-language code analysis engine with a universal IR, deterministic VM, type system, and iterative dataflow analysis — almost entirely through conversations with Claude Code. RedDragon was built in an initial session, then refined across 237+ more, with 73 additional sessions on its precursor project. That’s roughly 400+ human-AI conversation sessions total.

This post documents what I learned about directing an AI to build a system of this scale.

RedDragon: How the Architecture Emerged

The Initial Session (Feb 25–26)

On Feb 25, I opened a fresh session and described what I wanted: a universal symbolic interpreter that parses source in any language, lowers it to a flat IR, builds a CFG, and executes it symbolically, handling missing imports and unknown externals gracefully.

The first thing I asked: “Is there an existing IR/VM that already does this?” There wasn’t a good fit for what I needed — symbolic execution of incomplete programs across 15 languages — so we proceeded.

The git log from that day shows the progression:

3bfbead  Initial implementation of LLM symbolic interpreter
7eb9721  Local function dispatch, builtins, and scope chain
ed4a3c8  Break up interpreter.py into modular package
b459cdc  Make VM fully deterministic: replace all LLM fallbacks
         with symbolic value creation
bd51810  Add LLM-based frontend for multi-language source-to-IR lowering
4b6f815  Add closure support
6bdd973  Add deterministic tree-sitter frontends for 14 languages
         (346 tests, 0 failures)

Seven commits, each one a distinct architectural decision. The ADR log (which I had Claude write retroactively) captures the reasoning behind each.

The Determinism Pivot

The initial design had the LLM deciding state changes at each execution step. After implementing it, I asked: “Given that the IR is always bounded, shouldn’t the IR execution be deterministic?”

This turned out to matter. We replaced all LLM calls in the VM with symbolic value creation. When the VM encountered an unresolved import, it created a SymbolicValue with a descriptive hint instead of asking an LLM. The value propagated through computation deterministically. The entire execution became reproducible.

With the VM deterministic, the LLM’s role narrowed to one thing: translating source code to IR. And even that was constrained — the prompt provided all opcode schemas, concrete patterns, and a worked example. The LLM was acting as a mechanical translator, not a reasoning engine.

This was the decision that shaped everything else. Once execution was deterministic, everything became testable. The entire test suite runs with zero LLM calls.

Deterministic Frontends for 15 Languages

Rather than using the LLM at runtime to lower source to IR, I asked: “How hard is it to write deterministic logic to lower ASTs to IR for 16 languages?”

Not that hard, with tree-sitter and a dispatch table engine. Claude generated tree-sitter-based frontends for 14 languages in a single session. Each frontend extends a BaseFrontend class with two dispatch tables (one for statements, one for expressions) mapping AST node types to handler methods. Common constructs (if/else, while, for, return) are handled in the base class. Language-specific constructs override or extend.

Sub-millisecond. Zero LLM calls. Fully testable. 346 tests on day one.

When the LLM frontend hit context window limits on large files, we added a chunked frontend that decomposes files into per-function chunks via tree-sitter, lowers each independently, then renumbers registers and reassembles.

The Implementation Rhythm

The initial session followed a repeating cycle:

1. Implement a feature (30–60 minutes)
2. Run it on real code and inspect the output
3. Identify the next gap (“any other language features not covered?”)
4. Audit for completeness, then batch-implement all gaps
5. Clean up immediately: refactor, split large files, reorganise tests

I didn’t let technical debt accumulate. When interpreter.py hit 1,200 lines, I said “break up interpreter.py, it’s too big.” When the registry module grew three responsibilities, I split it into three files. When tests were in a flat directory, I separated them into unit/ and integration/.

Filling language-specific gaps across all 15 frontends was systematic: ask Claude to audit every frontend for missing constructs, prioritise by impact, say “implement all the critical and common ones”, push, re-audit. This cycle repeated 4–5 times, each time catching a smaller set of remaining gaps.

Growing the Test Suite

Cross-Language Testing via Rosetta and Exercism

The test count tells the progression:

Initial frontends:    346 tests
After tooling:       ~700 tests
Rosetta suite:     ~1,200 tests
Exercism (final):   7,268 tests
COBOL + audit:      8,569 tests
Type system:       ~9,400 tests
Gap analysis:     10,152 tests

The Rosetta cross-language test suite (15 algorithms across 15 languages) and the Exercism integration suite drove most of this growth. Each exercise exposed new frontend gaps, VM limitations, and edge cases, and each fix was immediately verified across all 15 languages.

All tests run without LLM calls and are deterministic.

The Dispatch Audit Loop

After every batch of frontend work, I ran a two-pass audit:

Pass 1 (Dispatch Comparison): Parse source samples in all 15 languages, collect every AST node type that appears, compare against the frontend’s dispatch tables, and classify unhandled types as structural (harmless, consumed by parent handlers) or substantive (gaps that produce SYMBOLIC).

Pass 2 (Runtime SYMBOLIC check): Lower the source through each frontend, scan the resulting IR for SYMBOLIC instructions with "unsupported:" operands.

The classification heuristic itself went through three iterations:

1. Naive: Flag everything not in a dispatch table. Hundreds of false positives, because nodes like parameter_list are consumed by parent handlers.
2. Parent heuristic: Flag unhandled nodes only if their immediate parent isn’t handled. Reduced false positives but still produced 259.
3. Block-reachability analysis: Walk the AST and identify which unhandled nodes are direct named children of block-iterated nodes. Only these can reach _lower_stmt and produce SYMBOLIC. This dropped substantive gaps from 259 to 1.

The audit loop ran dozens of times:

flowchart LR
    A("🔍 Audit all<br/>frontends"):::audit --> G{"Gaps<br/>found?"}:::decide
    G -- "Yes (34 → 19 → 12 → ...)" --> I("🔧 Batch-implement<br/>all gaps"):::impl
    I --> T("✅ Add tests"):::test
    T --> A
    G -- "No: 0 gaps,<br/>0 SYMBOLIC" --> D("🏁 Done"):::done

    classDef audit fill:#e8f4fd,stroke:#4a90d9,stroke-width:2px,color:#1a3a5c
    classDef decide fill:#fff3e0,stroke:#e8a735,stroke-width:2px,color:#5c3a0a
    classDef impl fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#3a0a3a
    classDef test fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#1a3a1a
    classDef done fill:#e8f5e9,stroke:#2e7d32,stroke-width:3px,color:#1a3a1a

This pattern (audit, batch-fix, re-audit) was more effective than trying to enumerate every missing feature upfront.

The Assertion Audit, or, Why Green Tests may not imply a working system

By March 2026, the test suite had grown to ~8,400 tests across ~130 files. All green. The question I’d been putting off: if every test passes, how do I know each test is actually checking what it says it’s checking?

When an AI writes your tests, you get volume and coverage breadth. What you don’t get is assertion depth. The AI produces a test for every function, every edge case, every language, but each individual assertion may be checking the easy thing (does it not crash?) rather than the hard thing (does it produce the right output?). The AI optimises for the test passing, not for the test verifying.

Weak Assertion Patterns

Over two days and 11 audit passes, I had Claude scan every test file, comparing each test’s name against its actual assertions. The patterns that emerged:

• OR-fallback assertions. Tests like assert Opcode.BRANCH_IF in opcodes or Opcode.BRANCH in opcodes — where BRANCH (unconditional jump) exists in virtually every program, making the assertion tautologically true. 23+ instances across Scala match/case, C# switch expressions, COBOL PERFORM ordering, and IR stats tests.
• Existence-only checks. assert len(writes) >= 1 on WRITE_REGION, satisfied by DATA DIVISION initial-value writes, leaving the PROCEDURE statement under test untested. The strengthened version decoded the EBCDIC bytes and checked specific values.
• Cross-product matching. assert any(bi < pi for bi in branch_if_indices for pi in print_indices) — any() over a cross-product matches if any BRANCH_IF appears before any print, even from unrelated parts of the program.
• Silent parametrised passes. Bare return in parametrised tests for excluded languages — 11 languages were showing as green in the closure test report with zero assertions executed. The fix was pytest.skip() with a reason string.
• Tautological guards. if "x" in result.definitions: where result.definitions was a list of Definition objects, not a dict. The in check always returned False, so the assertion never fired.

The Audit Process

Phase 1: Discrepancy audits. Tests whose names contradicted what the code did. A diamond-shape test that asserted stadium shape; test_constructor_sets_fields that never verified field values.

Phase 2: Name-vs-assertion audits. Does each test assert what its name claims? 52 violations across 22 files.

Phase 3: Priority-based audits. P0 (false confidence), P1 (missing key assertion), P2 (weak/generic), P3 (cosmetic). Re-scans after each fix batch drove the count down: 82 to 56 to 17.

Phase 4: Reconciliation. The violation list kept changing between audits. Items fixed reappeared with different wording. The fix was anchoring: starting from the previous audit’s known remaining items and verifying each against the current code.

The governing principle throughout: strengthen the assertion to match the name, never weaken the name to match the assertion. Renaming moves the problem. Strengthening closes the gap.

Bugs Found Behind Weak Assertions

P0 fixes exposed genuine bugs:

Pascal bare-except. The Pascal frontend silently dropped bare except blocks (without on E: Exception do wrapper). The test passed because it only checked that STORE_VAR "x" existed, satisfied by the try body alone. Strengthening the assertion exposed the bug.

C# else-if chain lowering. A weak assertion masked incomplete lowering of chained else-if blocks.

test_no_self_dependency_without_loop. A guard checking membership on a list of Definition objects always returned False, so the assertion never executed.

Assertion Audit Lessons

The test count went up, not down. Strengthening assertions sometimes meant splitting one weak test into multiple specific ones.

Key lessons:

• Green tests are necessary but not sufficient. 15 P0 violations where the test would pass even when the feature was broken.
• OR-fallback assertions are the most dangerous pattern. One side trivially satisfied by unrelated instructions.
• Audit stability requires anchoring. Fresh scans produce inconsistent results. The reconciliation approach is necessary.
• Fixing assertions requires running the code. Many fix attempts failed because the assertion assumed a representation that didn’t match reality. The cycle (write assertion, run, discover actual representation, fix, re-run) never happened voluntarily.
• Parametrised tests need explicit skips, not silent returns.

Guardrails: CLAUDE.md

The file that had the most impact on consistency wasn’t any Python module. It was CLAUDE.md, the development rules file that Claude Code reads at the start of every session. The rules evolved over the project’s lifetime, each one added in response to a specific failure mode.

Build Rules

• “Before committing anything, run all tests, fixing them if necessary.” This prevented test count regression across 292 commits. If test assertions are being removed, ask for human review first.
• “Before committing anything, run poetry run black on the full codebase.” CI enforces this.
• “Before committing anything, update the README based on the diffs.” Without this, the README would have drifted within the first week.
• “For each feature, treat it as an independent commit / push, with its own testing.” Atomic, reviewable commits. Combined with “do not start a new task until the current one is committed,” this prevented half-finished features from accumulating across sessions.
• “Once a design is finalised, document it as an ADR.” This produced 100+ architectural decision records that serve as the project’s institutional memory.

Testing Rules

• “When fixing tests, do not blindly change test assertions to make the test pass.” Without this, the AI’s default behaviour is to modify the assertion to match whatever the code produces, regardless of whether the code is correct.
• “Make sure you are not creating any special implementation behaviour just to get the tests to pass.” Without this, the AI occasionally added if-branches in production code solely to satisfy a test expectation.
• “Do not use unittest.mock.patch. Use proper dependency injection.” This forced every external dependency to be injectable. The entire VM, all 15 frontends, and all analysis passes are testable in isolation.
• “For every bug you fix, make sure you have a test that fails without the bug fix.”

Programming Rules

• “STOP USING FOR LOOPS WITH MUTATIONS IN THEM.” This forced a functional style: list comprehensions, map, filter, reduce instead of mutable accumulators.
• “Categorically avoid defensive programming.” Defensive code hides bugs. A None check that silently returns an empty list masks the fact that a value should never have been None. Without this rule, the AI adds defensive checks reflexively.
• “If a function has a non-None return type, never return None.” Use null object pattern instead.
• “When writing if conditions, prefer early return.” Without this, the AI nests the happy path inside increasingly deep conditionals.
• “Do not use static methods.” Static methods resist dependency injection and create hidden coupling.
• “Use a ports-and-adapter type architecture. Adhere to ‘Functional Core, Imperative Shell’.” The VM handlers are pure functions returning StateUpdate data objects. The dataflow module is a pure analysis pass. I/O lives at the edges.
• “Parameters in functions, if they must have default values, must have those values as empty structures corresponding to the non-empty types.” Empty dicts, empty lists, never None.

The Workflow Evolution

The workflow encoded in CLAUDE.md changed over time:

Early workflow:

flowchart LR
    B1("🧠 Brainstorm"):::phase1 --> P1("📐 Plan"):::phase2 --> I1("⚙️ Implement"):::phase3 --> T1("🧪 Test"):::phase4

    classDef phase1 fill:#e8f4fd,stroke:#4a90d9,stroke-width:2px,color:#1a3a5c
    classDef phase2 fill:#fff3e0,stroke:#e8a735,stroke-width:2px,color:#5c3a0a
    classDef phase3 fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#3a0a3a
    classDef phase4 fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#1a3a1a

Revised workflow (TDD):

flowchart LR
    B2("🧠 Brainstorm"):::phase1 --> D2("⚖️ Discuss<br/>trade-offs"):::phase1 --> P2("📐 Plan"):::phase2 --> T2("🧪 Write<br/>tests"):::test --> I2("⚙️ Implement"):::phase3 --> F2("🔧 Fix<br/>tests"):::test --> C2("✅ Commit"):::done --> R2("♻️ Refactor"):::done

    classDef phase1 fill:#e8f4fd,stroke:#4a90d9,stroke-width:2px,color:#1a3a5c
    classDef phase2 fill:#fff3e0,stroke:#e8a735,stroke-width:2px,color:#5c3a0a
    classDef phase3 fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#3a0a3a
    classDef test fill:#fce4ec,stroke:#c62828,stroke-width:2px,color:#5c0a0a
    classDef done fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#1a3a1a

Early: Brainstorm -> Plan -> Implement -> Test. Tests came after implementation. This was the root cause of the weak assertion patterns the audit uncovered — when the AI writes tests after the code exists, it tends to assert what the code does rather than what it should do. The test becomes a description of current behaviour, not a specification of correct behaviour.

The assertion audit made this cost concrete. After spending two days fixing ~75 violations — OR-fallbacks, existence-only checks, silent parametrised passes — I changed the workflow to test-first. The AI writes tests that encode expected behaviour before implementation. It then writes code to make them pass. This inverts the incentive: the test defines the target, and the code adapts to meet it, rather than the test adapting to describe whatever the code produced.

The type system work (Phase 3 onward) was built entirely under this TDD workflow. The difference was visible — the type inference tests asserted specific return types for specific expressions, not just “inference produced a result.”

Every rule was reactive. “STOP USING FOR LOOPS WITH MUTATIONS” came after mutation bugs. “Don’t blindly change test assertions” came after watching the AI weaken tests to make them pass. “Categorically avoid defensive programming” came after silent None checks masked real bugs. Each rule represents a mistake that happened at least once.

Structured Agent Memory

The Continuity Problem

By session 200, the project had outgrown ad-hoc session management. At 8,500+ tests, 15 frontends, 66 ADRs, and a type system under active development, I’d open a new conversation and describe what I wanted — but determining what was getting harder. Which frontend gaps remained? Which were P0 vs. P1? What depended on what?

The deeper problem was agent amnesia. Each conversation started from zero. Claude didn’t remember that the TypeExpr migration was complete, that Pascal declLabels was already handled, that poetry run python -m pytest was the correct test command. At 50 sessions, this was a minor annoyance. At 200, it was the main cost.

The solution was a structured memory layer — persistent artefacts that the agent reads at session start. Four components: a curated memory file, a gap analysis document, an issue tracker, and architectural decision records. Together they answer: what’s the current state?, what’s left to do?, what are the rules?, and why were past decisions made?

Issue Tracking with Beads

The inflection point was a frontend lowering gap analysis: cross-referencing every frontend’s dispatch table against its tree-sitter grammar. Result: 25 P0, 187 P1, and ~326 P2 gaps across 15 languages. The P0s were resolved in three commits. But 187 P1 gaps couldn’t be managed as a mental list.

I chose Beads, a local-first issue tracker that stores data in a Dolt database alongside the repo. It supports hierarchical issues (epics -> stories -> tasks), dependency chains, labels, and priority classifications from the command line.

The 187 P1 gaps became a structured breakdown:

red-dragon-gvu [epic]: 129 P1 frontend lowering gaps
├── gvu.1 [epic]: Cross-language pattern matching (25 tasks across 6 languages)
├── gvu.2 [epic]: Class/OOP features (14 tasks)
├── gvu.3 [epic]: Type system and generics (11 tasks)
├── gvu.4 [epic]: Async/coroutine support (8 tasks)
├── gvu.5 [epic]: Destructuring and rest patterns (7 tasks)
├── gvu.6 [epic]: Metaprogramming/macros (9 tasks)
├── gvu.7 [epic]: Module system and imports (8 tasks)
└── gvu.8 [epic]: Language-specific features (remaining)

This changed how sessions started. Instead of describing work from memory, I could say “what’s the next open task under gvu.1?” The issue tracker became the session boundary — work was defined before the session began, not discovered during it.

Beads data is backed up as JSONL files committed to the repository, so issue state travels with the code. On a new machine, bd backup restore rebuilds the full database — 168 issues, 538 events, 163 dependencies.

Gap Analysis as Planning

The gap analysis document (docs/frontend-lowering-gaps.md) became a living planning artefact. Each P1 gap had a row with language, node type, description, and status. As gaps were resolved, status flipped to DONE. As new gaps were discovered, they were added.

Many P1 gaps clustered thematically. Pattern matching was a gap in 6 languages simultaneously. Class/OOP features were missing in 5. The right unit of work wasn’t “fix Go’s missing iota” — it was “implement pattern matching across all 6 languages that need it.” The themed epics emerged from the data, not from upfront planning.

The analysis also forced honest assessment of what “done” meant. I’d have Claude classify some gaps as “no-ops.” When I asked Claude to verify each claimed no-op against the actual tree-sitter AST, most contained meaningful content. TypeScript’s ambient_declaration had full type signatures. C#’s unsafe_statement wrapped executable blocks. Out of 8 claimed no-ops, only 2 were genuine. The lesson: verify against the AST, not against assumptions about what a node type name implies.

The Type System Evolution

The largest post-sprint development was the type system. RedDragon started with string-based type hints — "Int", "String", "List<Int>" — threaded through the IR as operand annotations. This worked for simple inference but couldn’t represent parameterised types, union types, or subtype relationships.

The evolution happened in phases, each driven by a concrete limitation:

Phase 1: TypeExpr ADT. Replaced string type hints with an algebraic data type: ScalarType("Int"), ParameterizedType("List", (ScalarType("Int"),)), UnknownType. A parse_type() function handled roundtripping from legacy strings. String-compatible equality was preserved for backward compatibility during the migration.

Phase 2: TypeGraph. A directed acyclic graph encoding subtype relationships (Int <: Number <: Object, String <: Object). Covariant is_subtype_expr() for parameterised types. common_supertype_expr() for join operations.

Phase 3: Interface-aware inference. When the inference engine encountered animal.speak() where animal was typed as interface Animal, it couldn’t resolve the return type. The fix was a chain walk: check interface method types when the class’s own methods don’t have type information. This required seeding interface_implementations from 5 frontends.

Each phase was documented as an ADR, tested with both unit and integration tests, and committed independently. The type system alone accounts for ~1,500 tests and 34 ADRs.

A later phase of type system work — migrating every runtime value to carry its type via a TypedValue wrapper — became a multi-phase refactoring that exposed hidden assumptions in constructor handling, revealed that builtins were bypassing the state management contract, and prompted half a dozen side detours. I wrote about that migration separately in Anatomy of a Refactoring Using AI.

Memory Files

Claude Code supports a persistent memory directory (.claude/projects/.../memory/MEMORY.md) loaded at session start. My memory file contains:

• Key references: Links to audit results, gap analyses, and their current status
• Workflow reminders: Commands that have been forgotten before
• Project state: Current test count, resolved issues, known gotchas
• Type system state: Which migration phases are complete
• Future work pointers: What’s been deferred and why

The memory file is curated, not appended. Outdated information is removed. Entries are updated when facts change.

The distinction between the memory file and CLAUDE.md: CLAUDE.md encodes rules. The memory file encodes state. Together with the gap analysis (plan) and the issue tracker (work queue), they form a four-layer structured memory:

flowchart TB
    S(("🚀 New session")):::start
    R("📜 CLAUDE.md<br/><i>Rules: how to behave</i>"):::rules
    M("🧠 MEMORY.md<br/><i>State: what's been done</i>"):::state
    G("📊 Gap analysis<br/><i>Plan: what's left to do</i>"):::plan
    B("📋 Beads issues<br/><i>Work queue: what to do next</i>"):::queue
    O("✅ Agent is oriented"):::done

    S --> R & M & G & B
    R & M & G & B --> O

    classDef start fill:#e8f4fd,stroke:#4a90d9,stroke-width:3px,color:#1a3a5c
    classDef rules fill:#fce4ec,stroke:#c62828,stroke-width:2px,color:#5c0a0a
    classDef state fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#3a0a3a
    classDef plan fill:#fff3e0,stroke:#e8a735,stroke-width:2px,color:#5c3a0a
    classDef queue fill:#e8f4fd,stroke:#4a90d9,stroke-width:2px,color:#1a3a5c
    classDef done fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#1a3a1a

A fresh session can orient itself in seconds rather than minutes.

The Quick Win Trap

When managing 168 issues, there is a temptation to chase quick wins — tasks that appear trivial. During the gap analysis breakdown, Claude identified ~16 “quick wins” including 8 claimed no-ops. When I asked Claude to verify each one against the actual AST structure, the list shrank to 7, with only 2 genuine no-ops. The rest needed real handlers.

What looks like a no-op from the node type name often isn’t. ambient_declaration sounds like metadata; it’s actually declare const VERSION: string. unsafe_statement sounds like a compiler pragma; it’s actually a block wrapper around executable code.

The AI will optimise for closing tickets, not for closing them correctly. The human’s job is to challenge the classification before the work begins.

Patterns and Observations

• Brainstorm, probe, crystallise. I didn’t start with fixed architectures. I started with a problem, brainstormed approaches with Claude, then implemented each and tested on real data. The deterministic VM emerged from asking “shouldn’t this be deterministic?” after seeing the LLM-based approach work.

• The plan document as interface. After brainstorming and discussing trade-offs, I’d formulate a plan document covering context, phases, file-by-file changes, and verification steps. The plan is specific enough for unambiguous execution but high-level enough to retain architectural control. This happened ~15 times.

• Brainstorming with Superpowers. Later in the project, I started using the Superpowers plugin for Claude Code, specifically its brainstorming skill. Why it fit my workflow:
  • I’m not used to writing large upfront specs. I prefer to explore the design space before committing to a choice, and Superpowers’ brainstorming mode let me describe a problem and have it explore multiple approaches interactively.
  • Design through small focused decisions. I want the design to evolve through a series of yes/no decisions on individual aspects, not a single monolithic plan. The brainstorming skill converges on a design through exactly this kind of incremental refinement.
  • Customising how information is presented. For larger refactorings, instead of handing me a full implementation spec to review (which I would skim), I asked it to show me the salient aspects of the final design — the key trade-offs, the data structures that would change, the migration strategy — as a list of focused questions I could approve or reject individually. This turned spec review from a passive reading exercise into an active decision-making process.

• Breadth over depth. Tasks like “generate frontends for 14 languages” or “audit all 130 test files for weak assertions” are where the AI works well. These breadth tasks — applying a consistent pattern across many targets — would have taken days. Where it needed more guidance was depth: closure capture semantics (snapshot vs. shared environment), when to use SYMBOLIC fallback vs. crash, whether an assertion is vacuous. These required me to probe with specific test cases.

• Empirical validation over specification. I rarely specified exact behaviour upfront. I implemented a feature, ran it on real code, and judged the results. The AI made this feedback loop fast enough to be practical.

• Terse directives after trust. Early prompts were detailed. By mid-project: “do all of them”, “push”, “commit and push this”. Trust built through consistent execution.

flowchart LR
    E("📝 Sessions 1–20<br/><b>Detailed specs</b><br/><i>full context + constraints</i>"):::early
    M("💬 Sessions 20–100<br/><b>Short directives</b><br/><i>'implement all the<br/>critical and common ones'</i>"):::mid
    L("⚡ Sessions 100+<br/><b>Minimal prompts</b><br/><i>'do all of them'</i><br/><i>'push'</i>"):::late

    E --> M --> L

    classDef early fill:#fce4ec,stroke:#c62828,stroke-width:2px,color:#5c0a0a
    classDef mid fill:#fff3e0,stroke:#e8a735,stroke-width:2px,color:#5c3a0a
    classDef late fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#1a3a1a

• The AI hallucinated audit findings. During the assertion audit, the AI reported violations that didn’t exist or had already been fixed. Different parallel agents flagged different things, inconsistently applied priority criteria, and re-reported fixed items with different wording. The reconciliation pass caught this. The auditor itself needs auditing.

• CLAUDE.md rules are reactive. Every rule was added in response to a specific failure. They accumulate over time, and each one represents a mistake that happened at least once.

• Screenshot-driven debugging. For the CFG visualisation work, I’d generate a diagram, screenshot it, paste it into the conversation, and ask “why does it look so disjointed?” Claude could see the rendering and diagnose layout issues. The visualisation went through five rounds.

The Anonymous Class Story, or, Why the AI Reaches for New Infrastructure

TypeScript allows assigning anonymous classes to variables: const MyClass = class { constructor() { ... } }. When someone writes new MyClass(), the VM needs to resolve MyClass — but MyClass isn’t a declared class name. It’s a variable that holds a class.

The first design Claude proposed: a new class_aliases dictionary in the class registry, populated during lowering, with a resolve_class_name() method that checks aliases before the main registry. New data structure, new resolution method, new lowering logic to populate it.

I asked: “Why is this so complicated?”

Second attempt: a pointer chain mechanism. The variable would store a pointer to the class entry, and _handle_new_object would follow the pointer chain. Still new infrastructure — a new pointer type and a resolution protocol.

I asked: “Why can’t it just be a regular variable living on the stack?”

Third attempt — the one that shipped: at _handle_new_object time, if the class name isn’t in the registry, check if it’s a variable in scope. If so, dereference it and use the result as the class name. The variable store already was the lookup table. Five lines of code. Zero new data structures.

# The entire fix
if class_name not in self.class_registry:
    resolved = self.current_frame.lookup(class_name)
    if isinstance(resolved, str):
        class_name = resolved

The pattern repeated immediately. The next step was seeding the variable’s type as Type[ClassName] — a metatype — so the type inference engine could track it. Claude proposed a string-encoded "Type[ClassName]" representation. But the codebase already had ParameterizedType in its TypeExpr ADT. The metatype was just ParameterizedType("Type", (ScalarType("ClassName"),)). A one-line convenience constructor, no new types.

That metatype work then surfaced a deeper issue: the type extraction pipeline was converting TypeExpr objects to strings, passing strings through seed methods, and then parsing them back to TypeExpr on the other side. The round-trip was pointless. This led to a migration across all 15 frontends — changing seed methods to accept TypeExpr directly, eliminating the string intermediary. The migration touched ~30 files and passed through 11,193 tests without a single failure, because it was removing accidental complexity, not adding new behaviour.

Three iterations to reach a 5-line solution. Each iteration was simpler than the last. The AI’s instinct at each step was to add — a new registry, a new pointer type, a new string encoding. The human’s role was to ask “doesn’t the existing system already do this?” until the answer was yes.

This is the most common design failure mode I’ve observed: the AI builds new infrastructure before checking whether the existing system already solves the problem. It’s not a capability limitation — Claude understood the variable store, the class registry, and the TypeExpr ADT perfectly well. It just didn’t start from them. It started from the problem and worked forward, rather than starting from the existing system and asking what was missing.

The fix isn’t a CLAUDE.md rule (though I added one). It’s a conversational habit: before accepting any design, ask “what existing mechanism does this duplicate?”

What I Would Change

• Start with the audit earlier. The two-pass dispatch audit should have existed from the first batch of frontends, not after 50 sessions.

• Invest in cross-language tests from day one. The Rosetta and Exercism suites exposed more bugs than all the language-specific unit tests combined. A single exercise tested across 15 languages covers more surface area than 50 unit tests in one language.

• Be more aggressive about the functional core. Even with the FP rules in CLAUDE.md, some mutation crept in, especially in the VM executor. The dataflow module is almost purely functional and is the easiest module to test. The correlation is not a coincidence.

Conclusion

Building non-trivial systems with an AI coding assistant is about architectural direction, not prompting. The human’s role is strategic: choosing problems, evaluating approaches empirically, making pivot decisions, and encoding quality standards. The AI’s role is tactical: implementing plans, auditing for completeness, applying patterns at breadth, and maintaining consistency.

The workflow I converged on (brainstorm, discuss trade-offs, plan, test-first, implement, clean up) emerged through trial and error across 400+ sessions.

What changed between the early sessions and the later ones was the emergence of structured agent memory. The early sessions were exploratory, driven by momentum. The later sessions were systematic — the agent started each conversation knowing the project state, the active work queue, and the governing rules. The human’s role expanded from architect to memory curator: defining work, challenging classifications, and maintaining the persistent artefacts that make each session productive from its first message.

The limiting factor in AI-assisted development is not the AI’s capability — it’s the AI’s memory. A capable agent with no memory rediscovers context every session. A capable agent with structured memory picks up where the last session left off.

References

• IR Reference — The 28-opcode instruction set
• Notes on VM Design — Deterministic execution model and symbolic values
• Notes on Frontend Design — Tree-sitter dispatch table architecture
• Notes on Dataflow Design — Iterative dataflow analysis
• Type System — TypeExpr ADT, TypeGraph, and inference
• Frontend Lowering Gaps — Gap analysis across 15 languages
• IR Lowering Gaps — IR-level lowering gaps
• Architectural Decision Records — 100+ ADRs documenting design decisions
• Anatomy of a Refactoring Using AI — The TypedValue migration: a multi-phase refactoring traced in detail

GitHub: avishek-sen-gupta/red-dragon

The Problem

I wanted to analyse source code across many languages (trace data flow, build control flow graphs, understand how variables depend on each other) without writing a separate analyser for each language. The conventional approach is to build language-specific tooling (Roslyn for C#, javac’s AST for Java, etc.), but that means duplicating every downstream analysis pass for every language. I wanted one representation, one analyser, many languages.

Established IRs exist for this kind of work. LLVM IR covers C, C++, Rust, Swift, and others. WebAssembly targets a growing set of languages. GraalVM’s Truffle framework provides a polyglot execution layer. I considered all of these and chose to build my own for three reasons:

• No single existing IR covered the full set of languages I wanted to analyse (Python, Ruby, JavaScript, TypeScript, PHP, Lua, Scala, Kotlin, Go, Java, C#, C, C++, Rust, Pascal, and COBOL).
• Existing IRs assume programs are complete and all dependencies are resolved. They are not designed for incomplete code with missing imports, unresolved externals, or partial extracts.
• I wanted to integrate LLM-based lowering and LLM-assisted execution as first-class features of the pipeline, and grafting that onto an existing IR’s toolchain would have taken more time than building a purpose-built one.

The twist: I wanted to handle incomplete programs gracefully. Real-world code depends on imports, frameworks, and external systems that aren’t available during static analysis. Most tools crash or give up when they hit an unresolved reference. I wanted mine to keep going, creating symbolic placeholders for unknowns and tracing data flow through them.

RedDragon is the result. It parses source in 15 languages, lowers it to a universal intermediate representation, builds control flow graphs, performs iterative dataflow analysis, and executes programs via a deterministic virtual machine. All with zero LLM calls for programs with concrete inputs. RedDragon is a work in progress.

This post covers how the system is designed: the IR, the frontends, the VM, type inference, and the dataflow analysis.

Motivation

RedDragon is the natural extension of my earlier work on Cobol-REKT, a COBOL reverse engineering toolkit. That project taught me the value of building analysis tools for legacy code, and left me wanting to generalise the approach across languages. I’d also built a small VM in Prolog previously, and wanted to attempt a more complete one — with a proper type system, dataflow analysis, and multi-language support.

Beyond the technical goals, this project was also a deliberate exercise in AI-assisted software development. I wanted to actively practise and improve my skills in directing an AI to build non-trivial systems — understanding where it works well, where it doesn’t, and how to structure the collaboration. The companion post covers that side of the experience.

RedDragon is a work in progress, and this post is a snapshot of where it stands today. My understanding of compiler design, type systems, and program analysis continues to evolve alongside the project.

Core Theses

RedDragon explores three ideas about analysing frequently-incomplete code, the kind found in legacy migrations, decompiled binaries, partial extracts, and codebases with missing dependencies:

1. Deterministic language frontends with LLM-assisted repair. Tree-sitter frontends (15 languages) and a ProLeap bridge (COBOL) handle well-formed source deterministically. When tree-sitter hits malformed syntax, an optional LLM repair loop fixes only the broken fragments and re-parses, maximising deterministic coverage for real-world incomplete code. All paths produce the same universal IR.

2. Full LLM frontends for unsupported languages. For languages without a tree-sitter frontend, an LLM lowers source to IR entirely, supporting any language without new parser code. A chunked variant splits large files into per-function chunks via tree-sitter, lowering each independently. The LLM acts as a compiler frontend, constrained by a formal IR schema with concrete patterns. It’s translating syntax, not reasoning about semantics.

3. A VM that integrates LLMs only at the boundaries where information is genuinely missing. When execution hits missing dependencies, unresolved imports, or unknown externals, a configurable resolver can invoke an LLM to produce plausible state changes, keeping execution moving through incomplete programs instead of halting at the first unknown. When source is complete and all dependencies are present, the entire pipeline (parse → lower → execute) is deterministic with zero LLM calls.

Table of Contents

1. Architecture Overview
2. A Worked Example: Source to Execution
3. The IR: 33 Opcodes to Rule Them All
4. Frontends: Four Strategies, One Output
5. LLM-Assisted AST Repair
6. LLM Frontend: Lowering Unknown Languages
7. The Dispatch Table Engine
8. Lowering Equivalence
9. The Deterministic VM
10. LLM-Assisted VM Execution
11. Dataflow Analysis
12. Type Inference
13. Cross-Language Type Inference in Practice
14. Cross-Language Verification via Exercism
15. References

Architecture Overview

RedDragon follows a classic compiler pipeline:

%%{ init: { "flowchart": { "curve": "stepBefore" } } }%%
flowchart TD
    src("📄 Source Code<br/><i>15 languages</i>"):::input
    frontend("🔧 Frontend<br/><i>deterministic or LLM-based</i>"):::transform
    cfg("🔀 CFG Builder"):::analysis
    typeinf("🏷️ Type Inference"):::analysis
    vm("⚙️ VM"):::engine
    dataflow("📊 Dataflow Analysis"):::engine

    src --> frontend
    frontend -->|"list[TypedInstruction]"| cfg
    frontend -->|"list[TypedInstruction]"| typeinf
    typeinf -->|"TypeEnvironment"| vm
    cfg --> vm
    cfg --> dataflow

    classDef input fill:#e8f4fd,stroke:#4a90d9,stroke-width:2px,color:#1a3a5c
    classDef transform fill:#fff3e0,stroke:#e8a735,stroke-width:2px,color:#5c3a0a
    classDef analysis fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#3a0a3a
    classDef engine fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#1a3a1a

Every stage operates on the same flat IR. The type inference pass, VM, and dataflow analysis are all language-agnostic. They don’t know whether the instructions came from Python, Rust, or COBOL.

A Worked Example: Source to Execution

To make the pipeline concrete, here’s a complete trace of a simple program through every stage. This is the same pipeline that runs for all 15 languages.

Source (Python)

def classify(x):
    if x > 0:
        label = "positive"
    else:
        label = "negative"
    return label

result = classify(5)

Stage 1: Lowering to IR

The Python tree-sitter frontend parses this and emits flat three-address code. The function body is wrapped in a skip-over pattern (a BRANCH jumps past it so it’s not executed at definition time):

branch end_classify_0                    # skip over body
func_classify_0:                         # entry point
  %0 = symbolic param:x                  # parameter binding
  decl_var x %0
  %1 = load_var x                        # if x > 0
  %2 = const 0
  %3 = binop > %1 %2
  branch_if %3 if_true_0,if_false_0
if_true_0:
  %4 = const "positive"
  decl_var label %4
  branch if_end_0
if_false_0:
  %5 = const "negative"
  store_var label %5                     # assignment to existing var
  branch if_end_0
if_end_0:
  %6 = load_var label
  return %6
end_classify_0:
  %7 = const <function:classify@func_classify_0>
  decl_var classify %7
  %8 = const 5
  decl_var x %8
  %9 = call_function classify %8         # classify(5)
  decl_var result %9

Every instruction is a flat dataclass with an opcode, operands, a destination register, and a source location tracing it back to the original line and column. No nested expressions. x > 0 decomposes into LOAD_VAR, CONST, BINOP.

Stage 2: CFG Construction

The CFG builder splits the IR at every LABEL and after every BRANCH/BRANCH_IF/RETURN/THROW, then wires edges based on branch targets:

flowchart TD
    entry(["<b>entry</b><br/>BRANCH end_classify_0"]):::entry
    func("<b>func_classify_0</b><br/>SYMBOLIC param:x · DECL_VAR x<br/>LOAD x · CONST 0 · BINOP ><br/>BRANCH_IF"):::block
    if_true("<b>if_true_0</b><br/>CONST &quot;positive&quot;<br/>DECL_VAR label · BRANCH"):::branch
    if_false("<b>if_false_0</b><br/>CONST &quot;negative&quot;<br/>STORE_VAR label · BRANCH"):::branch
    if_end(["<b>if_end_0</b><br/>LOAD label<br/>RETURN"]):::exit
    end_classify("<b>end_classify_0</b><br/>CONST function · DECL_VAR classify<br/>CONST 5 · DECL_VAR x<br/>CALL classify · DECL_VAR result"):::block

    entry --> end_classify
    entry -.->|"skip"| func
    func -- "T" --> if_true
    func -- "F" --> if_false
    if_true --> if_end
    if_false --> if_end
    end_classify -.->|"call"| func

    classDef entry fill:#e8f4fd,stroke:#4a90d9,stroke-width:2px,color:#1a3a5c
    classDef block fill:#fff3e0,stroke:#e8a735,stroke-width:2px,color:#5c3a0a
    classDef branch fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#3a0a3a
    classDef exit fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#1a3a1a

Stage 3: VM Execution (0 LLM calls)

The deterministic VM executes step by step. When it hits CALL_FUNCTION classify, it pushes a new stack frame, binds the parameter x = 5, and jumps to func_classify_0:

step  1: branch end_classify_0          → skip to end_classify_0
step  2: const <function:classify>       → %7 = <function:classify@func_classify_0>
step  3: decl_var classify %7            → classify = <function>
step  4: const 5                         → %8 = 5
step  5: decl_var x %8                   → x = 5
step  6: call_function classify %8       → push frame, jump to func_classify_0
step  7: symbolic param:x               → %0 = 5 (bound from caller)
step  8: decl_var x %0                   → x = 5
step  9: load_var x                      → %1 = 5
step 10: const 0                         → %2 = 0
step 11: binop > %1 %2                   → %3 = True (5 > 0)
step 12: branch_if %3 if_true,if_false   → True, jump to if_true_0
step 13: const "positive"                → %4 = "positive"
step 14: decl_var label %4               → label = "positive"
step 15: branch if_end_0                 → jump to if_end_0
step 16: load_var label                  → %6 = "positive"
step 17: return %6                       → pop frame, return "positive"
step 18: decl_var result %9              → result = "positive"

Final state: result = "positive"  (18 steps, 0 LLM calls)

Stage 4: Dataflow Analysis

The reaching definitions analysis traces through the register chain. The raw def-use chain says “result depends on %9”. But tracing through: %9 comes from CALL_FUNCTION on classify with argument %8; inside the call, label is set to "positive" (the branch taken); label is loaded into %6 and returned. The dependency graph says: result depends on classify and x.

The LLM-Assisted VM Execution section shows what happens when the source has missing dependencies: the VM creates symbolic placeholders that propagate deterministically, preserving dataflow tracing even without concrete values.

The IR: 33 Opcodes to Rule Them All

See also: IR Reference

The intermediate representation is a flattened three-address code with 33 opcodes, grouped by role:

Value producers:   CONST, LOAD_VAR, LOAD_FIELD, LOAD_INDEX,
                   NEW_OBJECT, NEW_ARRAY, BINOP, UNOP,
                   CALL_FUNCTION, CALL_METHOD, CALL_UNKNOWN,
                   CALL_CTOR

Value consumers:   STORE_VAR, STORE_FIELD, STORE_INDEX, DECL_VAR

Control flow:      BRANCH, BRANCH_IF, LABEL, RETURN, THROW,
                   TRY_PUSH, TRY_POP

Pointers:          ADDRESS_OF, LOAD_INDIRECT, LOAD_FIELD_INDIRECT,
                   STORE_INDIRECT

Regions:           ALLOC_REGION, WRITE_REGION, LOAD_REGION

Continuations:     SET_CONTINUATION, RESUME_CONTINUATION

Escape hatch:      SYMBOLIC

DECL_VAR is a recent addition that separates variable declarations from assignments. Previously, STORE_VAR handled both, always writing to the current stack frame. This meant assignments inside nested functions could never modify outer-scope variables — a fundamental scope chain bug. DECL_VAR writes only to the current frame (for let x = ..., var x = ...), while STORE_VAR now walks the scope chain to find existing bindings. All 15 frontends emit DECL_VAR for declarations and STORE_VAR for assignments.

The first 21 opcodes handle all general-purpose lowering across 15 languages. TRY_PUSH and TRY_POP model structured exception handling (pushing/popping handler labels onto the VM’s exception stack). ADDRESS_OF supports pointer aliasing: &x on a primitive promotes the variable to a heap object and returns a typed Pointer(base, offset), enabling *ptr = 99 to update the original variable through the alias (see Pointer Aliasing). The three region opcodes (ALLOC_REGION, WRITE_REGION, LOAD_REGION) provide byte-addressed memory for COBOL-style overlays, REDEFINES, and packed data layouts. The two continuation opcodes (SET_CONTINUATION, RESUME_CONTINUATION) model COBOL’s PERFORM return semantics, where control transfers to a named paragraph and returns to the caller on completion. The extended opcodes are language-agnostic in the IR and VM; they happen to be emitted by specific frontends but could serve broader use cases.

Every instruction is a frozen dataclass with named fields: an opcode, typed operands (registers as Register objects, labels as CodeLabel objects, operators as BinopKind/UnopKind enums), a destination register, and a source location tracing it back to the original code. Each opcode has its own dataclass (e.g., Binop, LoadVar, CallFunction) rather than a generic container with positional operands. No nested expressions. a + b * c decomposes into:

%0 = const b
%1 = const c
%2 = binop * %0 %1
%3 = const a
%4 = binop + %3 %2

This verbosity is the trade-off for universality. CFG construction, dataflow analysis, and VM execution all operate on the same flat list. Adding a new language means emitting these opcodes; everything downstream works automatically.

Source Location Traceability

Every instruction carries a SourceLocation with start/end line and column, captured from the tree-sitter AST node that generated it. The IR’s string representation appends this:

%0 = const 10  # 1:4-1:6

This means any IR instruction, any VM execution step, any dataflow dependency can be traced back to the exact span of source code that produced it. When a symbolic value appears in the output, its provenance chain leads back to specific source lines.

Control Flow and Functions

All control flow is explicit: labels, conditional branches, and unconditional jumps. There are no structured if/while/for constructs. BRANCH_IF carries its branch targets as a typed branch_targets: tuple[CodeLabel, ...] field. The CFG builder splits the IR into basic blocks at every LABEL and after every BRANCH/BRANCH_IF/RETURN/THROW, then wires edges based on the branch targets. Loops become back-edges: a while loop’s BRANCH at the end of the body points back to the condition’s label. Function definitions use the skip-over pattern shown in the worked example: a BRANCH jumps past the body at definition time, and a FunctionRegistry scans the IR for SYMBOLIC "param:" markers to extract parameter names, map class names to method labels, and build linearized parent chains for class inheritance (see Class Hierarchy and Inherited Method Dispatch).

Four Call Variants

The IR distinguishes four kinds of calls:

• CALL_FUNCTION: static calls where the target is a known name. Fields: func_name, args.
• CALL_METHOD: method calls on objects. Fields: obj_reg, method_name, args.
• CALL_UNKNOWN: dynamic calls where the target is a computed expression (a variable holding a function reference, or a closure). Fields: target_reg, args.
• CALL_CTOR: explicit constructor calls, separating new ClassName(args) from regular function calls. Fields: class_name, args. This avoids the need for runtime heuristics to distinguish constructor calls from function calls, and gives the VM a clean dispatch path for object allocation + initialisation.

The frontend decides which to emit based on the AST: foo(x) emits CALL_FUNCTION, obj.foo(x) emits CALL_METHOD, some_var(x) where some_var isn’t a known function emits CALL_UNKNOWN, and new Foo(x) emits CALL_CTOR.

Object and Array Construction

Objects and arrays are created via NEW_OBJECT/NEW_ARRAY followed by STORE_FIELD/STORE_INDEX for each member. An array literal [1, 2, 3] lowers to:

%0 = const 3
%1 = new_array list %0
%2 = const 0
%3 = const 1
store_index %1 %2 %3         # array[0] = 1
%4 = const 1
%5 = const 2
store_index %1 %4 %5         # array[1] = 2
%6 = const 2
%7 = const 3
store_index %1 %6 %7         # array[2] = 3

This verbose expansion means the VM and dataflow analysis see every individual element assignment, which matters for tracking which values flow into which positions.

The SYMBOLIC Escape Hatch

SYMBOLIC is the escape hatch. When a frontend encounters a construct it doesn’t handle, it emits SYMBOLIC "unsupported:list_comprehension" instead of crashing. The VM treats it as a symbolic value that propagates through execution. Parameters use it too (SYMBOLIC "param:x"), as do caught exceptions (SYMBOLIC "caught_exception:ValueError").

Over time, unsupported: emissions get replaced with real IR as frontends gain coverage. The project’s history is essentially the story of systematically eliminating every last SYMBOLIC.

Frontends: Four Strategies, One Output

See also: Frontend Design · Per-Language Frontend Docs

All four frontend strategies produce the same list of typed instructions. They differ in speed, coverage, and determinism:

1. Deterministic frontends (15 languages): Python, JavaScript, TypeScript, Java, Ruby, Go, PHP, C#, C, C++, Rust, Kotlin, Scala, Lua, Pascal. These use tree-sitter for parsing and a dispatch-table-based recursive descent for lowering. Sub-millisecond. Zero LLM calls. Fully testable. Each frontend is modularised into separate files for expressions, control flow, and declarations, inheriting from a shared BaseFrontend. An optional AST repair decorator can wrap any deterministic frontend to handle malformed source (see the next section).

2. COBOL frontend (ProLeap bridge): COBOL source is parsed by the ProLeap COBOL parser (a Java-based parser producing an Abstract Syntax Graph), bridged to Python via a shaded JAR that emits JSON ASGs. The frontend includes a complete type system: PIC clause parsing (zoned decimal, COMP/COMP-1/COMP-2, packed decimal, alphanumeric, EBCDIC), REDEFINES overlays with byte-addressed memory regions, OCCURS arrays with subscript resolution, level-88 condition names with value ranges, and paragraph-based control flow via named continuations. COBOL-specific IR is emitted using the region and continuation opcodes.

3. LLM frontend: For languages without a deterministic frontend. The source is sent to an LLM constrained by a formal schema: all 33 opcode specs, concrete patterns, and worked examples. The LLM acts as a mechanical compiler frontend, not a reasoning engine. This distinction matters: the prompt doesn’t ask “what does this code do?” It asks “translate this into these specific opcodes.”

4. Chunked LLM frontend: For large files that overflow context windows. Tree-sitter decomposes the file into per-function chunks, each is LLM-lowered independently, registers and labels are renumbered to avoid collisions, and the chunks are reassembled into a single IR.

LLM-Assisted AST Repair

Real-world source code is often malformed: missing semicolons, unclosed brackets, incomplete extracts pasted from documentation, partial files from legacy migrations. Tree-sitter is tolerant of errors (it produces ERROR and MISSING nodes in the AST rather than refusing to parse), but those error nodes reach the dispatch chain and produce SYMBOLIC "unsupported:ERROR" emissions. The deterministic frontend keeps going, but the analysis loses information at every error node.

The AST repair facility recovers that information. It’s implemented as a decorator (RepairingFrontendDecorator) that wraps any deterministic frontend. When the source is clean, the decorator adds zero overhead: it checks tree.root_node.has_error, finds no errors, and delegates directly to the inner frontend. When errors exist, it runs a repair loop:

%%{ init: { "flowchart": { "curve": "stepBefore" } } }%%
flowchart TD
    parse("📄 Parse source<br/><i>tree-sitter</i>"):::step
    check{"has_error?"}:::decide
    delegate("✅ Delegate to<br/>inner frontend"):::success
    extract("🔍 Extract<br/>error spans"):::step
    prompt("📝 Build<br/>repair prompt"):::step
    llm("🤖 Send to LLM"):::llm
    patch("🩹 Patch source<br/><i>at error spans</i>"):::step
    reparse("📄 Re-parse<br/><i>patched source</i>"):::step
    recheck{"has_error?"}:::decide
    fallback("⚠️ Fall back to<br/>original source"):::fallback

    parse --> check
    check -->|"No"| delegate
    check -->|"Yes"| extract
    extract --> prompt --> llm --> patch --> reparse --> recheck
    recheck -->|"No"| delegate
    recheck -->|"Yes (retries left)"| extract
    recheck -->|"Yes (exhausted)"| fallback
    fallback --> delegate

    classDef step fill:#fff3e0,stroke:#e8a735,stroke-width:2px,color:#5c3a0a
    classDef decide fill:#e8f4fd,stroke:#4a90d9,stroke-width:2px,color:#1a3a5c
    classDef llm fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#3a0a3a
    classDef success fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#1a3a1a
    classDef fallback fill:#fce4ec,stroke:#c62828,stroke-width:1px,color:#5c0a0a

The loop has four stages, each implemented as a pure function:

1. Error Span Extraction

The extractor walks the tree-sitter AST recursively, collecting every ERROR and MISSING node. Each node’s byte offsets are expanded to cover full source lines (so the LLM sees complete lines, not mid-line fragments). Overlapping or adjacent spans are merged to avoid sending redundant context. Each merged span gets N lines of surrounding context (configurable, default 3) attached as context_before and context_after.

2. Prompt Construction

The prompter builds a structured repair prompt from the error spans. The system prompt constrains the LLM to fix only syntax errors and return only the repaired code, with no markdown wrapping and no explanations. Each error span becomes a delimited section in the user prompt showing the broken code with its surrounding context:

# Context before:
def process(data):
    result = []

# Broken code:
    for item in data
        result.append(item.value

# Context after:
    return result

Multiple error spans are separated by a ===FRAGMENT=== delimiter. The LLM returns repaired fragments separated by the same delimiter.

3. Source Patching

The patcher applies repaired fragments back to the original source bytes. It processes spans from end-of-file backward so that earlier byte offsets remain valid as later spans are replaced. This is the same technique compilers use for applying source-level fixups.

4. Re-parse and Retry

The patched source is re-parsed with tree-sitter. If the parse is now clean (has_error is false), the repaired source is passed to the inner deterministic frontend for lowering. If errors remain and retry budget allows (default: 3 attempts), the loop repeats from step 1 with the partially-repaired source. If all retries are exhausted, the decorator falls back to the original source, accepting SYMBOLIC emissions for the error nodes rather than crashing.

Design Properties

The LLM fixes syntax, not semantics. The prompt constrains the LLM to syntactic repair: fix the missing semicolon, close the bracket, complete the partial statement. This keeps the repair narrowly scoped and verifiable (the repaired source either parses cleanly or it doesn’t).

Graceful degradation. If the LLM returns garbage, the retry budget is eventually exhausted and the decorator falls back to the original source. The worst case is identical to not having repair at all.

LLM Frontend: Lowering Unknown Languages

The 15 deterministic frontends cover a fixed set of languages. For everything else (Haskell, Elixir, Perl, R, Fortran, or any language with parseable source), the LLM frontend lowers source directly to IR. No tree-sitter grammar needed, no dispatch table, no language-specific code. The LLM acts as the entire compiler frontend.

The Prompt as a Formal Schema

The LLM frontend works by constraining the LLM to a mechanical translation task. The system prompt is a specification containing:

1. The instruction format: every IR instruction is a JSON object with opcode, result_reg, operands, label, and source_location fields.
2. All 33 opcode definitions: grouped into value producers (CONST, LOAD_VAR, BINOP, CALL_FUNCTION, …), consumers/control flow (STORE_VAR, BRANCH_IF, RETURN, …), and special instructions (SYMBOLIC, LABEL).
3. Critical patterns: exact lowering templates for function definitions (the skip-over pattern with BRANCH/LABEL/SYMBOLIC param:/implicit RETURN None), class definitions, constructor calls, method calls, and if/elif/else chains.
4. A complete worked example: a fib(n) function lowered to 30 IR instructions, showing every convention in context.
5. Rules: the first instruction is always LABEL "entry", every expression is flattened into registers, string literals include quotes in the operand, booleans are "True"/"False", return only the JSON array with no markdown fences.

The user prompt is simply: “Lower the following {language} source code into IR instructions:” followed by the raw source. The opcode definitions and patterns are the specification; the LLM is the translator.

Parsing and Validation

The LLM’s response (a JSON array of instruction objects) goes through three stages:

1. Fence stripping: markdown code fences are removed if present (LLMs add them reflexively despite being told not to).
2. JSON parsing: each object is mapped to an IRInstruction, validating that every opcode string matches the Opcode enum. Unknown opcodes raise IRParsingError.
3. Entry label validation: if the first instruction isn’t LABEL "entry", one is auto-prepended with a warning. This ensures the CFG builder always finds a valid entry point.

If JSON parsing fails, the frontend retries up to 3 times (configurable). Each retry makes a fresh LLM call. If all retries are exhausted, the parsing error propagates.

Chunked LLM Frontend: Scaling to Large Files

A single LLM call can’t handle a 2,000-line file: the source plus the system prompt plus the response would overflow the context window. The chunked frontend solves this by decomposing the file before calling the LLM.

The decomposition uses tree-sitter for structural splitting (even though the language may not have a deterministic lowering frontend, tree-sitter grammars exist for most languages). The ChunkExtractor walks the top-level children of the parse tree and classifies each as a function, class, or top-level statement. Contiguous top-level statements are grouped into a single chunk. Functions and classes are emitted first, then top-level groups, preserving the definition-before-use ordering that the skip-over pattern requires.

Each chunk is lowered independently through the standard LLMFrontend. The IRRenumberer then fixes up the results:

• Register renumbering: each chunk’s registers start at %0, so the renumberer offsets them (%0 in chunk 2 becomes %47 if chunk 1 used registers up to %46).
• Label renumbering: each chunk’s labels get a _chunkN suffix to avoid collisions (if_true_2 in chunk 1 vs. if_true_2_chunk1).
• Function reference fixup: the <function:foo@func_foo_0> convention embeds the label in a string literal. The renumberer patches these to match the suffixed labels.

The entry label is stripped from each chunk’s output and a single LABEL "entry" is prepended to the combined result. If a chunk fails (the LLM returns unparseable JSON), a SYMBOLIC "chunk_error:chunk_name" placeholder is inserted and lowering continues with the next chunk.

End-to-End Example: Haskell

Haskell has no deterministic frontend in RedDragon. Here is the full pipeline for a Haskell program with pattern-matched recursion, imports, and external function calls:

import Data.Char (toUpper, ord)

factorial :: Int -> Int
factorial 0 = 1
factorial n = n * factorial (n - 1)

x = factorial 5
ch = toUpper 'a'
code = ord ch
total = x + code

The LLM frontend receives this source along with the 180-line system prompt and produces IR following the same conventions as the deterministic frontends. The factorial function is lowered using the skip-over pattern:

entry:
  branch end_factorial_1          # skip over function body

func_factorial_0:
  %0 = symbolic "param:n"
  decl_var n %0
  %1 = load_var n
  %2 = const 0
  %3 = binop == %1 %2
  branch_if %3 if_true_2,if_false_3

if_true_2:
  %4 = const 1
  return %4

if_false_3:
  %5 = load_var n
  %6 = const 1
  %7 = binop - %5 %6
  %8 = call_function factorial %7
  %9 = load_var n
  %10 = binop * %9 %8
  return %10
  %11 = const "None"
  return %11

end_factorial_1:
  %12 = const "<function:factorial@func_factorial_0>"
  decl_var factorial %12

The top-level bindings follow the same pattern: CONST + CALL_FUNCTION + DECL_VAR for each declaration. At execution time, factorial(5) resolves to 120 deterministically (concrete recursive call). toUpper('a') and ord(ch) are unresolved Data.Char functions, handled by the UnresolvedCallResolver: the default SymbolicResolver traces dependencies through symbolic placeholders; the opt-in LLMPlausibleResolver produces concrete values ('A', 65, total = 185). From Haskell source to executed VM state, with zero language-specific code.

The Dispatch Table Engine

See also: Base Frontend Design

The heart of the deterministic frontends is a BaseFrontend class that all 15 languages inherit from. It uses two dispatch tables (one for statements, one for expressions) mapping tree-sitter AST node types to handler methods.

The lowering dispatch chain:

%%{ init: { "flowchart": { "curve": "stepBefore" } } }%%
flowchart TD
    lower("lower(root)"):::fn
    block("_lower_block(root)<br/><i>iterate named children</i>"):::fn
    stmt("_lower_stmt(child)<br/><i>skip noise/comments; try STMT_DISPATCH</i>"):::fn
    expr("_lower_expr(child)<br/><i>fallback: try EXPR_DISPATCH</i>"):::fn
    sym("⚠️ SYMBOLIC('unsupported:X')<br/><i>final fallback</i>"):::fallback

    lower --> block --> stmt --> expr --> sym

    classDef fn fill:#fff3e0,stroke:#e8a735,stroke-width:2px,color:#5c3a0a
    classDef fallback fill:#fce4ec,stroke:#c62828,stroke-width:2px,color:#5c0a0a

Common constructs (if/else, while, for, for-each with destructuring, return, function_definition, class_definition, try/catch) are handled in the base class. For-loop destructuring (for (const [k, v] of arr) in JS/TS, for ((k, v) in map) in Kotlin, structured bindings in C++) decomposes binding patterns into individual LOAD_INDEX/LOAD_FIELD + STORE_VAR instructions per iteration. Language-specific constructs override or extend. Overridable constants handle the small but persistent differences across grammars:

# Python says "True", Go says "true", Lua says "true"
TRUE_LITERAL: str = "True"    # default
FALSE_LITERAL: str = "False"
NONE_LITERAL: str = "None"

# Python puts the body in "body", Go puts it in "block"
FUNC_BODY_FIELD: str = "body"
IF_CONSEQUENCE_FIELD: str = "consequence"

All 15 languages canonicalise their native null/boolean forms to Python-form at lowering time. nil, null, undefined, NULL all become "None". true, True, TRUE all become "True". This means the VM only handles one set of literals, regardless of source language.

Adding support for a new AST node type is mechanical: write a handler method, register it in the dispatch table. This is what made the systematic coverage push possible. When the audit flagged 34 missing node types across 15 languages, implementing them was straightforward because each one followed the same pattern.

Lowering Equivalence

If 15 frontends lower the same algorithm from 15 different languages, does the resulting IR look the same? It should. The whole point of a universal IR is that downstream analysis (VM execution, dataflow, CFG) doesn’t depend on the source language. If two frontends produce structurally different IR for the same logic, it means one of them has a bug or an unnecessary inefficiency.

The lowering equivalence tests verify this directly. For each algorithm, the test lowers the source through all 15 deterministic frontends, extracts the function body from the IR (scanning for the LABEL func_<name>_N … LABEL end_<name>_N markers), strips LABEL instructions (which vary in naming across languages), and compares the resulting opcode sequences.

Iterative Factorial: Full Equivalence

The iterative factorial is implemented in all 15 languages using the same structure: initialise result = 1 and i = 2, loop while i <= n, multiply result *= i, increment i, return result. Despite the syntactic differences (Python’s while, Go’s for, Rust’s loop with break, Pascal’s while...do), all 15 frontends produce the identical opcode sequence:

SYMBOLIC, DECL_VAR, CONST, DECL_VAR, CONST, DECL_VAR,
LOAD_VAR, LOAD_VAR, BINOP, BRANCH_IF, LOAD_VAR, LOAD_VAR,
BINOP, STORE_VAR, LOAD_VAR, CONST, BINOP, STORE_VAR, BRANCH,
LOAD_VAR, RETURN, CONST, RETURN

This is a 23-opcode sequence: parameter binding, three initialisations, the loop condition (LOAD_VAR i, LOAD_VAR n, BINOP <=, BRANCH_IF), the loop body (BINOP *, STORE_VAR result, BINOP +, STORE_VAR i, BRANCH back), and the return path. Every frontend, from C to Lua to Scala, produces exactly this sequence.

Recursive Factorial: Partial Equivalence

The recursive variant (if n <= 1: return 1; return n * factorial(n - 1)) achieves equivalence across 11 of 15 frontends. Four languages (Kotlin, Pascal, Rust, Scala) emit minor redundant instructions: an extra STORE_VAR/LOAD_VAR pair or an unreachable BRANCH. These are semantically correct (the VM produces the right answer) but structurally non-identical. The test is marked xfail with strict=True, so it will fail loudly when the frontends are fixed, signalling that the xfail should be removed.

The structural differences are instructive:

• Kotlin emits an extra LOAD_VAR before the return, because Kotlin’s tree-sitter grammar wraps the return value in a parenthesized_expression that the frontend lowers as a separate load.
• Rust emits an extra BRANCH after the implicit return, because Rust’s expression-position blocks produce a trailing unconditional jump to the function end label.
• Pascal and Scala have similar minor redundancies from language-specific AST structures.

These are all candidates for frontend-level peephole optimisations: removing dead stores, eliminating redundant loads, pruning unreachable branches. The equivalence test makes the gap visible and quantifiable.

What Equivalence Tests Catch

The equivalence tests complement the Exercism execution tests. Exercism verifies that all 15 frontends produce the correct answer. Equivalence tests verify that they produce the same IR structure. A frontend could produce the correct answer through a longer, less efficient IR path (extra stores, redundant loads, unnecessary branches). The execution test would pass; the equivalence test would fail.

This distinction matters for analysis quality. Redundant instructions can introduce spurious dependencies in the dataflow graph, create unnecessary basic blocks in the CFG, or slow down the VM. Structural equivalence is a stronger property than semantic correctness.

The Deterministic VM

See also: VM Design

The VM is fully deterministic. Unknown values are created as symbolic placeholders that propagate through computation, rather than being resolved via LLM calls. The entire execution engine is reproducible across runs.

VM State: Frames, Heap, and Closures

The VM’s state is held in a single VMState dataclass:

@dataclass
class VMState:
    heap: dict[str, HeapObject]          # flat object store
    call_stack: list[StackFrame]         # LIFO execution frames
    path_conditions: list[str]           # branch assumptions
    symbolic_counter: int = 0            # fresh-name generator
    closures: dict[str, ClosureEnvironment]  # shared mutable cells

Each StackFrame has a two-level namespace: registers for IR temporaries (%0, %1, …) and local_vars for source-level named variables. This separation keeps the three-address code machinery invisible to the analysis layer, which only cares about named variables.

The heap is a flat dictionary mapping addresses ("obj_0", "arr_1") to HeapObject instances. Each HeapObject stores a type_hint and a fields dictionary. Arrays use stringified indices as field keys. This uniform representation means the VM doesn’t distinguish between object field access and array indexing at the storage level.

The Execution Loop

The VM executes one instruction per step in a bounded loop. Each step fetches, dispatches, coerces, applies, and resolves control flow:

flowchart TD
    START(("🔄 Step N")):::start

    FETCH("Fetch instruction<br/><i>block.instructions[ip]</i>"):::step
    LABEL{"LABEL?"}:::decide
    DISPATCH("🔧 LocalExecutor.execute()<br/><i>dispatch table → handler</i>"):::step
    HANDLED{"handled?"}:::decide
    LLM("🤖 LLM Backend<br/><i>interpret_instruction()</i>"):::llm
    COERCE_L("coerce_local_update()"):::coerce
    COERCE_M("materialize_raw_update()<br/><i>deserialize + coerce + wrap</i>"):::coerce

    CALL{"call_push<br/>+ next_label?"}:::decide
    CALL_SETUP("⬇️ Push frame<br/><i>save return_label, return_ip,<br/>result_reg</i>"):::step
    APPLY("apply_update()<br/><i>registers, vars, heap,<br/>closures, objects</i>"):::apply

    RET{"RETURN<br/>or THROW?"}:::decide
    RETFLOW("⬆️ Pop frame<br/><i>write return value to<br/>caller's result_reg</i>"):::step
    STOP(("🛑 End")):::stop
    JUMP{"next_label<br/>set?"}:::decide
    NEXT_BLOCK("Jump to block<br/><i>ip = 0</i>"):::step
    NEXT_IP("ip += 1"):::step

    START --> FETCH
    FETCH --> LABEL
    LABEL -- "yes" --> NEXT_IP
    LABEL -- "no" --> DISPATCH
    DISPATCH --> HANDLED
    HANDLED -- "yes" --> COERCE_L
    HANDLED -- "no" --> LLM
    LLM --> COERCE_M
    COERCE_L --> CALL
    COERCE_M --> CALL
    CALL -- "yes" --> CALL_SETUP
    CALL_SETUP --> APPLY
    CALL -- "no" --> APPLY
    APPLY --> RET
    RET -- "yes" --> RETFLOW
    RETFLOW -- "top-level" --> STOP
    RETFLOW -- "has caller" --> NEXT_BLOCK
    RET -- "no" --> JUMP
    JUMP -- "yes" --> NEXT_BLOCK
    JUMP -- "no" --> NEXT_IP
    NEXT_IP --> START
    NEXT_BLOCK --> START

    classDef start fill:#e8f4fd,stroke:#4a90d9,stroke-width:3px,color:#1a3a5c
    classDef stop fill:#fce4ec,stroke:#c62828,stroke-width:3px,color:#5c0a0a
    classDef step fill:#fff3e0,stroke:#e8a735,stroke-width:2px,color:#5c3a0a
    classDef decide fill:#e8f4fd,stroke:#4a90d9,stroke-width:2px,color:#1a3a5c
    classDef llm fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#3a0a3a
    classDef coerce fill:#fff9c4,stroke:#f9a825,stroke-width:2px,color:#5c3a0a
    classDef apply fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#1a3a1a

The critical design point: every path converges on apply_update(). Whether the instruction was executed locally or by the LLM backend, the state change flows through the same single mutator. The LLM path adds a materialization step (deserialize JSON, coerce types, wrap in TypedValue), but the state application is identical.

The call dispatch path saves the return address (return_label, return_ip) and result register on the new frame before apply_update runs, so parameter bindings land in the callee’s frame automatically. On return, the saved metadata tells the loop where to resume in the caller.

Opcode Dispatch

The LocalExecutor maps each of the 33 Opcode enum values to a handler function via a static dispatch table:

DISPATCH: dict[Opcode, Any] = {
    Opcode.CONST: _handle_const,
    Opcode.BINOP: _handle_binop,
    Opcode.CALL_FUNCTION: _handle_call_function,
    Opcode.LOAD_FIELD: _handle_load_field,
    # ... all 33 opcodes
}

Every handler receives the instruction, the VM state, the CFG, and a function registry, and returns an ExecutionResult. No handler mutates the VM directly. Instead, each constructs a StateUpdate describing the desired mutations.

StateUpdate: The Communication Contract

StateUpdate is the universal contract between handlers and the state engine. It’s a pure data object listing all effects:

class StateUpdate:
    register_writes: dict[str, TypedValue]  # %0 = TypedValue(42, Int)
    var_writes: dict[str, TypedValue]       # x = TypedValue("hello", String)
    heap_writes: list[HeapWrite]            # obj.field = TypedValue(...)
    new_objects: list[NewObject]            # allocate on heap
    call_push: StackFramePush | None        # push new frame
    call_pop: bool                          # pop frame on return
    path_condition: str | None              # branch assumption
    next_label: str | None                  # jump target

All values flowing through StateUpdate are TypedValue objects — frozen dataclasses pairing a raw Python value with its TypeExpr type. This means type information is carried alongside every value throughout the execution pipeline, from handler output through state mutation to subsequent reads.

This separation of computation (handlers) from mutation (apply_update) is a deliberate functional core / imperative shell split. The handlers are pure functions that return data. The mutation is centralised in one place.

TypedValue: Runtime Type Propagation

Every runtime value in the VM is a TypedValue — a frozen dataclass pairing a raw value with its inferred type:

@dataclass(frozen=True)
class TypedValue:
    value: Any       # int, str, SymbolicValue, Pointer, ...
    type: TypeExpr   # ScalarType("Int"), ParameterizedType("Array", ...), ...

Registers, local variables, heap fields, and closure bindings all store TypedValue. This bridges the static type inference pass (which runs before execution) with runtime coercion: when a BINOP operates on two TypedValue operands, it can inspect their types to apply language-specific coercion rules (e.g., Java’s String + int auto-stringification) without consulting the TypeEnvironment at every step.

Three helpers simplify construction: typed(value, type_expr) for explicit typing, typed_from_runtime(value) for inferring type from a Python value, and VOID_RETURN (a canonical TypedValue(None, Void)) for procedures that return nothing.

Two-Layer Type Coercion

Type coercion operates at two points:

Layer 1 (Pre-operation): Pluggable BinopCoercionStrategy and UnopCoercionStrategy coerce operands before evaluation. The default strategies are no-ops, but language-specific strategies override them — JavaBinopCoercion auto-stringifies when one operand of + is a String. Each strategy also infers the result type.

Layer 2 (Write-time): TypeConversionRules coerce values when storing into typed registers (Int → Float widening, Float → Int narrowing, Bool → Int promotion). This layer operates inside apply_update().

BuiltinResult

Built-in functions return a BuiltinResult — a uniform type distinguishing pure builtins from those with side effects:

@dataclass
class BuiltinResult:
    value: Any
    new_objects: list[NewObject] = field(default_factory=list)
    heap_writes: list[HeapWrite] = field(default_factory=list)

Pure builtins (len, abs, max) return BuiltinResult(value=result) with empty side-effect lists. Heap-mutating builtins (list.append, array_of) express mutations as structured new_objects and heap_writes that the executor applies through the same apply_update() path. This eliminated the previous inconsistency where some builtins returned bare values and others returned tuples with side effects.

apply_update(): The Single Mutator

All state changes flow through apply_update(), which applies a StateUpdate in strict order: new objects, register writes, heap writes, path conditions, call push, variable writes, call pop. The ordering matters: call push (step 5) happens before variable writes (step 6), so parameter bindings automatically land in the new frame without special-casing. Variable writes also handle closure synchronisation: if a variable is in the frame’s captured_var_names, the write is mirrored to the shared ClosureEnvironment.

Symbolic Value Propagation

When execution hits an unresolved import or function, the VM creates a SymbolicValue with a descriptive hint:

sym_0 (hint: "math.sqrt(16)")

This symbolic value propagates through computation deterministically. Each handler checks whether its operands are symbolic. If either operand of a BINOP is symbolic, the result is a fresh symbolic with a constraint recording the expression:

sym_0 + 1  →  sym_1 (constraint: "sym_0 + 1")

Field access on a symbolic object creates a symbolic field with lazy heap materialisation: the first access to sym_0.x allocates a synthetic heap entry and caches a symbolic value for x, so subsequent accesses to the same field return the same symbolic. This deduplication is important for dataflow analysis, where repeated reads of the same field should trace back to the same definition.

Concrete operations that fail (division by zero, unsupported operator) produce an UNCOMPUTABLE sentinel, which triggers symbolic fallback rather than crashing.

The trade-off is that symbolic branches always take the true path (a simplification), and symbolic values can’t be resolved to concrete results without help.

The UnresolvedCallResolver

For the latter trade-off, a configurable UnresolvedCallResolver uses the Strategy pattern. Two strategies ship with RedDragon: a default symbolic resolver (zero LLM calls, fully deterministic) and an opt-in LLM-based resolver that produces plausible concrete values. The next section covers this mechanism in detail.

Closures

One subtle design iteration worth mentioning: closure capture semantics. The initial implementation captured variables by snapshot (copy at definition time). This broke counter factories:

def make_counter():
    count = 0
    def inc():
        count += 1
        return count
    return inc

With snapshot capture, inc() always reads count = 0. The fix was shared ClosureEnvironment cells: all closures from the same scope share a mutable environment, matching Python/JavaScript semantics. When a nested function is created, the enclosing frame’s variables are copied into a ClosureEnvironment. On each call, captured variables are injected into the new frame, and apply_update() mirrors writes back to the shared environment. This is the kind of deep correctness issue that only surfaces through specific test cases. It’s documented as ADR-019 in the project’s architectural decision records.

Class Hierarchy and Inherited Method Dispatch

OOP languages encode class hierarchies differently: Java uses extends, Python lists bases in the class signature, Ruby uses <, C++ has access-specified base lists, and so on. RedDragon handles all of these through a single mechanism in the FunctionRegistry, without adding any new IR opcodes.

Each frontend extracts parent class names from its language-specific tree-sitter nodes and encodes them in the class reference string: <class:Dog@class_Dog_0:Animal> records that Dog extends Animal. The registry’s _scan_classes method collects these direct parents, and _expand_parent_chains transitively expands them into a linearized list. For a chain C extends B extends A, class_parents["C"] becomes ["B", "A"].

At execution time, when CALL_METHOD resolves a method on an object, the executor first looks in the child class’s method table. On a miss, it walks class_parents until it finds a matching method:

# Walk parent chain for inherited methods
for parent in registry.class_parents.get(type_hint, []):
    parent_methods = registry.class_methods.get(parent, {})
    candidate = parent_methods.get(method_name, "")
    if candidate and candidate in cfg.blocks:
        func_label = candidate
        break

Method override works naturally: the child’s method table is checked first, so a redefined method in the child shadows the parent’s version. Multi-level inheritance (C → B → A) resolves at any depth.

Ten OOP frontends extract parent classes: Java, Python, C#, Kotlin, Ruby, JavaScript, TypeScript, Scala, PHP, and C++. Each uses a shared make_class_ref helper to encode parents into the class reference string, keeping the language-specific code minimal. The five non-OOP frontends (C, Go, Rust, Lua, Pascal) are unaffected.

Overload Resolution

When a class defines multiple methods with the same name but different parameter types (common in Java, C#, Kotlin, Scala, C++), the VM needs to select the right overload at call time. The OverloadResolver uses a composable strategy pattern:

ArityThenTypeStrategy ranks candidates in two passes:

1. Arity distance: how many parameters differ from the call site’s argument count
2. Type compatibility score: exact match (2 points), coercion or subtype match (1 point), mismatch (-1 point)

The type scoring uses TypeGraph.is_subtype_expr() for inheritance-aware dispatch: passing a Dog to foo(Dog) scores higher than foo(Animal). Primitive coercions (Int → Float, Bool → Int) score as compatible but below exact matches. Since the resolver receives list[TypedValue] arguments, full type metadata is available without consulting the TypeEnvironment.

Symbol Table

The SymbolTable is a pre-execution data structure extracted from the IR by each frontend during lowering. It maps class names to their fields, methods, static fields, and parent classes — information that was previously recovered at runtime by scanning IR instructions.

The symbol table is populated via a _extract_symbols pre-pass hook on BaseFrontend. All 15 language frontends implement symbol extraction. The executor receives the symbol table at construction time and uses it for:

• Cross-class field resolution: SymbolTable.resolve_field walks the class hierarchy to find which class owns a field, enabling field access in subclass constructors without explicit this.parent_field qualification.
• Implicit-this field access: In Java, C#, and C++, methods can reference fields without this. — age = 10 inside a constructor means this.age = 10. The executor checks the symbol table to determine whether an unqualified name refers to a class field, and if so, rewrites the access as a STORE_FIELD/LOAD_FIELD on the implicit this parameter.
• Static method dispatch: Class::method() calls (PHP, C++, Rust) are lowered with a ClassRef marker in the CALL_METHOD instruction. The executor uses the symbol table to verify the target is a static method and dispatches without requiring an object instance.

Pointer Aliasing

C and Rust programs use &x to take the address of a variable. In most analysis tools, this creates an aliasing relationship that’s tracked through a separate alias analysis pass. RedDragon handles it directly in the VM through a KLEE-inspired promote-on-address-of model.

When the VM encounters ADDRESS_OF, it promotes the target variable from a primitive to a HeapObject and returns a typed Pointer(base, offset) value. Subsequent writes through the pointer (*ptr = 99) go through the heap and update the original variable’s storage. This means aliasing is exact: *ptr and x always see the same value, with no approximation.

%0 = const 42
decl_var x %0
%1 = address_of x               # promote x to heap, return Pointer
decl_var ptr %1
%2 = const 99
store_field ptr "value" %2       # *ptr = 99; x is now 99
%3 = load_var x                  # %3 = 99 (reads through heap)

The model supports nested pointers (int **pp), pointer arithmetic (ptr + 1 offsets into arrays), pointer subtraction (returns the offset difference between same-base pointers), pointer relational comparisons (<, >, == on offsets within the same base), struct pointers (arrow operator via LOAD_FIELD), and array pointer decay. The C and Rust frontends emit ADDRESS_OF for &identifier expressions.

Slicing

All 15 languages support array and string slicing in execution. Each language’s slice syntax is lowered to the same SLICE IR operation, and the VM handles the semantics uniformly:

• Python: a[1:3], a[::2], a[-2:]
• Ruby: arr[1..3] (inclusive range), arr[1...3] (exclusive), arr[start, length] (positional)
• Rust: arr[1..3] (exclusive), arr[1..=3] (inclusive)
• Go: a[1:3], a[2:], string slicing
• Kotlin: subList() and substring() via METHOD_TABLE dispatch

Rest Patterns and Variadic Parameters

JavaScript and TypeScript support rest patterns in destructuring and function parameters:

Array destructuring: const [a, ...rest] = arr — the frontend emits a SLICE operation to extract remaining elements into the rest variable.

Object destructuring: const {a, ...rest} = obj — remaining properties are spread into a new object on the heap.

Function rest parameters: function f(a, ...args) — the frontend injects an arguments array into the function’s local scope and emits a SLICE to extract the variadic portion into the rest parameter.

Anonymous Class Resolution

TypeScript and JavaScript allow assigning anonymous classes to variables: const MyClass = class { ... }. When new MyClass() is encountered, the VM resolves it by checking the variable store if the name isn’t in the class registry:

if class_name not in self.class_registry:
    resolved = self.current_frame.lookup(class_name)
    if isinstance(resolved, str):
        class_name = resolved

This reuses the existing variable store as the lookup table — no new data structures needed.

Language Prelude Classes

Some languages have standard library types that are integral to idiomatic code but don’t exist as user-defined classes in the source. Rust’s Box<T> and Option<T> are examples: linked list implementations use Box::new(node) and Some(value) pervasively.

Rather than adding VM-level special cases, each frontend can override an _emit_prelude hook to emit synthetic class definitions during lowering:

• Box::new(expr) is a pass-through — it returns its argument directly. In RedDragon’s reference-based VM, all values are already heap-allocated, so Box adds no indirection. This matches Rust’s auto-deref semantics transparently.
• Option is emitted as a real class with __init__(self, value), unwrap(self), and as_ref(self) methods. Some(expr) lowers to CALL_FUNCTION "Option".

The prelude hook is a no-op by default. Only the Rust frontend overrides it. The registry recognises prelude class labels via a prefix constant, so prelude classes participate in method dispatch and type inference like any user-defined class.

Structural Pattern Matching

Languages like Python, Rust, C#, and Scala have structural pattern matching constructs (match/switch with destructuring), where a subject value is tested against a sequence of patterns that can bind variables, decompose structures, and guard with conditions. RedDragon handles these through a common Pattern ADT (interpreter/frontends/common/patterns.py) shared across frontends.

The ADT defines pattern types that compose recursively:

LiteralPattern(value)                    # 42, "hello", true
WildcardPattern()                        # _
CapturePattern(name)                     # x (bind to variable)
OrPattern(alternatives)                  # 1 | 2 | 3
SequencePattern(elements)               # (a, b, _) — tuple destructuring
ClassPattern(class_name, positional, keyword)  # Point { x, y } or Some(x)
ValuePattern(parts)                      # Color::Red, Color.Red
AsPattern(inner, name)                   # x: Int (isinstance + bind)

Two shared compiler functions translate patterns into IR without any new opcodes:

• compile_pattern_test(ctx, subject_reg, pattern) emits a chain of BINOP ==, LOAD_FIELD, LOAD_INDEX, and BRANCH_IF instructions that evaluate to a boolean test register. Nested patterns recurse and AND the results together.
• compile_pattern_bindings(ctx, subject_reg, pattern) emits LOAD_FIELD/LOAD_INDEX + DECL_VAR instructions that extract and bind matched components to local variables.

Each frontend maps its language’s tree-sitter AST nodes to the Pattern ADT through a parse_<lang>_pattern function:

• Python maps match_statement cases: case_pattern, class_pattern, as_pattern, or_pattern.
• C# maps switch_expression arms: constant_pattern, declaration_pattern, var_pattern, property_pattern, discard_pattern.
• Rust maps match_expression arms: integer_literal → LiteralPattern, identifier → CapturePattern, tuple_struct_pattern → ClassPattern (with prelude variant resolution: Some(x) becomes ClassPattern("Option", ...)), struct_pattern → ClassPattern with keyword args, or_pattern, tuple_pattern, scoped_identifier → ValuePattern. Rust match is expression-style (returns a value), so the frontend uses compile_pattern_test/compile_pattern_bindings directly rather than the statement-level compile_match, storing each arm’s result into a shared result variable.

Because the Pattern ADT compiles down to existing IR opcodes (BINOP, LOAD_FIELD, LOAD_INDEX, BRANCH_IF, DECL_VAR), no VM changes are needed. The VM, CFG builder, and dataflow analysis all handle pattern matching transparently.

Built-in Functions

The VM includes a small table of built-in functions (len, range, print, int, float, str, bool, abs, max, min, plus array constructors) that are resolved before falling through to the UnresolvedCallResolver. Each built-in handles symbolic arguments gracefully: len of a symbolic list returns a symbolic, range with symbolic bounds returns UNCOMPUTABLE, and so on. This keeps common operations concrete without requiring language-specific runtime support.

LLM-Assisted VM Execution

The deterministic VM handles known functions, built-ins, class constructors, and concrete operations without external help. But real-world code calls libraries, frameworks, and system functions that don’t exist in the IR. When the VM exhausts all internal resolution paths (built-in table, function registry, class constructors, string/list indexing conversion), it delegates to an UnresolvedCallResolver. For a program with 50 function calls where 45 are to local functions and built-ins, only 5 hit the resolver.

This is the third and final point where an LLM can enter the pipeline. The first is at the frontend (lowering source to IR). The second is AST repair (fixing malformed syntax). This third point is at runtime: resolving calls to functions whose implementations are unavailable.

The Strategy Pattern

The resolver is a pluggable strategy, selected at pipeline configuration time:

class UnresolvedCallResolver(ABC):
    @abstractmethod
    def resolve_call(self, func_name, args, inst, vm) -> ExecutionResult: ...

    @abstractmethod
    def resolve_method(self, obj_desc, method_name, args, inst, vm) -> ExecutionResult: ...

Both resolve_call (for CALL_FUNCTION and CALL_UNKNOWN) and resolve_method (for CALL_METHOD) return an ExecutionResult containing a StateUpdate, the same data object that every opcode handler returns. This means the resolver’s output flows through the same apply_update() path as everything else. No special cases.

SymbolicResolver (Default)

The default resolver creates a fresh SymbolicValue for any unknown call (e.g., sym_0 (hint: "math.sqrt(16)")). The symbolic propagation described in the VM section takes over from there: dependent operations produce constrained symbolics, and the dataflow analysis traces dependencies through them. This is the right default for most analysis tasks, where knowing that a dependency exists matters more than knowing its concrete value.

LLMPlausibleResolver (Opt-In)

When concrete results matter (e.g., verifying that a computed value matches an expected output), the LLMPlausibleResolver asks an LLM to produce a plausible return value.

The resolver sends a structured JSON prompt containing:

{
  "call": "math.sqrt(16)",
  "args": [16],
  "result_reg": "%5",
  "state": {
    "local_vars": {"x": 16, "y": "sym_0"},
    "heap": {}
  },
  "language": "python"
}

The system prompt constrains the LLM to return a JSON object with:

• value: the concrete return value (or null if unknowable)
• heap_writes: any side effects as [{"obj_addr": "...", "field": "...", "value": ...}]
• var_writes: any variable mutations as {"name": value}
• reasoning: a short explanation

For standard library functions (math.sqrt, string.upper, list.append), the prompt instructs the LLM to compute the exact result. For unknown functions, it asks for a best estimate based on the name and arguments.

The response is parsed into a StateUpdate and applied through the same apply_update() path. If the LLM returns invalid JSON or the call fails for any reason, the resolver falls back to SymbolicResolver automatically. The worst case is identical to not using LLM resolution at all.

Worked Example: Analysing Code with Missing Dependencies

Consider a Python program that uses requests (not available in the IR) and a local function:

import requests

def extract_name(data):
    return data["user"]["name"]

response = requests.get("https://api.example.com/users/1")
body = response.json()
name = extract_name(body)
greeting = "Hello, " + name

The deterministic frontend lowers this to IR. extract_name gets a full function definition (skip-over pattern, parameter binding, LOAD_FIELD chain). requests.get and response.json() are calls to unresolved externals.

With SymbolicResolver:

response  = sym_0 (hint: "requests.get('https://api.example.com/users/1')")
body      = sym_1 (hint: "sym_0.json()")

The VM enters extract_name with data = sym_1. The LOAD_FIELD for data["user"] triggers lazy heap materialisation: a synthetic heap entry is created for sym_1, and a symbolic field user is cached. Then LOAD_FIELD for ["name"] creates another symbolic. The result:

name      = sym_3 (hint: "sym_2.name")  where sym_2 = sym_1["user"]
greeting  = sym_4 (constraint: "'Hello, ' + sym_3")

The dataflow analysis traces greeting back through name, body, and response to the requests.get call. The dependency chain is fully preserved even though no concrete HTTP call was made.

With LLMPlausibleResolver:

response  = <plausible Response object>
body      = {"user": {"name": "Alice", "email": "alice@example.com"}}
name      = "Alice"
greeting  = "Hello, Alice"

The LLM produces a plausible JSON response for the API call. response.json() returns a plausible dict. extract_name runs concretely on the plausible data. The final values are concrete and inspectable, at the cost of one LLM call per unresolved external.

Dataflow Analysis

See also: Dataflow Design

The dataflow module (interpreter/dataflow.py) performs iterative intraprocedural analysis over the CFG in five stages:

1. Collect definitions: identify every point where a variable or register is assigned
2. Reaching definitions: GEN/KILL worklist fixpoint iteration over the CFG
3. Def-use chains: link each use to the definition(s) that reach it
4. Raw dependency graph: trace through register chains to discover direct named-variable-to-named-variable dependencies
5. Transitive closure: propagate indirect dependencies to produce the full dependency graph

The analysis is forward, may-approximate (over-approximate), and intraprocedural (single function/module scope). It covers all value-producing opcodes including the byte-addressed memory region operations (ALLOC_REGION, LOAD_REGION, WRITE_REGION), so COBOL programs get full dataflow tracking.

Reaching Definitions

Standard GEN/KILL worklist iteration over the dataflow equations:

reach_in(B)  = ∪ { reach_out(P) | P ∈ predecessors(B) }
reach_out(B) = GEN(B) ∪ (reach_in(B) − KILL(B))

The lattice is the power set of all definitions (finite), so convergence is guaranteed. A safety cap of 1,000 iterations prevents runaway on pathological CFGs.

The Register Chain Problem

The interesting part is translating from register-level def-use chains to human-readable variable dependencies. The IR uses temporary registers (%0, %1, …) for all intermediate values. A statement like y = x + 1 becomes:

%0 = LOAD_VAR x
%1 = CONST 1
%2 = BINOP +, %0, %1
     STORE_VAR y, %2

The raw def-use chain says “y depends on %2”. But a human wants to know “y depends on x”. The dependency graph builder traces through the register chain: %2 comes from BINOP on %0 and %1; %0 comes from LOAD_VAR x; %1 is a constant. Therefore y depends on x. Transitive closure extends this across multi-step computations.

Worked Example: Diamond Dependencies

Consider this program with diamond dependencies, function calls, and multi-operand expressions:

a = 1
b = 2
c = a + b
d = a * b
e = c + d
f = e - a

def square(x):
    return x * x

g = square(c)
h = g + f
total = h + e + b

c and d both depend on a and b (the diamond). g depends on c through the function call. total depends on three variables directly. The IR for just the main body (omitting the function) looks like:

%0  = const 1           → a = 1
%1  = const 2           → b = 2
%2  = load_var a
%3  = load_var b
%4  = binop + %2 %3     → c = a + b
%5  = load_var a
%6  = load_var b
%7  = binop * %5 %6     → d = a * b
%8  = load_var c
%9  = load_var d
%10 = binop + %8 %9     → e = c + d
%11 = load_var e
%12 = load_var a
%13 = binop - %11 %12   → f = e - a
%14 = load_var c
%15 = call_function square %14  → g = square(c)
%16 = load_var g
%17 = load_var f
%18 = binop + %16 %17   → h = g + f
%19 = load_var h
%20 = load_var e
%21 = load_var b
%22 = binop + %19 %20   → (partial)
%23 = binop + %22 %21   → total = h + e + b

The dependency graph builder traces through the register chains. For example, c depends on %4 (a BINOP), which reads %2 (from LOAD_VAR a) and %3 (from LOAD_VAR b), so c → {a, b}. Applying this recursively across all variables:

c → {a, b}, d → {a, b}, e → {c, d}, f → {e, a}, g → {c} (through the function call), h → {g, f}, total → {h, e, b}.

The direct dependency graph:

flowchart BT
    a("a"):::source
    b("b"):::source
    c("c"):::mid
    d("d"):::mid
    e("e"):::mid
    f("f"):::mid
    g("g<br/><i>square(c)</i>"):::mid
    h("h"):::mid
    total("total"):::sink

    a --> c
    b --> c
    a --> d
    b --> d
    c --> e
    d --> e
    a --> f
    e --> f
    c --> g
    f --> h
    g --> h
    b --> total
    e --> total
    h --> total

    classDef source fill:#e8f4fd,stroke:#4a90d9,stroke-width:2px,color:#1a3a5c
    classDef mid fill:#fff3e0,stroke:#e8a735,stroke-width:2px,color:#5c3a0a
    classDef sink fill:#e8f5e9,stroke:#2e7d32,stroke-width:3px,color:#1a3a1a

total directly depends on h, e, and b. The transitive closure adds a, c, d, f, and g, giving total → {a, b, c, d, e, f, g, h}. This means a change to any of these variables could affect total.

Branching and Multiple Reaching Definitions

On a diamond CFG (if/else), reaching definitions produce multiple reaching defs for the same variable at the merge point:

entry:    x = 10        → reach_out = {x@entry}
if_true:  x = 20        → reach_out = {x@if_true}
if_false: y = 30        → reach_out = {x@entry, y@if_false}
merge:    use(x)        → reach_in = {x@entry, x@if_true, y@if_false}

At the merge block, x has two reaching definitions (from entry and if_true). This correctly models the fact that the value of x at the merge point depends on which branch was taken. The def-use chain links the use of x in merge to both definitions.

Decoupling

The dataflow module has no dependencies on the VM, frontends, or backends. It’s a pure analysis pass over the CFG, decoupled from the imperative shell (parsing, I/O, LLM calls). Its input is a CFG object; its output is a DataflowResult containing definitions, block facts, def-use chains, and both raw and transitive dependency graphs.

Type Inference

See also: Type System Design

The type inference module (interpreter/type_inference.py) is a static analysis pass that runs after lowering but before VM execution. It walks the IR instructions in a fixpoint loop — repeating until no new types are discovered — and produces an immutable TypeEnvironment mapping registers and variables to canonical types. The VM then uses this environment for type-aware coercion at write time.

Type Representation: The TypeExpr ADT

Types are represented as an algebraic data type (TypeExpr) with nine variants:

ScalarType(name)                          # Int, String, Bool, MyClass
EnumType(name)                            # Color, Direction (enum declarations)
AnnotationType(name)                      # @Override, @Deprecated (annotation types)
StructPatternType(name)                   # Point { x, y } (struct pattern matching)
ParameterizedType(constructor, arguments) # Array[Int], Map[String, Int], Pointer[Pointer[Float]]
FunctionType(params, return_type)         # Fn(Int, String) -> Bool
UnionType(members)                        # Union[Int, String], Optional = Union[T, Null]
TypeVar(name, bound)                      # T, T: Number (bounded type variable)
UnknownType                               # sentinel for unresolved types

All TypeExpr values produce canonical string representations and — critically for the migration from the original string-based system — compare equal to those strings (ScalarType("Int") == "Int"). This made it possible to migrate the inference engine, type resolver, and coercion rules to structured types incrementally without breaking existing tests.

The Type Ontology

The base type hierarchy is a DAG (TypeGraph) with subtype queries and least-upper-bound (LUB) computation:

Any
├── Number
│   ├── Int
│   └── Float
├── String
├── Bool
├── Object
└── Array

The graph is pluggable: TypeGraph is constructed from a tuple of TypeNode values and can be extended without mutating the original. Subtype checks (is_subtype) and common-supertype queries (common_supertype) traverse the DAG via BFS. At runtime the graph is extended with user-defined class types, interface/trait nodes, and parameterized type rules.

Parameterized types. ParameterizedType values carry subtype checking through their arguments. Array[Int] is a subtype of Array[Number] because Int is a subtype of Number (covariant by default). A raw constructor (Array) is a supertype of any parameterised variant (Array[Int]).

Union types. UnionType members are flattened (nested unions merge), deduplicated, and singleton-eliminated (Union[Int] simplifies to Int). Optional is sugar for Union[T, Null]. A union is a subtype of a parent if all members are subtypes; a child is a subtype of a union parent if it is a subtype of at least one member.

Function types. FunctionType follows standard variance: parameters are contravariant (a function accepting Number is a subtype of one requiring Int), return types are covariant (returning Int is a subtype of returning Number).

Type aliases. A type_aliases registry maps alias names to TypeExpr targets. Resolution is transitive with cycle protection: IntPtr → Pointer[Int], NestedPtr → Pointer[IntPtr] → Pointer[Pointer[Int]].

Interface and trait typing. TypeNode values carry a kind field ("class" or "interface"). TypeGraph.extend_with_interfaces() adds interface nodes and wires implementing classes to them, so is_subtype(MyClass, Serializable) works when MyClass implements Serializable.

Variance annotations. A per-constructor variance registry maps constructors to per-argument variance (COVARIANT, CONTRAVARIANT, or INVARIANT). For example, MutableList can be marked invariant so that MutableList[Int] is not a subtype of MutableList[Number]. Unregistered constructors default to covariant.

Bounded type variables. TypeVar("T", bound=ScalarType("Number")) represents a generic parameter constrained to Number subtypes. Array[Int] is a subtype of Array[T: Number] because Int satisfies the bound.

Two Sources of Type Information

Type information enters the system through two paths:

1. Frontend type extraction (12 statically-typed languages). During lowering, each frontend extracts type annotations from the tree-sitter AST and normalises them to canonical types via a per-language type map. Simple types are straightforward: Java’s int → Int, Rust’s f64 → Float, Go’s string → String. Generic types are extracted structurally: a shared extract_normalized_type() function walks tree-sitter’s generic_type / generic_name / user_type nodes recursively, decomposes each component through the language’s type map, and emits bracket notation (List[Int], Map[String, Array[Float]]). C pointer types use a depth-counting approach: int **p becomes Pointer[Pointer[Int]]. All extracted types are parsed into TypeExpr objects and seeded into a TypeEnvironmentBuilder that the inference pass merges before its walk. Dynamically-typed languages (JavaScript, Ruby, Lua) skip this step — they have no annotations to extract.

2. Inference from IR structure. The inference pass itself infers types from the IR opcodes, covering both dynamically-typed languages (where all types come from inference) and filling gaps in statically-typed code (e.g., inferring the type of an expression result).

The Inference Algorithm

The inference walk runs to fixpoint over the flat IR. A dispatch table maps opcodes to handler functions (control flow, pointer, region, and continuation instructions with no typeable results are skipped). Each handler is a pure function that reads from and writes to an _InferenceContext — a mutable bundle of maps storing TypeExpr values:

• register_types: %0 → ScalarType("Int"), %3 → ScalarType("Bool"), …
• var_types: x → ScalarType("Int"), items → ParameterizedType("Array", [ScalarType("String")]), …
• func_return_types: factorial → ScalarType("Int"), …
• func_param_types: factorial → [("n", ScalarType("Int"))], …
• tuple_element_types: %5 → {0: ScalarType("Int"), 1: ScalarType("String")}, …

The key inference rules:

The RETURN backfill deserves mention: when the pass encounters a RETURN instruction inside a function, it records the return expression’s type in func_return_types. This means callers later in the IR can resolve the function’s return type even without an explicit annotation. The fixpoint loop extends this to forward references: when function A calls function B defined later in the IR, the first pass learns B’s return type from its RETURN, and the second pass propagates it to A’s call site. Chains of arbitrary depth (A → B → C) resolve correctly.

Type-Aware Coercion in the VM

The inference pass produces a frozen TypeEnvironment (backed by MappingProxyType for immutability). Since all VM values are TypedValue objects carrying their type alongside their value, coercion operates at two layers (described in more detail in the Two-Layer Type Coercion section above):

Layer 1 (Pre-operation): Pluggable BinopCoercionStrategy and UnopCoercionStrategy coerce operands before evaluation. Language-specific strategies (e.g., JavaBinopCoercion for String + int auto-stringification) override the defaults.

Layer 2 (Write-time): The TypeConversionRules interface coerces values when storing into typed registers. The default rules (DefaultTypeConversionRules) handle:

• Widening: Int → Float (lossless promotion)
• Narrowing: Float → Int (truncate toward zero, matching C/Java/COBOL semantics)
• Bool promotion: Bool → Int
• Arithmetic result types: Int ÷ Int → Int (floor division), Int + Float → Float
• Comparison results: any comparison → Bool

This two-layer coercion means the VM produces correct typed results for cross-language programs. A Go program that declares var x int = 7 / 2 gets 3 (integer division), not 3.5. A COBOL program with PIC 9(4) fields truncates float assignments. The type system makes this automatic rather than requiring per-language special cases in the VM.

Self/This Typing

Inside class definitions, the inference pass recognises self, this, and $this parameter names and assigns them the enclosing class type. This enables method return type resolution: when self.method() is called, the pass knows the receiver’s class and can look up the method’s return type in the class-scoped method type map.

Interface-Aware Inference

When a variable is typed as an interface (Animal animal = ...) and a method is called on it (animal.speak()), the inference pass needs to resolve the return type without knowing the concrete class. The solution is a chain walk: when class method lookup fails, the pass walks the interface_implementations map to find the interface that the variable’s type implements, then looks up the method’s return type from the interface’s method definitions.

Five frontends (Java, C#, TypeScript, Kotlin, Go) seed interface_implementations during lowering. Interfaces are lowered as CLASS blocks with method definitions, so their return types are available in the function registry.

Method Signatures

Class methods are stored in a method_signatures dictionary keyed by ScalarType, with a FunctionKind enum (UNBOUND, INSTANCE, STATIC) distinguishing method types. This class-scoped storage eliminates method name collisions — the same method name in different classes no longer overwrites a single flat entry — and supports method overload accumulation.

Design Properties

Pure function. infer_types() takes a list of IR instructions and a TypeResolver, returns a TypeEnvironment. No mutation of the input instructions. No side effects.

Fixpoint convergence. The pass repeats until no new types are discovered, resolving forward references across function boundaries. Convergence is measured by the combined size of register_types and func_return_types. Programs without forward references converge in one pass (no performance penalty). Each handler’s “skip if already known” guards prevent clobbering types from earlier passes while allowing unfilled gaps to be resolved on subsequent passes.

Pluggable ontology. The TypeGraph, TypeConversionRules, and TypeResolver are all injected. A different language family (e.g., one with unsigned integers or decimal types) can supply its own rules without changing the inference engine.

Structured types end-to-end. The entire type pipeline — from frontend extraction through inference, coercion, and environment output — operates on TypeExpr objects exclusively. The str | TypeExpr union that existed during the migration has been fully removed: all seed sites, all 15 frontends, and all downstream consumers (inference context, type resolver, conversion rules) work with the structured representation directly. There are no string serialization boundaries.

Cross-Language Type Inference in Practice

See also: IR Lowering Gaps

The type inference engine described above is language-agnostic: it operates on IR instructions without knowing which frontend produced them. But making it work correctly across 15 languages required solving language-specific lowering gaps — places where idiomatic code in one language produced IR that the inference pass couldn’t reason about.

The End-to-End Flow

The full pipeline from source to typed environment looks like this:

%%{ init: { "flowchart": { "curve": "stepBefore" } } }%%
flowchart LR
    subgraph Frontend ["Frontend (per-language)"]
        SRC("📄 Source Code"):::input --> PARSE("🌳 tree-sitter Parse"):::step
        PARSE --> LOWER("⬇️ Lower to IR"):::step
        LOWER --> SEED("🌱 Seed Type<br/>Environment Builder"):::step
    end
    subgraph Inference ["Type Inference (language-agnostic)"]
        SEED --> MERGE("🔗 Merge Seeds"):::infer
        MERGE --> WALK("🔄 Fixpoint Loop<br/><i>over IR</i>"):::infer
        WALK --> ENV("❄️ Frozen<br/>TypeEnvironment"):::output
    end
    ENV --> VM("⚙️ VM<br/><i>type-aware coercion</i>"):::engine

    classDef input fill:#e8f4fd,stroke:#4a90d9,stroke-width:2px,color:#1a3a5c
    classDef step fill:#fff3e0,stroke:#e8a735,stroke-width:2px,color:#5c3a0a
    classDef infer fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#3a0a3a
    classDef output fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#1a3a1a
    classDef engine fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#1a3a1a

The critical contract: frontends must produce IR that the inference pass can consume. If a frontend drops a return value, the inference pass has nothing to propagate. If a field access is lowered as a variable load instead of a field load, field tracking breaks.

Field Type Tracking Across OOP Languages

Eight OOP languages (Python, Java, C#, C++, JavaScript, TypeScript, PHP, Scala) support field type tracking through this/self. The mechanism:

%%{ init: { "flowchart": { "curve": "stepBefore" } } }%%
flowchart TD
    STORE("STORE_FIELD %this 'age' %val<br/><i>%this typed as Dog, %val typed as Int</i>"):::ir
    FT("🏷️ field_types['Dog']['age'] = Int"):::infer
    LOAD("LOAD_FIELD %this 'age'<br/><i>%this typed as Dog</i>"):::ir
    RESULT("✅ %result typed as Int"):::output

    STORE --> FT --> LOAD --> RESULT

    classDef ir fill:#fff3e0,stroke:#e8a735,stroke-width:2px,color:#5c3a0a
    classDef infer fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#3a0a3a
    classDef output fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#1a3a1a

This only works if:

1. The self/this parameter register is typed as the enclosing class (handled by each frontend’s _emit_this_param / _emit_self_param)
2. this.field access is lowered as LOAD_FIELD, not LOAD_VAR

Return Backfill and Expression-Bodied Functions

Return backfill infers a function’s return type from its RETURN instructions:

%%{ init: { "flowchart": { "curve": "stepBefore" } } }%%
flowchart LR
    CONST("%0 = CONST 42<br/><i>typed as Int</i>"):::ir
    RET("RETURN %0"):::ir
    BF("🔄 Backfill<br/>func_return_types['f'] = Int"):::infer
    CALL("result = f()<br/>CALL_FUNCTION"):::ir
    TYPED("✅ %result typed as Int"):::output

    CONST --> RET --> BF --> CALL --> TYPED

    classDef ir fill:#fff3e0,stroke:#e8a735,stroke-width:2px,color:#5c3a0a
    classDef infer fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#3a0a3a
    classDef output fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#1a3a1a

This works for explicit return statements. But three languages have idioms where the return value is implicit:

• Scala expression-bodied functions: def f() = 42 (the body is the return value)
• Kotlin expression-bodied functions: fun f() = 42
• Ruby implicit return: the last expression in a method is the return value

In all three cases, the original frontend lowering discarded the expression value and unconditionally emitted a default nil return. The inference pass saw RETURN nil and could not backfill the actual type.

The Fix Pattern

The fix for all three languages followed the same principle: detect when a function body is a bare expression rather than a block of statements, and wire the expression’s register to the RETURN instruction.

For Scala, lower_function_def checks if body_node is a block type or a bare expression. If bare, it calls lower_expr and emits RETURN with the result:

# Before: def getAge(): Int = this.age
func_getAge:
  %0 = load_var this    # ← wrong: should be load_field
  %1 = load_var age     # ← body iterated as children
  %2 = const ()
  return %2             # ← default nil return

# After:
func_getAge:
  %0 = load_var this
  %1 = load_field %0 age   # ← field_expression lowered correctly
  return %1                 # ← expression value returned

For Ruby, a _lower_body_with_implicit_return helper identifies the last named child of the method body. If it’s an expression (not a statement like if, while, or return), it lowers it via lower_expr and returns its register:

# Before: def get_age; @age; end
func_get_age:
  %0 = load_var self
  %1 = load_field %0 age    # value loaded...
  %2 = const None
  return %2                  # ...but discarded

# After:
func_get_age:
  %0 = load_var self
  %1 = load_field %0 age
  return %1                  # implicit return wired

Cross-Language Type Inference Test Matrix

With all three gaps fixed, the integration test suite verifies type inference scenarios across all applicable languages:

Each cell is a parametrized pytest fixture — a failure in one language doesn’t mask failures in others.

Cross-Language Verification via Exercism

The broadest verification effort was the Exercism integration test suite. The idea: take Exercism’s canonical test cases (which define expected inputs and outputs for programming exercises), write equivalent solutions in all 15 languages, and verify that RedDragon’s pipeline produces the correct answer for every case in every language.

The 18 exercises span a range of constructs: modulo and boolean logic (leap), while loops (collatz-conjecture), accumulators (difference-of-squares), string operations (two-fer, hamming, reverse-string, rna-transcription), nested loops (isogram, pangram), multi-branch classification (bob), float arithmetic (space-age), and multi-pass validation (luhn). For each exercise, every canonical test case generates tests across three dimensions:

1. Lowering quality: does the IR contain any unsupported: SYMBOLIC? (15 tests per exercise)
2. Cross-language consistency: do all 15 languages produce structurally equivalent IR? (2 tests per exercise)
3. VM execution correctness: does the VM produce the expected output? (cases x languages tests)

The argument substitution mechanism deserves a mention: a build_program() helper finds the answer = f(default_arg) line in each solution and substitutes new arguments for each canonical test case. This works across languages with different assignment syntaxes (=, :=, : type =) via regex.

The Exercism suite surfaced more bugs than any other test approach. Each exercise exposed new gaps: Ruby’s parenthesized_statements vs Python’s parenthesized_expression, Rust’s expression-position loops, Pascal’s single-quote string escaping, PHP’s . concatenation operator. Every gap found was a bug fixed.

The Numbers

Conclusion

RedDragon started as a question: “Can I build a single system that analyses code in any language?” It evolved into a compiler pipeline with 15 deterministic frontends, a COBOL frontend via ProLeap, LLM-assisted AST repair, a fully typed instruction set (33 per-opcode frozen dataclasses with Register, CodeLabel, BinopKind/UnopKind, and TypeExpr domain types replacing all raw strings), a structured type system (an algebraic TypeExpr ADT with generics, unions, function types, enums, annotation types, struct patterns, tuples, type aliases, interface/trait typing, variance annotations, and bounded type variables), static type inference with fixpoint convergence, interface-aware chain walk, and structural generic extraction across 12 statically-typed languages, a deterministic VM with class hierarchy support (inherited method dispatch via linearized parent chains across 10 OOP languages), TypedValue-based runtime type propagation with two-layer coercion, type-aware overload resolution, a symbol table with cross-class field resolution and implicit-this support, cross-language slicing, rest pattern destructuring, structural pattern matching via a shared Pattern ADT, byte-addressed memory regions and named continuations, and cross-language verification.

None of the individual components are novel. TAC IR, dispatch tables, worklist dataflow, and forward type inference are all textbook techniques. The value, if any, is in applying them together to a practical multi-language analysis tool.

References

Design documents and detailed specs from the RedDragon repository:

• IR Reference — Full specification of all 33 opcodes, per-opcode typed instruction classes, and lowering conventions
• Frontend Design — Architecture of the frontend subsystem: dispatch tables, AST repair, LLM frontends
• Per-Language Frontend Docs — Exhaustive per-file documentation for all 15 language frontends and the base frontend
• VM Design — VM internals: state model, opcode dispatch, symbolic propagation, closures, class hierarchy
• Dataflow Design — Reaching definitions, def-use chains, and dependency graph construction
• Type System Design — Type ontology, inference algorithm, coercion rules, and cross-language type extraction
• Architectural Decision Records — Chronological log of key design decisions (ADR-001 through ADR-121)
• IR Lowering Gaps — Tracking document for cross-language type inference lowering gaps
• Project Philosophy — Design principles and engineering values
• Contributing Guide — How to contribute to the project

This post has not been written or edited by AI.

This post has not been written or edited by AI.

Building a simple Virtual Machine

One of my favourite exercises to do when learning a new language is to build something which exercises non-trivial capabilities of the language like pattern matching, flexibility of data structures, or exposes the brevity of expressing ideas in the langauge. Building a simple virtual machine forces one to reckon with ideas like expression trees, recursive traversals, term rewriting, etc.

I’ve also been reading about symbolic execution as a way to perform dataflow analysis recently as well. As an added challenge, I chose to enhance the concrete interpretation of a program with symbolic execution capabilities.

Foundational Operations from the ground-up

We need a dictionary implementation. SWI-Prolog has the dictionaries, but since we are building everything from scratch, we will write a very naive implementation using only lists. Granted, there are some semantics of a dictionary that can be violated for now - for example, you can start off with duplicate keys, but let’s assume the happy path.

get2(_,[],empty).
get2(K, [(-(K,VX))|_],VX) :- !.
get2(K, [_|T],R) :- get2(K,T,R).

put2_(-(K,V),[],Replaced,R) :- Replaced->R=[];R=[-(K,V)].
put2_(-(K,V),[-(K,_)|T],_,[-(K,V)|RX]) :- put2_(-(K,V),T,true,RX).
put2_(-(K,V),[H|T],Replaced,[H|RX]) :- put2_(-(K,V),T,Replaced,RX).

put2(-(K,V),Map,R) :- put2_(-(K,V),Map,false,R).

To represent entries in a dictionary, we use the K-V compound term, which is basically syntactic sugar for -(K,V). These entries live inside a list. Both get2 and put2 behave in predictable ways, except when the dictionary has duplicate keys. In that case:

• get2(K,V) returns the value of the first matching key.
• put2(-(K,V),InputMap,OutputMap) modifies all matching keys with the value V.

In our current implementation, we will not worry about duplicate entries yet.

We will also need push/pop operations on stacks. This is very simple. Note that the top of the stack is always the leftmost element.

push_(V,Stack,UpdatedStack) :- UpdatedStack=[V|Stack].
pop_([],empty,[]).
pop_([H|Rest],H,Rest).

Logging

We will be logging quite a bit inside the rules. Thus it is important to have a structured way of logging different levels, like DEBUG, INFO, WARNING, etc. This is what a basic logging setup looks like:

log_with_level(LogLevel,FormatString,Args) :- format(string(Message),FormatString,Args),format('[~w]: ~w~n',[LogLevel,Message]).

debug(Message) :- log_with_level('DEBUG',Message,[]).
debug(FormatString,Args) :- log_with_level('DEBUG',FormatString,Args).

info(Message) :- log_with_level('INFO',Message,[]).
info(FormatString,Args) :- log_with_level('INFO',FormatString,Args).

warning(Message) :- log_with_level('WARN',Message,[]).
warning(FormatString,Args) :- log_with_level('WARN',FormatString,Args).

error(Message) :- log_with_level('ERROR',Message,[]).
error(FormatString,Args) :- log_with_level('ERROR',FormatString,Args).

dont_log(_).
dont_log(_,_).

Minimal instruction set

The minimal instruction is comprised of the following:

• mov(reg,reg|constant)
• cmp(reg,reg|constant)
• label(name)
• j(label)
• jz(label|address)
• jnz(label|address)
• push(reg|constant)
• pop(reg)
• call(label)
• ret
• hlt
• term(string)
• nop
• inc(reg)
• dec(reg)
• mul(reg,reg|constant)
• term(string)

Registers, Flags, and other Data Structures

For convenience, I chose to not have a fixed number of registers for convenience; thus, you can use any symbol as a register. In this respect, we will be treating registers more akin to conventional variables.

There will be one special register called the Instruction Pointer (IP). This will point to the next instruction to be executed. Jump instructions like j, jnz, and jz can can modify the IP to change the flow of the program.

The other useful data structure will be the stack, which is operated by push, pop, call, and ret (the last two use it to keep track of the stack when entering and leaving procedures).

There will be one flag called the Zero Flag. This should probably be better named to Equals Flag, because it is set to zero if the two sides of a cmp are equal, otherwise -1/+1 depending upon their relative ordering.

Data can be of two types:

• Concrete data, like numbers, which would be represented like const(5)
• Symbolic data, which stand in for concrete data, and are used for symbolic execuction, which we’ll introduce in Symbolic Execution and World Splits. These are represented as sym(x), sym(abcd), etc.

Memory Model

For the purposes of this simple VM, I chose not to have any memory. I may add it later, and then I will update this post accordingly.

Execution Model

The execution model is simple and similar to what we’d expect a very simple single-threaded VM to behave. Every instruction is sequentially mapped to a specific memory address (simple incrementing integers for our purposes). The Instruction Pointer starts at 0. At every instruction, something can happen. Actions include:

• Moving data between registers
• Loading constants into registers
• Incrementing / Decrementing registers
• Push / pop values to / from the stack
• Unconditional / Conditional jumps to another address
• Compare registers to other registers or constants
• Halt (effectively exit the program)
• Declare a label
• Call and return from a procedure (defined as a label)

Jumps work by modifying the value of the Instruction Pointer to the destination address. Procedure calls work similarly, but with an added side effect: the address of the instruction after the call is pushed onto the stack: when a ret is encountered, the topmost value is popped off the stack and is assigned back to the Instruction Pointer. This simulates the return from the procedure.

Building the navigation maps

There are a couple of mappings we need to build to be able to jump to arbitrary locations because of changes to the IP.

• Mapping labels to memory addresses
• Mapping memory addresses to instructions

These mappings are done in the following code:

instruction_pointer_map([],IPMap,_,IPMap).
instruction_pointer_map([Instr|T],IPMap,IPCounter,FinalIPMap) :- put2(-(IPCounter,Instr),IPMap,UpdatedIPMap),
                                                                 plusOne(IPCounter,UpdatedIPCounter),
                                                                 instruction_pointer_map(T,UpdatedIPMap,UpdatedIPCounter,FinalIPMap).
label_map([],LabelMap,_,LabelMap).
label_map([label(Label)|T],LabelMap,IPCounter,FinalLabelMap) :- put2(-(label(Label),IPCounter),LabelMap,UpdatedLabelMap),
                                                                 plusOne(IPCounter,UpdatedIPCounter),
                                                                 label_map(T,UpdatedLabelMap,UpdatedIPCounter,FinalLabelMap),
                                                                 !.
label_map([_|T],LabelMap,IPCounter,FinalLabelMap) :- plusOne(IPCounter,UpdatedIPCounter),
                                                     label_map(T,LabelMap,UpdatedIPCounter,FinalLabelMap).

The label_map predicate simply step through the full list of instructions, adding a label mapping to the current address (incremented each time through plusOne) when it encounters a label fact.

The instruction_map predicate simply assigns every instruction that it finds to an incrementing counter.

Symbolic Execution and World Splits

Symbolic execution is a technique used to determine the provenance of data in a piece of code. Assume, you have a very simplified code segment, like so:

Code=[
    mvc(reg(hl),const(10)), % load 10 into register HL
    mvc(reg(bc),const(5)),  % load 5 into register BC
    inc(reg(hl)),           % increment HL by one
    mul(reg(hl),reg(bc))    % multiply contents of HL with that of BC, store the result in HL
].

Now, suppose you wished to determine what sort of data transformations were taking place in this code. You might want to do this for different reasons:

• Determine if there are any optimisations that can be made, eg: an addition of zero can be eliminated, since it does not change the answer.
• Understand the data transformation for reverse engineering the business logic of this code

Now, you can run this piece of code on concrete numbers and generate lots of test cases for different values in hl, bc, etc. However, as a human, you may be able to induce a generic rule which explains the behaviour of this piece of code, which is:

hl=(hl+1)*bc

To deduce this rule, note that you didn’t use a concrete number, you used symbols like hl and bc to represent the values that these registers could store. Symbolic execution does exactly this: instead of storing concrete numbers in registers, we store symbols. When we “execute” the program, all operations which modify these symbols essentially store the log of operations on these symbols. So for example:

Code=[
mvc(reg(hl),sym(a)), % load symbol a into register HL
mvc(reg(bc),sym(b)),  % load symbol b into register BC
inc(reg(hl)),           % increment HL by one, HL now holds inc(sym(a))
mul(reg(hl),reg(bc))    %  HL now holds mul(inc(sym(a)),sym(b))
].

Thus at the end hl’s contents are mul(inc(sym(a)),sym(b)), which is interpreted as hl=(hl+1)*bc.

Symbolic execution is a powerful technique for program analysis. There is however one wrinkle we need to take care of when building a symbolic interpreter: branching.

Consider the instruction jz(label(some_label)). During concrete execution, we can look at the value of the Zero Flag, and then determine whether we want to jump to some_label or continue with the normal execution flow. However, the Zero Flag is set based on comparison between two concrete values: what if those values are symbols? You cannot meaningfully compare sym(a) and sym(b) numerically: they represent a range of values.

So, then the question becomes: which path do we take?

The image below is an example of the sort of situation you might encounter at a branch point.

The answer is that we take both paths. Effectively, we split our execution world into two branches: one which makes the jump, and the other one which contains normal execution. These two branches then continue on as individual threads to completion. Of course, if these branches encounter more conditional jump instructions, more sub-worlds split out of these as well, and so on.

Symbolic execution thus explores all possibilities of a program.

One issue is that this can easily result in a combinatorial explosion of paths, as each binary branch doubles the number of effective worlds. Symbolic execution engines tackle this in various ways. However, for our simple VM, we will simply keep splitting our world into new branches whenever we encounter conditional jumps.

Arithmetic operations

plusOne(sym(X),sym(inc(sym(X)))).
plusOne(const(X),const(PlusOne)) :- PlusOne is X+1.

minusOne(sym(X),sym(dec(sym(X)))).
minusOne(const(X),const(MinusOne)) :- MinusOne is X-1.

product(const(LHS),const(RHS),const(Product)) :- Product is LHS*RHS.
product(sym(LHS),sym(RHS),sym(product(sym(LHS),sym(RHS)))).
product(sym(LHS),const(RHS),sym(product(sym(LHS),const(RHS)))).
product(const(LHS),sym(RHS),sym(product(const(LHS),sym(RHS)))).

The predicate definitions take into account meaningful combinations of constants and symbols. As a rule of thumb, any expression containing even one symbol cannot be simplified (save degenerate cases like adding / subtracting 0, multiplying by 1 or 0, subtracting an expression from itself, etc., but we leave those aside for now for simplicity). Thus the only arithmetic simplification we do is when everything in an expression is a constant. For all the others, it creates a new compound term which reflects the operation being performed, which will ultimately be inspected at the end of a run as part of the value of a register.

Comparison

Comparison also works similar to arithmetic operations, in that actual comparison is usually only performed when both sides are constants. The special case is that if both sides are symbolic expressions with the same structure, that also counts for equality. Otherwise a new compound term logging the comparison operator (wrapped in a symbol itself) is returned.

equate(LHS,LHS,const(0)).
equate(sym(LHS),sym(RHS),sym(cmp(sym(LHS)),sym(RHS))).
equate(sym(LHS),const(RHS),sym(cmp(sym(LHS)),const(RHS))).
equate(const(LHS),sym(RHS),sym(cmp(const(LHS)),sym(RHS))).
equate(const(LHS),const(RHS),const(1)) :- LHS < RHS.
equate(const(LHS),const(RHS),const(-1)) :- LHS > RHS.

Virtual Machine state

The virtual machine state must reflect the exact configuration of registers, flags, stack, etc. These are represented as:

vmState(IP,Stack,CallStack,Registers,flags(zero(v1),hlt(v2),branch(v3))

• IP: Instruction Pointer, represented as a const()
• Stack: The program writer’s stack
• CallStack: We need a stack to store return addresses when performing procedure calls. However, using the program writer’s stack would mess with expectations of the programmer of what should be at the top of the stack. Therefore, a separate call stack is maintained.
• Registers: A map of the registers with their values
• Flags: The only flag that a user can set and access (indirectly) is the Zero Flag. However, there are two other (hidden flags) which indicate whether the program is about to halt or branch. The branch() compound term is useful to keep track of when to split worlds during symbolic execution. The hlt() compound term is to keep track of a halt condition (which can be an explicit HLT instruction, or the flow falling off the end of a program without a HLT instruction).

This vmState compound term is passed around everywhere and essentially is equivalent to a struct in C (SWI-Prolog has dedicated facilities for representing structures, but I’ve deliberately kept the code as implementation-neutral as possible).

Accessing data inside this structure is very easy, thanks to unification and pattern matching; for example, if we wished to only extract the value of the Zero Flag, and not care about the other values, we can simply write:

vmState(_,_,_,_,flags(zero(ZeroFlagValue),_,_)

Inner single world loop

For reference, this is the high level predicate flow that we will be referencing in the explanation of the predicates.

Before looking at how branches in symbolic execution are handled, it is instructive to understand how a single world, concrete execution flow works. The inner loop which evaluates a world, starts with:

• The original program, which simply a list of instructions
• The ExecutionMode is either symbolic or concrete. For the purposes of this explanation, let us assume that it is concrete.
• The StateIn is simply the initial VM state which is described in Virtual Machine state
• The vmMaps is a tuple of the IP Map and the label map, as described in Building the navigation maps
• The last variable represents the final output of evaluating this particular world. In particular, the TraceOut contains the program trace for this execution. Since we are only doing a concrete flow, there will be no ChildWorlds. The code below represents the part of the vm predicate which is pertinent to this discussion.

vm(Program,ExecutionMode,StateIn,vmMaps(IPMap,LabelMap),world(StateIn,TraceOut,ChildWorlds)) :-
                              exec_(vmMaps(IPMap,LabelMap),
                                  StateIn,[],
                                  traceOut(FinalTrace,VmStateOut),
                                  env(log(debug,info,warning,error),ExecutionMode)),
                              VmStateOut=vmState(FinalIP,FinalStack,FinalCallStack,FinalRegisters,FinalVmFlags),
                              minusOne(FinalIP,LastInstrIP),
                              TraceOut=traceOut(FinalTrace,vmState(LastInstrIP,FinalStack,FinalCallStack,FinalRegisters,FinalVmFlags)),
                              ...
                              .

The core interpretation is triggered by the exec_ predicate. The remaining lines involves taking the output VM state, adjusting its final IP value (which is one address beyond the last executed instruction) to point to the last executed instruction, and repackaging it to bind it to the output variable TraceOut.

Let’s look at the internal exec_ loop. The exec_ has two cases:

• The base case is if the hlt flag is set to true (hlt(true)). This indicates that a HLT instruction has been encountered in the execution of the previous instruction. At this point, the TraceOut variable is bound to the accumulated program trace and the current VM trace, and returned back to the vm_ predicate.

exec_(_,vmState(IP,Stack,CallStack,Registers,flags(ZeroFlag,hlt(true),BranchFlag)),
                  TraceAcc,
                  traceOut(TraceAcc,vmState(IP,Stack,CallStack,Registers,flags(ZeroFlag,hlt(true),BranchFlag))),
                  env(log(_,Info,_,_),_)) :- call(Info,'EXITING PROGRAM LOOP!!!').

• For the general case (when the last instruction was not HLT), we first get the instruction corresponding to the current IP value from the IPMap structure. This is then passed to exec_helper with all the associated context.

exec_(vmMaps(IPMap,LabelMap),vmState(IP,Stack,CallStack,Registers,VmFlags),TraceAcc,StateOut,Env) :-
                                                    get2(IP,IPMap,Instr),
                                                    exec_helper(Instr,vmMaps(IPMap,LabelMap),
                                                        vmState(IP,Stack,CallStack,Registers,VmFlags),TraceAcc,StateOut,Env).

The exec_helper predicate is where the interpretation actually happens. This also has two cases.

• The base case is when an empty instruction is encountered. This can happen if the program does not contain a HLT instruction, and execution falls off the end of the program. This is treated equivalent to an implicit HLT instruction. Thus, the TraceOut variable is bound to whatever context is already present. The only explicit modification is the hlt flag which is explicitly set to true.

exec_helper(empty,VmMaps,vmState(IP,Stack,CallStack,Registers,flags(ZeroFlag,_,BranchFlag)),
                    TraceAcc,
                    traceOut(TraceAcc,ExitState),
                    env(log(Debug,Info,Warn,Error),ExecutionMode)) :-
                            ExitState=vmState(IP,Stack,CallStack,Registers,flags(ZeroFlag,hlt(true),BranchFlag)),
                            call(Warn,'No other instruction found, but no HLT is present. Halting program.'),
                            exec_(VmMaps,ExitState,TraceAcc,traceOut(TraceAcc,ExitState),env(log(Debug,Info,Warn,Error),ExecutionMode)).

• The general case is the actual interpretation of the instruction. Before the interpret predicate is called, a NextIP variable is initialised to the current IP incremented by one, to indicate the next instruction that will be executed, assuming there are no jumps. This is so that a conditional jump can either return the same NextIP (i.e., no jump), or can return a different IP (indicating a jump).

The interpret predicate is then called, which has different cases, depending upon the instruction encountered. The various cases are described in Instruction Interpretation.

The shouldBranch() ternary operator’s true condition is only triggered during symbolic execution, so we’ll not worry about that for the moment. The negative condition is the concrete execution flow. This part is straightforward. It simply calls the exec_ predicate recursively with the updated IP.

This mutual recursive call between exec_ and exec_helper continues until a halt condition is reached.

exec_helper(...) :-
        ...,
        plusOne(IP,NextIP),
        interpret(Instr,VmMaps,vmState(NextIP,Stack,CallStack,Registers,VmFlags),vmState(UpdatedIP,UpdatedStack,UpdatedCallStack,UpdatedRegisters,UpdatedVmFlags),env(log(Debug,Info,Warning,Error),ExecutionMode)),
        (shouldBranch(UpdatedVmFlags)->
            (
                ...
            );
            (
                call(Debug,'Next IP is ~w',[UpdatedIP]),
                exec_(VmMaps,vmState(UpdatedIP,UpdatedStack,UpdatedCallStack,UpdatedRegisters,UpdatedVmFlags),TraceAcc,traceOut(RemainingTrace,vmState(FinalIP,FinalStack,FinalCallStack,FinalRegisters,FinalVmFlags)),env(log(Debug,Info,Warning,Error),ExecutionMode)),
                FinalTrace=[traceEntry(Instr,vmState(UpdatedIP,UpdatedStack,UpdatedCallStack,UpdatedRegisters,UpdatedVmFlags))|RemainingTrace]
            )
        ),
        !.

Some notes on Instruction Interpretation

Many of the cases for the interpret predicate are about retrieving the values of (one or two) registers, performing some manipulation on them (symbolic or arithmetic) and storing the result in the register, as in this example for the MUL instruction.

interpret(mul(reg(LHSRegister),reg(RHSRegister)),_,vmState(NextIP,Stack,CallStack,Registers,VmFlags),vmState(NextIP,Stack,CallStack,UpdatedRegisters,VmFlags),env(log(Debug,_,_,_),_)) :-
                get2(LHSRegister,Registers,LHSValue),
                get2(RHSRegister,Registers,RHSValue),
                call(Debug,'LHS is ~w,~w',[LHSRegister,LHSValue]),
                call(Debug,'RHS is ~w,~w',[RHSRegister,RHSValue]),
                product(LHSValue,RHSValue,Product),
                call(Debug,'And result is ~w',[Product]),
                update_reg(-(reg(LHSRegister),Product),Registers,UpdatedRegisters).

The two get2 calls retrieve the values of LHSRegister and RHSRegister. product calculates their (symbolic or arithmetic) product. update_reg updates the LHSRegister with the product.

The two instructions that modify the VM state differently are the JZ and JNZ instructions, which we have discussed depend upon whether the ExecutionMode is symbolic or concrete.

Symbolic Execution and World splitting: The outer loop

Let’s talk about how symbolic execution works. The symbolic execution mode is controlled by two variables:

• The ExecutionMode variable which can either be symbolic or concrete.
• The branch flag which is explicitly set to true by conditional jump instructions, only when the ExecutionMode is symbolic. To see this link, look at the two cases for the JZ (Jump if Zero) instruction.

interpret(jz(JumpIP),_,vmState(OldNextIP,Stack,CallStack,Registers,VmFlags),vmState(UpdatedIP,Stack,CallStack,Registers,UpdatedVmFlags),env(_,mode(symbolic))) :- interpret_symbolic_condition(OldNextIP,JumpIP,VmFlags,isZero,UpdatedVmFlags,UpdatedIP).
interpret(jz(JumpIP),_,vmState(OldNextIP,Stack,CallStack,Registers,VmFlags),vmState(UpdatedIP,Stack,CallStack,Registers,UpdatedVmFlags),env(_,mode(concrete))) :- interpret_condition(OldNextIP,JumpIP,VmFlags,isZero,UpdatedVmFlags,UpdatedIP).