BitGrid-Rust

BitGrid-Rust is a Rust-from-C systems-programming project.

It reimplements the core ideas from a C-based Hitori puzzle assignment as a Rust command-line engine while preserving the original project's low-level profile:

• compact board representation
• row-major storage
• bit-packed cell state
• deterministic puzzle logic
• graph validation
• recursive search
• CLI tooling
• tests
• documentation

This repository has completed R13 quality hardening after the R12 documentation and portfolio packaging pass. It has a Cargo project, compact Cell and row-major Board types, a strict numeric puzzle parser, state-aware solution parsing and writing, blackout/circle propagation, sandwich, doublet, and gate deductions, a deterministic rule loop, independent validation, clone-based recursive search, structured solver traces, solve, validate, and bench CLI commands, explicit solve --search and solve --logic-only modes, unit/integration tests, a small regression fixture corpus, architecture notes, C-to-Rust comparison notes, and AI-native phase closeouts.

---

Project Direction

BitGrid-Rust follows a deliberately scoped technical and workflow strategy:

Preserve the systems core; improve architecture, correctness, testing, tooling, and documentation through Rust and AI-native workflow control.

The project intentionally evolves through three maturity levels:

School Assignment Baseline
  -> MVP Standalone Rust CLI
  -> MVP+ Systems-Style Portfolio Project

The project is not primarily a web app, UI product, or generic puzzle game. Its purpose is to demonstrate:

• Rust systems-programming fundamentals
• C-to-Rust concept transfer
• compact data representation
• algorithmic problem solving
• graph traversal
• recursive search
• CLI tool design
• testing discipline
• AI-native workflow control

---

Why This Project Exists

The original C assignment focused on low-level programming concepts such as heap-allocated board data, row-major indexing, byte-level cell storage, bit masks, deterministic Hitori deductions, and memory cleanup.

BitGrid-Rust uses that assignment as the seed for a larger Rust learning and portfolio project.

The central engineering question is:

How can a C systems-style assignment be transferred into Rust while preserving the low-level representation ideas and gaining Rust's ownership model, module structure, test discipline, and tooling?

The central workflow claim is:

Codex is more than a coding agent. With the right workflow, context, and feedback loops, Codex can act as a tutor, implementer, reviewer, debugger, and documentation partner.

---

Current Status

Status: R13 Complete

At this stage, the repository contains project planning documents plus the MVP and MVP+ data, I/O, propagation, deterministic rule, validation, search, trace, benchmark, CLI, hardening, and documentation layers. The implementation exposes the planned module boundaries and implements compact cells, row-major boards, strict puzzle parsing, stable numeric puzzle writing, state-aware solution writing/parsing, legal blackout/circle state transitions, sandwich deductions, doublet deductions, connectivity-aware gate deductions, a repeated deterministic rule loop, independent validation, clone-based recursive search, structured explanation traces, command-line entry points, a benchmark runner that reports search-assisted solver statistics, and regression tests for parser, validation, CLI, benchmark, and search behavior.

The R12 review identified a final hardening phase before project closeout. R13 was completed as five small subphases:

• R13A - state-aware solution output and validation (complete)
• R13B - CLI --search and --logic-only solve modes (complete)
• R13C - gate deduction hardening against the C reference (complete)
• R13D - clearer solver status reporting (complete)
• R13E - final docs and closeout refresh (complete)

See docs/quality_hardening_plan.md for the practical R13 plan.

Current R13 behavior:

