Deterministic Core 3 — Box Pass, WriteCell, Solve Entry

Purpose: For each 3x3 box, detect digits 1–9 that appear in candidate masks of exactly one unsolved cell within that box, and assign them.

Assumptions:• Board base address in IX• Candidate masks stored per cell (2 bytes, little endian)• WriteCellValue handles propagation• Returns: Z=1 if no progress, Z=0 if at least one fill performed

HiddenSinglesBoxPass:
    LD   A,0
    LD   (ProgressFlag),A

    LD   D,0              ; box index 0–8
BoxLoop:
    PUSH DE
    CALL InitBoxPointer   ; HL = pointer to first cell in box D

    LD   E,1              ; digit = 1..9
DigitLoop:
    PUSH DE
    LD   B,0              ; match count
    LD   C,0              ; last matching cell offset

    PUSH HL
    LD   A,9
CellLoop:
    PUSH AF

    CALL LoadCandidateMask   ; BC = mask for cell
    CALL MaskContainsDigit   ; Z=0 if digit present
    JR   Z,NoMatch

    INC  B
    LD   C,L                 ; remember offset (low byte sufficient)

NoMatch:
    CALL NextBoxCell
    POP  AF
    DEC  A
    JR   NZ,CellLoop

    POP  HL

    LD   A,B
    CP   1
    JR   NZ,NextDigit

    ; exactly one match → write digit
    LD   L,C
    POP  DE                 ; restore digit in E
    PUSH DE
    LD   A,E
    CALL WriteCellValue
    LD   A,1
    LD   (ProgressFlag),A

NextDigit:
    POP  DE
    INC  E
    LD   A,E
    CP   10
    JR   NZ,DigitLoop

    POP  DE
    INC  D
    LD   A,D
    CP   9
    JR   NZ,BoxLoop

    LD   A,(ProgressFlag)
    OR   A
    RET

Purpose: Commit digit A (1–9) into current cell, clear its candidate mask, and propagate elimination to row, column, and box peers.

WriteCellValue:
    ; A = digit (1–9)
    PUSH AF

    CALL StoreSolvedDigit     ; write final value to board
    CALL ClearCellMask        ; zero candidate mask

    POP  AF
    PUSH AF
    CALL EliminateFromRow
    POP  AF
    PUSH AF
    CALL EliminateFromColumn
    POP  AF
    CALL EliminateFromBox

    RET

Purpose: Main deterministic entry point. Repeatedly apply naked singles and hidden singles (row/column/box) until no progress or contradiction.

Returns:• Z=1 → solved or no further deterministic progress• NZ → contradiction detected

SolveDeterministic:
MainLoop:
    LD   A,0
    LD   (ProgressFlag),A

    CALL DeterministicFillLoop   ; naked singles
    JR   NZ,Contradiction

    CALL HiddenSinglesRowPass
    JR   NZ,Contradiction

    CALL HiddenSinglesColumnPass
    JR   NZ,Contradiction

    CALL HiddenSinglesBoxPass
    JR   NZ,Contradiction

    LD   A,(ProgressFlag)
    OR   A
    JR   NZ,MainLoop

    XOR  A        ; Z=1
    RET

Contradiction:
    LD   A,1
    OR   A        ; NZ
    RET

This completes the structural deterministic engine: naked singles, hidden singles (row/column/box), write propagation, looping until fixpoint, and explicit contradiction signalling for integration with a future backtracking phase.