diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 0000000..6248a84
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,85 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Tests (Python 3.13)
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python 3.13
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+          cache: pip
+          cache-dependency-path: |
+            requirements.txt
+            pyproject.toml
+
+      - name: Upgrade pip and install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          # Install runtime deps (skip iqm-client which is hardware-only and not needed for tests)
+          pip install -r requirements.txt
+          # Install test dependencies
+          pip install pytest>=8.0 pytest-cov>=5.0
+
+      - name: Run tests with coverage
+        run: |
+          pytest \
+            --cov=. \
+            --cov-report=term-missing \
+            --cov-report=xml \
+            --cov-report=html \
+            --cov-fail-under=85 \
+            -v \
+            tests/
+
+      - name: Upload coverage to Codecov (optional)
+        if: success()
+        uses: codecov/codecov-action@v4
+        with:
+          files: ./coverage.xml
+          fail_ci_if_error: false
+          token: ${{ secrets.CODECOV_TOKEN }}
+          continue-on-error: true
+
+  smoke:
+    name: DiffQEC smoke test
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    needs: test
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python 3.13
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+          cache: pip
+          cache-dependency-path: |
+            requirements.txt
+            pyproject.toml
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+
+      - name: Run DiffQEC smoke test
+        run: |
+          python -m diffqec.smoke_test
diff --git a/conftest.py b/conftest.py
new file mode 100644
index 0000000..2f7f591
--- /dev/null
+++ b/conftest.py
@@ -0,0 +1,13 @@
+"""Pytest configuration: add the project root to sys.path.
+
+This lets test files import from the project modules (surface_code,
+extract_syndromes, internal_helpers, etc.) without requiring the project
+to be installed as a package.
+"""
+import sys
+from pathlib import Path
+
+# Add the project root to sys.path so tests can import project modules
+_PROJECT_ROOT = Path(__file__).resolve().parent
+if str(_PROJECT_ROOT) not in sys.path:
+    sys.path.insert(0, str(_PROJECT_ROOT))
diff --git a/pytest.ini b/pytest.ini
new file mode 100644
index 0000000..9eb2047
--- /dev/null
+++ b/pytest.ini
@@ -0,0 +1,44 @@
+[pytest]
+testpaths = tests
+python_files = test_*.py
+python_classes = Test*
+python_functions = test_*
+pythonpath = .
+addopts =
+    -ra
+    --strict-markers
+    --tb=short
+    --disable-warnings
+markers =
+    slow: marks tests as slow (deselect with -m 'not slow')
+    hardware: marks tests that require real quantum hardware (skipped in CI)
+filterwarnings =
+    ignore::DeprecationWarning:qiskit.*
+    ignore::DeprecationWarning:stim.*
+    ignore::DeprecationWarning:pymatching.*
+
+[coverage:run]
+source =
+    surface_code
+    extract_syndromes
+    internal_helpers
+    run_on_hardware
+    diffqec
+omit =
+    tests/*
+    iqm_utils/*
+    benchmarks/*
+    lumi/*
+    main.py
+    build_emerald_qubit_rotated.py
+
+[coverage:report]
+exclude_lines =
+    pragma: no cover
+    raise NotImplementedError
+    if __name__ == .__main__.:
+    def __repr__
+    \.\.\.
+precision = 1
+show_missing = true
+skip_covered = false
diff --git a/requirements.txt b/requirements.txt
index fcf7b70..1cf11e0 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -17,4 +17,7 @@ iqm-client==34.0.3
 
 # --- DiffQEC decoder (discrete diffusion model) ---
 torch>=2.0
-  
\ No newline at end of file
+
+# --- Test dependencies (CI) ---
+pytest>=8.0
+pytest-cov>=5.0
diff --git a/tests/__init__.py b/tests/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/test_pipeline.py b/tests/test_pipeline.py
new file mode 100644
index 0000000..b33be08
--- /dev/null
+++ b/tests/test_pipeline.py
@@ -0,0 +1,547 @@
+"""Tests for the base surface-code QEC pipeline (non-DiffQEC).
+
+Covers:
+- surface_code.py: make_stim_circuit, make_qiskit_circuit, stim_to_qiskit, get_circuit_info
+- extract_syndromes.py: extract_syndromes_manual, extract_syndromes
+- internal_helpers.py: get_qubit_lists, get_meas_order, counts_to_measurement_array
+- build_emerald_qubit_rotated.py: build_emerald_qubit_map
+- run_on_hardware.py: decode_hardware_results
+- main.py: run_simulation_test
+"""
+import math
+
+import numpy as np
+import pytest
+import stim
+
+from internal_helpers import (
+    counts_to_measurement_array,
+    get_meas_order,
+    get_qubit_lists,
+)
+from surface_code import (
+    DEFAULT_NOISE,
+    get_circuit_info,
+    make_qiskit_circuit,
+    make_stim_circuit,
+    stim_to_qiskit,
+)
+from extract_syndromes import extract_syndromes, extract_syndromes_manual
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+#  surface_code.py — make_stim_circuit
+# ─────────────────────────────────────────────────────────────────────────────
+
+class TestMakeStimCircuit:
+    def test_default_z_memory(self):
+        c = make_stim_circuit(distance=3, rounds=3)
+        assert isinstance(c, stim.Circuit)
+        assert c.num_qubits > 0
+        assert c.num_detectors > 0
+        assert c.num_observables >= 1
+
+    def test_x_memory(self):
+        c = make_stim_circuit(distance=3, rounds=3, memory="X")
+        assert isinstance(c, stim.Circuit)
+        assert c.num_detectors > 0
+
+    def test_memory_case_insensitive(self):
+        c_lower = make_stim_circuit(distance=3, rounds=2, memory="z")
+        c_upper = make_stim_circuit(distance=3, rounds=2, memory="Z")
+        assert c_lower.num_qubits == c_upper.num_qubits
+
+    def test_no_reset_flag(self):
+        c_reset = make_stim_circuit(distance=3, rounds=3, no_reset=False)
+        c_no_reset = make_stim_circuit(distance=3, rounds=3, no_reset=True)
+        # No-reset version has no R after M, so the string representation differs
+        assert "MR" in str(c_reset)
+        assert "MR" not in str(c_no_reset)
+
+    def test_noise_model_applied(self):
+        c_noiseless = make_stim_circuit(distance=3, rounds=2, noise=None)
+        c_noisy = make_stim_circuit(distance=3, rounds=2, noise=DEFAULT_NOISE)
+        # Noisy circuit includes DEPOLARIZE / X_ERROR / etc.
+        assert "DEPOLARIZE1" in str(c_noisy) or "X_ERROR" in str(c_noisy) or "PAULI_CHANNEL" in str(c_noisy)
+        assert "DEPOLARIZE1" not in str(c_noiseless) and "X_ERROR" not in str(c_noiseless)
+
+    def test_noise_partial_keys(self):
+        c = make_stim_circuit(
+            distance=3, rounds=2,
+            noise={"after_clifford_depolarization": 0.001},
+        )
+        assert isinstance(c, stim.Circuit)
+
+    def test_distance_5(self):
+        c = make_stim_circuit(distance=5, rounds=2)
+        assert c.num_qubits > 0
+        assert c.num_detectors > 0
+
+    def test_default_noise_constant(self):
+        assert "after_clifford_depolarization" in DEFAULT_NOISE
+        assert "after_reset_flip_probability" in DEFAULT_NOISE
+        assert "before_measure_flip_probability" in DEFAULT_NOISE
+        assert "before_round_data_depolarization" in DEFAULT_NOISE
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+#  surface_code.py — make_qiskit_circuit
+# ─────────────────────────────────────────────────────────────────────────────
+
+class TestMakeQiskitCircuit:
+    def test_returns_circuit_and_metadata(self):
+        qc, meta = make_qiskit_circuit(distance=3, rounds=3)
+        from qiskit import QuantumCircuit
+        assert isinstance(qc, QuantumCircuit)
+        assert isinstance(meta, dict)
+
+    def test_metadata_keys(self):
+        _, meta = make_qiskit_circuit(distance=3, rounds=3)
+        for k in ("num_data_qubits", "num_anc_qubits", "data_qubit_indices",
+                  "anc_qubit_indices", "rounds", "memory", "no_reset"):
+            assert k in meta, f"Missing key: {k}"
+
+    def test_distance_3_counts(self):
+        qc, meta = make_qiskit_circuit(distance=3, rounds=3)
+        assert meta["num_data_qubits"] == 9
+        assert meta["num_anc_qubits"] == 8
+        assert qc.num_qubits == 17
+        # rounds * num_anc + num_data classical bits
+        assert qc.num_clbits == 3 * 8 + 9
+
+    def test_distance_2_counts(self):
+        qc, meta = make_qiskit_circuit(distance=2, rounds=2)
+        assert meta["num_data_qubits"] == 4
+        assert meta["num_anc_qubits"] == 3
+        assert qc.num_qubits == 7
+        assert qc.num_clbits == 2 * 3 + 4
+
+    def test_x_memory(self):
+        qc, meta = make_qiskit_circuit(distance=3, rounds=2, memory="X")
+        assert meta["memory"] == "X"
+        # X memory should have H gates (H on ancillas)
+        op_names = [instr.operation.name for instr in qc.data]
+        assert "h" in op_names
+
+    def test_z_memory(self):
+        qc, meta = make_qiskit_circuit(distance=3, rounds=2, memory="Z")
+        assert meta["memory"] == "Z"
+
+    def test_no_reset_skips_resets(self):
+        qc_with, _ = make_qiskit_circuit(distance=3, rounds=3, no_reset=False)
+        qc_without, _ = make_qiskit_circuit(distance=3, rounds=3, no_reset=True)
+        # With reset: more reset ops
+        ops_with = sum(1 for instr in qc_with.data if instr.operation.name == "reset")
+        ops_without = sum(1 for instr in qc_without.data if instr.operation.name == "reset")
+        assert ops_with > ops_without
+
+    def test_depth_grows_with_rounds(self):
+        qc1, _ = make_qiskit_circuit(distance=3, rounds=1)
+        qc5, _ = make_qiskit_circuit(distance=3, rounds=5)
+        assert qc5.depth() > qc1.depth()
+
+    def test_noise_param_ignored(self):
+        # noise param is reserved for future use; should not error
+        qc, _ = make_qiskit_circuit(distance=3, rounds=2, noise=DEFAULT_NOISE)
+        assert qc.num_qubits == 17
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+#  surface_code.py — stim_to_qiskit
+# ─────────────────────────────────────────────────────────────────────────────
+
+class TestStimToQiskit:
+    def test_basic_conversion(self):
+        stim_circ = make_stim_circuit(distance=3, rounds=3, noise=None)
+        qc, stim_to_dense, meas_order = stim_to_qiskit(stim_circ)
+        from qiskit import QuantumCircuit
+        assert isinstance(qc, QuantumCircuit)
+        assert isinstance(stim_to_dense, dict)
+        assert isinstance(meas_order, list)
+        assert len(stim_to_dense) == qc.num_qubits
+        assert qc.num_clbits == stim_circ.num_measurements
+
+    def test_dense_indices_contiguous(self):
+        stim_circ = make_stim_circuit(distance=3, rounds=3, noise=None)
+        _, stim_to_dense, _ = stim_to_qiskit(stim_circ)
+        assert set(stim_to_dense.values()) == set(range(len(stim_to_dense)))
+
+    def test_strips_noise_instructions(self):
+        stim_circ = make_stim_circuit(distance=3, rounds=2, noise=DEFAULT_NOISE)
+        qc, _, _ = stim_to_qiskit(stim_circ)
+        # Qiskit circuit should not contain noise/annotation op names
+        # (Stims uses DEPOLARIZE1, X_ERROR, etc.)
+        op_names = [instr.operation.name for instr in qc.data]
+        assert "DEPOLARIZE1" not in op_names
+        assert "DETECTOR" not in op_names  # not a real qiskit op anyway, but check
+
+    def test_meas_order_length(self):
+        stim_circ = make_stim_circuit(distance=3, rounds=3, noise=None)
+        _, _, meas_order = stim_to_qiskit(stim_circ)
+        assert len(meas_order) == stim_circ.num_measurements
+
+    def test_raises_on_unhandled_gate(self, monkeypatch):
+        stim_circ = make_stim_circuit(distance=3, rounds=2, noise=None)
+        # Get a valid qubit index from the circuit
+        valid_qubit = list(get_meas_order(stim_circ))[0]
+        # Add an unhandled gate instruction on a valid qubit
+        stim_circ.append("S", [valid_qubit])  # S gate not in converter
+        with pytest.raises(NotImplementedError, match="Unhandled gate"):
+            stim_to_qiskit(stim_circ)
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+#  surface_code.py — get_circuit_info
+# ─────────────────────────────────────────────────────────────────────────────
+
+class TestGetCircuitInfo:
+    def test_returns_expected_keys(self):
+        stim_circ = make_stim_circuit(distance=3, rounds=3)
+        info = get_circuit_info(stim_circ)
+        expected = {
+            "num_qubits", "num_data_qubits", "num_anc_qubits",
+            "num_measurements", "num_detectors", "num_observables",
+            "data_stim_indices", "anc_stim_indices", "meas_order",
+        }
+        assert set(info.keys()) == expected
+
+    def test_qubit_classification_disjoint(self):
+        stim_circ = make_stim_circuit(distance=3, rounds=3)
+        info = get_circuit_info(stim_circ)
+        data_set = set(info["data_stim_indices"])
+        anc_set = set(info["anc_stim_indices"])
+        assert data_set.isdisjoint(anc_set)
+        # data + anc covers all measured qubits
+        assert len(data_set) + len(anc_set) == len(data_set | anc_set)
+
+    def test_data_qubit_count_for_distance_3(self):
+        stim_circ = make_stim_circuit(distance=3, rounds=3)
+        info = get_circuit_info(stim_circ)
+        assert info["num_data_qubits"] == 9
+        assert info["num_anc_qubits"] == 8
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+#  internal_helpers.py
+# ─────────────────────────────────────────────────────────────────────────────
+
+class TestGetQubitLists:
+    def test_data_anc_split(self):
+        stim_circ = make_stim_circuit(distance=3, rounds=3)
+        data_q, anc_q = get_qubit_lists(stim_circ)
+        assert len(data_q) == 9
+        assert len(anc_q) == 8
+
+    def test_handles_no_coords(self):
+        # Build a circuit with no QUBIT_COORDS — get_qubit_lists should still work
+        bare = stim.Circuit()
+        bare.append("M", [0, 1, 2])
+        data_q, anc_q = get_qubit_lists(bare)
+        # All measured qubits without coords → treated as data
+        assert sorted(data_q) == [0, 1, 2]
+        assert anc_q == []
+
+
+class TestGetMeasOrder:
+    def test_meas_order_matches_circuit(self):
+        stim_circ = make_stim_circuit(distance=3, rounds=3)
+        order = get_meas_order(stim_circ)
+        assert len(order) == stim_circ.num_measurements
+        # The same ancilla is measured once per round, so the order may repeat
+        # qubit indices. Verify the entries are valid (subset of stim qubit set).
+        stim_qubits = set()
+        for instr in stim_circ.flattened():
+            if instr.name in ("M", "MR"):
+                for t in instr.targets_copy():
+                    if t.is_qubit_target:
+                        stim_qubits.add(t.value)
+        assert set(order).issubset(stim_qubits)
+        # And there should be (rounds) measurements per ancilla
+        # (excluding the final data readout round in some circuits)
+        assert len(order) >= len(stim_qubits)
+
+
+class TestCountsToMeasurementArray:
+    def test_basic_conversion(self):
+        counts = {"00": 3, "11": 2}
+        # Qiskit bitstrings: rightmost is clbit 0
+        # "00" → [0, 0] → reversed → [0, 0] (both 0)
+        # "11" → [1, 1] → reversed → [1, 1] (both 1)
+        arr = counts_to_measurement_array(counts, num_measurements=2, total_shots=5)
+        assert arr.shape == (5, 2)
+        assert arr.dtype == bool
+        assert arr.sum() == 4  # 2 shots with "11" contribute 4 true bits
+
+    def test_explicit_meas_count(self):
+        counts = {"0000": 1, "1111": 1}
+        arr = counts_to_measurement_array(counts, num_measurements=4, total_shots=2)
+        assert arr.shape == (2, 4)
+        assert arr[0].sum() == 0
+        assert arr[1].sum() == 4
+
+    def test_truncation(self):
+        # Bitstring longer than num_measurements gets truncated
+        counts = {"00000": 1}  # 5 bits but we only want 3
+        arr = counts_to_measurement_array(counts, num_measurements=3, total_shots=1)
+        assert arr.shape == (1, 3)
+        assert arr[0].sum() == 0
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+#  extract_syndromes.py — extract_syndromes_manual
+# ─────────────────────────────────────────────────────────────────────────────
+
+class TestExtractSyndromesManual:
+    @pytest.fixture
+    def qiskit_setup(self):
+        qc, meta = make_qiskit_circuit(distance=3, rounds=3, no_reset=False)
+        return qc, meta
+
+    def test_noiseless_zero_detections(self, qiskit_setup):
+        from qiskit_aer import AerSimulator
+        qc, meta = qiskit_setup
+        sim = AerSimulator()
+        job = sim.run(qc, shots=64)
+        counts = job.result().get_counts()
+        raw = counts_to_measurement_array(counts, qc.num_clbits, 64)
+        syn = extract_syndromes_manual(raw, meta, print_summary=False)
+        assert syn["det_events"].sum() == 0  # noiseless → no detector fires
+        assert syn["num_shots"] == 64
+        assert syn["num_detectors"] == meta["num_anc_qubits"] * (meta["rounds"] - 1)
+
+    def test_output_dict_keys(self, qiskit_setup):
+        from qiskit_aer import AerSimulator
+        qc, meta = qiskit_setup
+        sim = AerSimulator()
+        job = sim.run(qc, shots=4)
+        counts = job.result().get_counts()
+        raw = counts_to_measurement_array(counts, qc.num_clbits, 4)
+        syn = extract_syndromes_manual(raw, meta, print_summary=False)
+        for k in ("det_events", "obs_flips", "raw_meas", "num_detectors",
+                  "num_shots", "syndrome_weight_per_shot", "detector_firing_rate"):
+            assert k in syn
+
+    def test_det_events_shape(self, qiskit_setup):
+        from qiskit_aer import AerSimulator
+        qc, meta = qiskit_setup
+        sim = AerSimulator()
+        job = sim.run(qc, shots=10)
+        counts = job.result().get_counts()
+        raw = counts_to_measurement_array(counts, qc.num_clbits, 10)
+        syn = extract_syndromes_manual(raw, meta, print_summary=False)
+        assert syn["det_events"].shape == (10, meta["num_anc_qubits"] * (meta["rounds"] - 1))
+        assert syn["obs_flips"].shape == (10, 1)
+
+    def test_inject_error_increases_weight(self, qiskit_setup):
+        from qiskit_aer import AerSimulator
+        from qiskit import QuantumCircuit
+        qc, meta = qiskit_setup
+        # Inject an X gate on a data qubit to force an error
+        qc_with_err = qc.copy()
+        qc_with_err.x(0)  # X on data qubit 0
+        qc_with_err.barrier()
+        # Re-apply the same operations after the error... actually the simpler
+        # check is: in the noiseless baseline, syndrome_weight_per_shot.sum() should
+        # be larger after manually flipping a bit in the raw_meas.
+        sim = AerSimulator()
+        job = sim.run(qc, shots=20)
+        counts = job.result().get_counts()
+        raw = counts_to_measurement_array(counts, qc.num_clbits, 20)
+        syn_clean = extract_syndromes_manual(raw, meta, print_summary=False)
+        # Flip one measurement in round 1 (column = anc_idx + 1 * num_anc)
+        raw_flipped = raw.copy()
+        raw_flipped[:, 0 + 1 * meta["num_anc_qubits"]] ^= True
+        syn_dirty = extract_syndromes_manual(raw_flipped, meta, print_summary=False)
+        assert syn_dirty["syndrome_weight_per_shot"].sum() > syn_clean["syndrome_weight_per_shot"].sum()
+
+    def test_with_noise(self):
+        from qiskit_aer import AerSimulator
+        from qiskit_aer.noise import NoiseModel, depolarizing_error
+        # Build a tiny noise model
+        noise_model = NoiseModel()
+        noise_model.add_all_qubit_quantum_error(depolarizing_error(0.05, 1), ["h", "x"])
+        noise_model.add_all_qubit_quantum_error(depolarizing_error(0.05, 2), ["cx"])
+        qc, meta = make_qiskit_circuit(distance=3, rounds=3)
+        sim = AerSimulator(noise_model=noise_model)
+        job = sim.run(qc, shots=128)
+        counts = job.result().get_counts()
+        raw = counts_to_measurement_array(counts, qc.num_clbits, 128)
+        syn = extract_syndromes_manual(raw, meta, print_summary=False)
+        # With noise, some shots should have detection events
+        assert syn["syndrome_weight_per_shot"].sum() > 0
+
+    def test_print_summary(self, qiskit_setup, capsys):
+        from qiskit_aer import AerSimulator
+        qc, meta = qiskit_setup
+        sim = AerSimulator()
+        job = sim.run(qc, shots=4)
+        counts = job.result().get_counts()
+        raw = counts_to_measurement_array(counts, qc.num_clbits, 4)
+        extract_syndromes_manual(raw, meta, print_summary=True)
+        captured = capsys.readouterr().out
+        assert "Manual Syndrome extraction summary" in captured
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+#  extract_syndromes.py — extract_syndromes (Stim m2d path)
+# ─────────────────────────────────────────────────────────────────────────────
+
+class TestExtractSyndromesStim:
+    def test_stim_detector_sampler(self):
+        # Use the detector sampler to get det/obs and verify shape
+        stim_circ = make_stim_circuit(distance=3, rounds=3, noise=DEFAULT_NOISE)
+        sampler = stim_circ.compile_detector_sampler()
+        det, obs = sampler.sample(shots=32, separate_observables=True)
+        assert det.shape[0] == 32
+        assert obs.shape[0] == 32
+        assert det.dtype == bool
+        assert obs.dtype == bool
+
+    def test_noiseless_zero_detections(self):
+        stim_circ = make_stim_circuit(distance=3, rounds=3, noise=None)
+        sampler = stim_circ.compile_detector_sampler()
+        det, obs = sampler.sample(shots=10, separate_observables=True)
+        assert det.sum() == 0
+        assert obs.sum() == 0
+
+    def test_extract_syndromes_with_raw_meas(self):
+        # Build a noisy circuit and feed its raw measurements into extract_syndromes
+        stim_circ = make_stim_circuit(distance=3, rounds=3, noise=DEFAULT_NOISE)
+        sampler = stim_circ.compile_detector_sampler()
+        det_expected, obs_expected = sampler.sample(shots=8, separate_observables=True)
+        # Now build raw_meas by sampling the same circuit with the measurement sampler
+        meas_sampler = stim_circ.compile_m2d_converter()
+        # The m2d converter takes raw measurements and returns det/obs
+        # We need to generate raw_meas by calling the circuit-level sampler
+        raw_meas = np.zeros((8, stim_circ.num_measurements), dtype=bool)
+        for i in range(8):
+            sample = stim_circ.compile_detector_sampler(seed=i).sample(
+                shots=1, separate_observables=False
+            )
+            # sample has shape (1, num_detectors + num_observables + ...)
+            # The raw measurements are available via a different API
+        # Instead, use the converter to get det/obs from a known raw_meas
+        # We'll use the fact that noiseless measurements are all-zero
+        if stim_circ.num_measurements == 0:
+            pytest.skip("Circuit has no measurements")
+        # Build a zero raw_meas and verify the converter handles it
+        result = extract_syndromes(
+            np.zeros((1, stim_circ.num_measurements), dtype=bool),
+            stim_circ,
+            print_summary=False,
+        )
+        assert "det_events" in result
+        assert "obs_flips" in result
+        assert "num_detectors" in result
+        assert "num_shots" in result
+        assert result["num_shots"] == 1
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+#  build_emerald_qubit_rotated.py
+# ─────────────────────────────────────────────────────────────────────────────
+
+class TestBuildEmeraldQubitMap:
+    def test_returns_empty_dict(self):
+        # Current implementation returns an empty dict (TBD)
+        from build_emerald_qubit_rotated import build_emerald_qubit_map
+        stim_circ = make_stim_circuit(distance=3, rounds=3)
+        qb_map = build_emerald_qubit_map(stim_circ)
+        assert isinstance(qb_map, dict)
+        # Currently empty; this test guards the contract
+        assert qb_map == {} or isinstance(qb_map, dict)
+
+    def test_import_uses_internal_helpers(self):
+        # The module's import was broken in a prior commit — verify it works
+        from build_emerald_qubit_rotated import build_emerald_qubit_map  # noqa: F401
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+#  run_on_hardware.py — decode_hardware_results
+# ─────────────────────────────────────────────────────────────────────────────
+
+class TestDecodeHardwareResults:
+    def test_mwpm_default_returns_empty_lists(self):
+        from run_on_hardware import decode_hardware_results
+        syndromes = {
+            "det_events": np.zeros((4, 5), dtype=bool),
+            "obs_flips": np.zeros((4, 1), dtype=bool),
+            "num_detectors": 5,
+            "num_shots": 4,
+        }
+        ler, err = decode_hardware_results(syndromes, decoder="mwpm")
+        assert ler == []
+        assert err == []
+
+    def test_diffqec_missing_model_path_raises(self):
+        from run_on_hardware import decode_hardware_results
+        syndromes = {
+            "det_events": np.zeros((4, 5), dtype=bool),
+            "obs_flips": np.zeros((4, 1), dtype=bool),
+            "num_detectors": 5,
+            "num_shots": 4,
+        }
+        with pytest.raises(ValueError, match="model_path"):
+            decode_hardware_results(syndromes, decoder="diffqec")
+
+    def test_unknown_decoder_returns_empty(self):
+        from run_on_hardware import decode_hardware_results
+        syndromes = {
+            "det_events": np.zeros((4, 5), dtype=bool),
+            "obs_flips": np.zeros((4, 1), dtype=bool),
+            "num_detectors": 5,
+            "num_shots": 4,
+        }
+        ler, err = decode_hardware_results(syndromes, decoder="unknown")
+        assert ler == []
+        assert err == []
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+#  main.py — run_simulation_test
+# ─────────────────────────────────────────────────────────────────────────────
+
+class TestMainSimulation:
+    def test_run_simulation_test_runs_without_error(self, capsys):
+        from main import run_simulation_test
+        run_simulation_test()
+        captured = capsys.readouterr().out
+        assert "Surface Code QEC Pipeline" in captured
+        assert "IMPLEMENTATION SUMMARY" in captured
+
+    def test_main_entrypoint(self, capsys):
+        from main import main
+        main()
+        captured = capsys.readouterr().out
+        assert "Surface Code QEC Pipeline" in captured
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+#  Pipeline integration: end-to-end Stim + Qiskit paths agree
+# ─────────────────────────────────────────────────────────────────────────────
+
+class TestPipelineIntegration:
+    def test_stim_circuit_info_consistent(self):
+        stim_circ = make_stim_circuit(distance=3, rounds=3, noise=DEFAULT_NOISE)
+        info = get_circuit_info(stim_circ)
+        # num_qubits >= data + anc (Stim may have unmeasured qubits too)
+        assert info["num_qubits"] >= info["num_data_qubits"] + info["num_anc_qubits"]
+        # All classified qubits are part of the total
+        classified = len(info["data_stim_indices"]) + len(info["anc_stim_indices"])
+        assert classified == info["num_data_qubits"] + info["num_anc_qubits"]
+        # num_detectors > 0
+        assert info["num_detectors"] > 0
+        # num_measurements > num_detectors (final data measurements too)
+        assert info["num_measurements"] >= info["num_detectors"]
+
+    def test_stim_to_qiskit_then_simulation(self):
+        stim_circ = make_stim_circuit(distance=3, rounds=3, noise=None)
+        qc, stim_to_dense, meas_order = stim_to_qiskit(stim_circ)
+        from qiskit_aer import AerSimulator
+        sim = AerSimulator()
+        job = sim.run(qc, shots=8)
+        counts = job.result().get_counts()
+        raw = counts_to_measurement_array(counts, qc.num_clbits, 8)
+        # extract_syndromes_manual needs the Qiskit-style metadata, not Stim
+        # so we just verify the raw_meas shape is reasonable
+        assert raw.shape == (8, qc.num_clbits)