• cargo build compiles the package.
• cargo run -- solve tests/fixtures/valid_3x3.puz runs the search-assisted solver, validates the resulting board, and prints state-aware solution output.
• cargo run -- solve tests/fixtures/regression/search_required_2x2.puz --search explicitly runs search-assisted solving.
• cargo run -- solve tests/fixtures/regression/search_required_2x2.puz --logic-only runs deterministic-only solving and reports explicit solved, stalled, or contradiction status.
• cargo run -- solve tests/fixtures/regression/search_required_2x2.puz --search --explain prints deterministic and search trace events.
• cargo run -- validate tests/fixtures/regression/valid_stateful_solution.sol validates a state-aware solution file.
• cargo run -- bench tests/fixtures runs a small search-assisted benchmark over a puzzle directory and reports status, deductions, passes, guesses, depth, validation, and elapsed microseconds.
• cargo test runs unit tests for cells, boards, parser behavior, writer behavior, propagation behavior, deterministic rules including forced-white gate deduction, the fixed-point rule loop, validation behavior, clone-based search, structured traces, benchmark behavior, CLI smoke behavior, and focused regression cases.
• cargo fmt --check and cargo clippy are part of the closeout workflow.
• src/lib.rs wires the planned engine modules.
• src/main.rs stays thin and dispatches CLI commands to the library.
• src/cell.rs implements compact one-byte cells with bit masks.
• src/board.rs implements owned row-major board storage.
• src/parser.rs parses strict numeric .puz input and state-aware .sol solution input into Board.
• src/writer.rs formats boards back to stable numeric puzzle output and state-aware solution output.
• src/solver.rs implements blackout/circle propagation and contradiction reporting.
• src/rules.rs implements sandwich, doublet, and forced-white connectivity-aware gate deductions.
• src/validate.rs implements independent duplicate, adjacency, and connectivity checks.
• src/search.rs implements clone-based recursive backtracking search as a library feature.
• src/trace.rs implements structured trace events and deterministic trace formatting.
• src/bench.rs implements a small benchmark runner and stable text formatting for solver statistics.

Core planning documents:

• docs/architecture.md - implemented module boundaries, data flow, solver flow, and design tradeoffs
• docs/c_vs_rust_notes.md - final reflection on C control, Rust ownership, safety, testing, and portfolio positioning
• docs/phase_catalog.md - quick index of paired phases, status, commands, and closeouts
• docs/quality_hardening_plan.md - R13 post-review hardening plan
• docs/project_specs.md — project scope, maturity levels, architecture direction, phase catalog, and success criteria
• docs/c_to_rust_translation.md — mapping from original C concepts to Rust concepts
• AGENTS.md — public repo-level instructions for Codex / AI coding agents working in this repository
• TESTING.md — test layout, regression fixture intent, and verification workflow
• AI_native_builder_journal.md — visible evidence of the AI-native paired tutor/build workflow used to build this project

These files are the main review path for understanding what was built, how it maps from the original C assignment, and how the AI-native phase workflow was controlled.

---

AI-Native Builder Journal

This project is being built through an AI-native development workflow.

That means the project is not simply written by a single human developer in the traditional way, nor is it blindly generated by AI. It is built through a paired human-Codex workflow, with ChatGPT supporting planning, specification, prompt design, and review in selected phases.

The file AI_native_builder_journal.md is a first-class project artifact. It explains how the project is being built, how phase boundaries are handled, what role Codex plays, and how human review and architectural control remain part of the process.

The README explains what BitGrid-Rust is.

The AI-native builder journal explains how BitGrid-Rust is being built.

---

Integrated Workflow

BitGrid-Rust uses a paired tutor/build workflow:

learn concept -> apply concept -> review implementation -> document lesson

Each implementation phase is paired with a tutor phase:

R#-Tutor -> R#-Build

For example:

R1-Tutor: Newtype pattern, u8 bit masks, safe APIs
R1-Build: Implement Cell and Board

The goal is not only to produce Rust code. The goal is to make the learning path, C-to-Rust transfer, review process, and implementation decisions visible.

---

Planned MVP Features

The MVP should support:

• Rust project skeleton using Cargo
• Cell representation backed by compact u8 storage
• Board representation backed by row-major Vec<Cell>
• parser for puzzle files
• writer for solution files
• blackout and circle propagation
• sandwich deduction
• doublet deduction
• repeated deterministic solving loop
• board validator
• CLI command for solving puzzles
• CLI command for validating solutions
• unit tests for cell bit operations
• unit tests for board indexing
• parser and writer tests
• validator tests
• integration tests for sample puzzles
• README with setup, run commands, and current project status
• AI-native builder journal entries for paired phases

MVP commands:

cargo run -- solve puzzles/practice.puz
cargo run -- validate solutions/practice.sol
cargo test

---

Current MVP+ Features

The MVP+ should expand the Rust CLI tool into a stronger systems-style engine.

Implemented MVP+ capabilities include:

• modular rule engine
• gate/connectivity-aware deductions
• full board validation independent from solving
• recursive backtracking fallback
• contradiction detection
• solver trace / explanation mode
• benchmark command
• structured solver statistics
• improved error handling
• larger puzzle corpus
• stronger integration tests
• architecture and design-tradeoff documentation
• C-to-Rust comparison notes
• AI-native builder journal with paired phase closeouts

