052. Flags handler refactor

Files to create/update

emulator/cpu/flags_handler.py
emulator/cpu/cpu.py

Symbols to create/update

FlagsHandler
CPU.flags
CPU.__post_init__

Why this step exists

The existing CPU helper covers only Zero and Negative. The next arithmetic instruction also needs Carry and Overflow, so status-bit access is collected in an object that mutates the CPU-owned p register. The existing CPU._update_zero_and_negative_flags stays intact for earlier instructions.

Complete example implementation

# emulator/cpu/flags_handler.py
from __future__ import annotations
from dataclasses import dataclass
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from emulator.cpu.cpu import CPU

CARRY_FLAG = 1 << 0
ZERO_FLAG = 1 << 1
ONE_FLAG = 1 << 5
OVERFLOW_FLAG = 1 << 6
NEGATIVE_FLAG = 1 << 7

@dataclass
class FlagsHandler:
    cpu: CPU

    def set_zero_flag(self, enabled: bool):
        if enabled:
            self.cpu.p |= ZERO_FLAG
        else:
            self.cpu.p &= ~ZERO_FLAG

    def set_negative_flag(self, enabled: bool):
        if enabled:
            self.cpu.p |= NEGATIVE_FLAG
        else:
            self.cpu.p &= ~NEGATIVE_FLAG

    def set_overflow_flag(self, enabled: bool):
        if enabled:
            self.cpu.p |= OVERFLOW_FLAG
        else:
            self.cpu.p &= ~OVERFLOW_FLAG

    def set_carry_flag(self, enabled: bool):
        if enabled:
            self.cpu.p |= CARRY_FLAG
        else:
            self.cpu.p &= ~CARRY_FLAG

    def set_one_flag(self, enabled: bool):
        if enabled:
            self.cpu.p |= ONE_FLAG
        else:
            self.cpu.p &= ~ONE_FLAG

    def get_zero_flag(self) -> bool:
        return bool(self.cpu.p & ZERO_FLAG)

    def get_negative_flag(self) -> bool:
        return bool(self.cpu.p & NEGATIVE_FLAG)

    def get_overflow_flag(self) -> bool:
        return bool(self.cpu.p & OVERFLOW_FLAG)

    def get_carry_flag(self) -> bool:
        return bool(self.cpu.p & CARRY_FLAG)

    def get_one_flag(self) -> bool:
        return bool(self.cpu.p & ONE_FLAG)

# emulator/cpu/cpu.py
from dataclasses import dataclass, field
from emulator.cpu.flags_handler import FlagsHandler

@dataclass
class CPU:
    bus: CpuBus
    flags: FlagsHandler = field(init=False)

    def __post_init__(self):
        self.flags = FlagsHandler(self)

    # Keep the existing registers, fetch/reset/step methods, and
    # _update_zero_and_negative_flags implementation unchanged.

Important invariants

• cpu.p remains the single processor-status value
• every setter changes only its own bit and supports both set and clear
• every getter returns a bool
• each CPU owns a handler whose cpu reference points back to that CPU
• the old Zero/Negative CPU helper remains callable

Common misconception

Do not give FlagsHandler a separate status byte or replace the old CPU helper; that would split state or break the instructions introduced in earlier tests.

Out of scope

• ADC, which first consumes these public helpers in test 053
• Break, interrupt-disable, and decimal helpers
• stack and interrupt behavior