Implemented commands and closeout checks:

cargo run -- solve puzzles/practice.puz
cargo run -- solve puzzles/practice.puz --logic-only
cargo run -- solve puzzles/practice.puz --search
cargo run -- solve puzzles/practice.puz --explain
cargo run -- validate solutions/practice.sol
cargo run -- bench puzzles/
cargo test
cargo clippy
cargo fmt --check

The current solve command is search-assisted by default. Use --logic-only for deterministic-only solving, or --search to request search-assisted solving explicitly.

---

Core Hitori Rules

A Hitori puzzle presents a grid of numbers. The solver must determine which cells should be blacked out so that:

1. No row contains more than one visible occurrence of the same number.
2. No column contains more than one visible occurrence of the same number.
3. Blacked-out cells are not horizontally or vertically adjacent.
4. All non-blacked-out cells remain connected horizontally or vertically.

BitGrid-Rust should preserve these rules as the core domain model.

---

Architecture

The implementation keeps puzzle I/O, board representation, solving, validation, search, tracing, benchmarking, and CLI behavior separated. See docs/architecture.md for the fuller walkthrough.

Implemented module structure:

src/
├── main.rs
├── lib.rs
├── cell.rs
├── board.rs
├── parser.rs
├── writer.rs
├── solver.rs
├── rules.rs
├── validate.rs
├── search.rs
├── trace.rs
├── bench.rs
└── error.rs

Expected responsibilities:

• cell.rs: compact cell representation and bit operations
• board.rs: row-major board storage and safe access APIs
• parser.rs: puzzle file parsing
• writer.rs: solution output
• rules.rs: deduction rules
• solver.rs: solver loop and orchestration
• validate.rs: Hitori correctness checks
• search.rs: recursive backtracking fallback
• trace.rs: explanation logging
• bench.rs: benchmark runner
• error.rs: shared error types
• main.rs: thin CLI entrypoint
• lib.rs: library exports and module wiring

---

C-to-Rust Translation

The project should make the C-to-Rust transfer visible.

C Concept	Rust Translation
typedef unsigned char Cell	struct Cell(u8) newtype
Cell *solution row-major array	Vec<Cell> owned by Board
manual offset calculation	explicit row-major indexing helper
bit masks such as 0x80, 0x40, 0x1F	Rust constants and Cell methods
manual allocation/free	ownership, Vec, and automatic drop behavior
error codes / helper error functions	Result<T, BitGridError>
recursive C functions	Rust recursion with controlled mutation or cloning
Valgrind leak checking	ownership, cargo test, Clippy, optional Miri
ad hoc function organization	modules, testable APIs, documented boundaries

The Rust version should not hide the original systems-programming concerns behind unnecessary abstraction. It should preserve compact representation, bit masks, row-major indexing, and solver-state transitions as visible design choices.

---

Implementation Phases

The project is expected to be implemented in paired phases.

Initial context phases:

1. S0-Context — Preserve original C assignment context
2. S1-Comparison — Identify core C concepts to translate

MVP paired phases:

1. R0-Tutor — Rust project model, Cargo, modules, ownership basics
2. R0-Build — Create Rust repo skeleton
3. R1-Tutor — Newtype pattern, u8 bit masks, safe APIs
4. R1-Build — Implement Cell and Board
5. R2-Tutor — Result, error types, file I/O, parsing
6. R2-Build — Implement Parser and Writer
7. R3-Tutor — Borrowing and mutation patterns for solver state
8. R3-Build — Implement blackout/circle propagation
9. R4-Tutor — Rule organization with enums or traits
10. R4-Build — Implement sandwich and doublet deductions
11. R5-Tutor — Graph traversal and connectivity in Rust
12. R5-Build — Implement Validator and Connectivity
13. R6-Tutor — CLI basics and human-usable tool boundaries
14. R6-Build — Basic CLI and MVP README update

MVP+ paired phases:

1. R7-Tutor / R7-Build — Connectivity-aware gate deduction
2. R8-Tutor / R8-Build — Backtracking search
3. R9-Tutor / R9-Build — Explanation trace mode
4. R10-Tutor / R10-Build — Benchmark command and solver statistics
5. R11-Tutor / R11-Build — Expanded tests and regression corpus
6. R12-Tutor / R12-Build — Final docs and MVP+ packaging
7. R13-Tutor / R13-Build — Post-review quality hardening

Each phase should produce a reviewable increment and a short closeout note.

---

Development Principles

• Build one phase at a time.
• Use tutor-before-build sequencing.
• Keep implementation requests bounded.
• Do not ask Codex to build the whole project in one pass.
• Preserve the compact systems-style project identity.
• Prefer clear beginner-to-intermediate Rust over clever abstractions.
• Keep CLI code thin and library code testable.
• Keep validation independent from solver logic.
• Use deterministic solving before recursive search.
• Add or update tests when behavior changes.
• Run cargo test, cargo clippy, and cargo fmt --check as the project matures.
• Update documentation as the project evolves.
• Keep human ownership over direction, architecture, quality, and final responsibility.

---

Setup

The R13 engine is available now. The CLI includes search-assisted solve, deterministic-only solve --logic-only with explicit status reporting, explicit solve --search, state-aware validate, optional explanation output, and a search-assisted benchmark runner.

# install Rust if needed
rustup --version
cargo --version

# build
cargo build

# solve a numeric puzzle with search-assisted solving
cargo run -- solve tests/fixtures/valid_3x3.puz

# solve with deterministic rules only
cargo run -- solve tests/fixtures/regression/search_required_2x2.puz --logic-only

# solve with explicit search and explanation trace output
cargo run -- solve tests/fixtures/regression/search_required_2x2.puz --search --explain

# validate a state-aware solution file
cargo run -- validate tests/fixtures/regression/valid_stateful_solution.sol

# benchmark the fixture directory with search-assisted solving
cargo run -- bench tests/fixtures

# run tests
cargo test

The solve command currently prints search-assisted, line-oriented output:

Command: solve
Size: 3x3
Mode: search
Status: solved
Passes: 0
Guesses: 0
Max recursion depth: 0
Validation: passed
Solved: yes
Solution:
3 3
1 2 3
4 5 6
7 8 9

State-aware solution tokens use plain numbers for visible cells, oN for circled cells, and xN for black cells. For example:

3 3
x2 o1 2
o2 o3 4
x2 o5 6

With --explain, the command appends deterministic trace lines such as:

Trace:
rule sandwich -> circle at (0, 1) number 1
cell circle at (0, 1) number 1
deterministic pass 1 changed board

The bench command prints tab-separated, line-oriented statistics:

Puzzle	Size	Status	Deductions	Passes	Guesses	MaxDepth	Validation	TimeUs
valid_3x3.puz	3x3	solved	0	0	0	0	passed	123

Benchmark timing is a smoke metric for local comparison, not a rigorous performance claim. Exact elapsed values vary by machine, build profile, and system load.

---

Running Tests

The current test suite covers the implemented foundation: cell bit operations, board indexing, parser error paths, fixture parsing, numeric and state-aware writer formatting, blackout/circle propagation, sandwich deductions, doublet deductions, gate deduction, the deterministic rule loop, independent validation, clone-based search, structured traces, benchmark behavior, CLI smoke behavior, and focused regression fixtures.

Default command:

cargo test

Formatting and linting commands:

cargo fmt --check
cargo clippy

See TESTING.md for regression fixture organization and the verification workflow.

Optional later verification:

cargo miri test

---

Environment Variables

No environment variables are expected at the starting point.

BitGrid-Rust should remain a local deterministic CLI tool. Tests should not require paid API keys, network calls, or external services.

---

Project Non-Goals

BitGrid-Rust should not become:

• a web application
• a large visual puzzle game
• a generic AI chatbot
• a database-backed product app
• a mobile app
• a frontend-heavy portfolio project
• a puzzle collection with many unrelated games
• a one-shot AI-generated code dump

The goal is a finished, systems-style Rust portfolio project with visible C-to-Rust transfer and AI-native workflow evidence.

---

Final Portfolio Direction

When complete, BitGrid-Rust should demonstrate:

• Rust systems programming fundamentals
• C-to-Rust concept transfer
• compact data representation
• algorithmic problem solving
• graph traversal
• recursive search
• CLI tool design
• testing discipline
• benchmarking and solver statistics
• documentation discipline
• AI-native development workflow

The intended final framing is:

BitGrid-Rust is a Rust-from-C systems-style constraint-solving engine that evolves from a school-style Hitori assignment into a tested, documented, CLI-based MVP and then into an MVP+ project with graph validation, recursive search, solver tracing, benchmarking, and phase-based AI-native development evidence.