TIM2 更新触发 → ADC1 → DMA2 循环写 samples[128]
                         A = [0..63]，B = [64..127]
HT：A 完成，DMA 将写 B → 请求 USART2 TX DMA 借出 A
TX 完成：归还 A
TC：B 完成，DMA 将回到 A → 请求 USART2 TX DMA 借出 B
忙、乱序、过期、错误：先停止采集源这个物理副作用，再由主循环清理

调用者提供 BatchEvent(kind, now, session, half, token)
    ↓
batch_event(&调用者持有的状态, event, &action)
    ↓
修改 Batch 所有权 / 首错快照，并输出 BatchAction
    ↓
主机：固定 Fake 记录动作，提供启动/停止/清理返回值
板端：HAL 执行动作，把真实完成/错误回调送回同一个入口

HSI = 16 MHz → PLLM=16 → VCO 输入 1 MHz → PLLN=336 → VCO 336 MHz
                                            ├ PLLP=4 → SYSCLK 84 MHz
                                            └ PLLQ=7 → 标称 48 MHz；本课不用其证明 USB 合规
SYSCLK → AHB /1 → HCLK 84 MHz，DMA1/2 总线访问在此时钟树下工作
HCLK   → APB1 /2 → PCLK1 42 MHz
                    ├ TIM2：该目标 APB 分频不为 1 时，定时器输入为 2×PCLK1 = 84 MHz
                    └ USART2：波特率基准 PCLK1 = 42 MHz
HCLK   → APB2 /2 → PCLK2 42 MHz → ADC common prescaler /4 → ADCCLK 10.5 MHz
HAL tick：HCLK 下 1 ms SysTick，时钟切换后 HAL 按新 HCLK 配置

TIM2：PSC=83，ARR=999，向上计数
f_counter = 84,000,000 / (83+1) = 1,000,000 Hz
f_TRGO    = 1,000,000 / (999+1) = 1,000 Hz；周期标称 1 ms
ADC：12 bit，84 cycles 采样 + 12 cycles 转换
T_conversion ≈ 96 / 10,500,000 = 9.143 us（不含触发同步延迟，不替代模拟建立时间验证）
半区：64 个样本 → T_half = 64 / 1000 = 64 ms
USART2：115200，8 数据位、无校验、1 停止位，加 1 起始位 → 10 bit/byte
理想发送时间 = 128 byte × 10 / 115200 ≈ 11.111 ms
所选HAL包的过采样16宏对42 MHz/115200的计算结果为BRR=0x16C（除数364），名义波特率约115384.62
对应发送时间约11.093 ms；这是主机求值/算术推导，不是目标寄存器读值或频率实测

发布 IRQ 延迟 + 启动 TX 时间 + 实际线速时间 + 完成 IRQ 延迟 + 抖动余量 < 64 ms
边界 IRQ 最坏延迟 + 停 TIM2 的时间 < 下一次采样触发间隔（标称 1 ms）

main → HAL_Init → Reference_Init
       → HSI/PLL/总线时钟 → GPIO/外设门控复位 → DMA 初始化与链接
       → TIM2/ADC1/USART2 初始化 → batch_start 输出 ARM
       → HAL_ADC_Start_DMA(128) → HAL_TIM_Base_Start → ARM结果
DMA2_Stream0_IRQHandler → HAL_DMA_IRQHandler
       → HAL_ADC_ConvHalfCpltCallback / HAL_ADC_ConvCpltCallback
       → batch_event → ACT_TX → HAL_UART_Transmit_DMA
DMA1_Stream6_IRQHandler → HAL_DMA_IRQHandler → HAL内部 UART DMA completion
       → 关闭 DMAT，打开 USART TC interrupt（normal模式）
USART2_IRQHandler → HAL_UART_IRQHandler → HAL_UART_TxCpltCallback
       → batch_event(TX_DONE) → 归还活动半区
ADC_IRQHandler / DMA error → HAL_ADC_ErrorCallback 或 HAL_UART_ErrorCallback
       → batch_event(IO_ERROR) → STOP_SOURCE
main → Reference_Service → POLL；操作员显式 RequestRecovery 后才执行 CLEAN
       → 再停TIM2 → HAL_ADC_Stop_DMA → HAL_UART_AbortTransmit
       → 确认两stream EN清零 → 重置相关DMA/HAL状态 → 清外设标志/旧NVIC pending
       → 新会话 ARM（先ADC DMA后TIM2）；失败仍故障

lessons/L039-host-test/
  README.md                 lesson.json
  CMakeLists.txt            .gitignore
  core/batch.h              core/batch.c
  host/test_batch.c          host/check_mutations.py
  target/reference_f407.h    target/reference_f407.c
  target/reference_main.c    target/stm32f4xx_hal_conf.h
  evidence/                 主机日志、来源核对记录、自检记录

cmake -S lessons/L039-host-test -B lessons/L039-host-test/build -G Ninja -DCMAKE_BUILD_TYPE=Debug
if ($LASTEXITCODE -ne 0) { throw '主机构建配置失败' }
cmake --build lessons/L039-host-test/build
if ($LASTEXITCODE -ne 0) { throw '主机编译失败，尚未执行逻辑测试' }
& ./lessons/L039-host-test/build/host_batch_test.exe --minimal
if ($LASTEXITCODE -ne 0) { throw '最小交接断言失败' }
& ./lessons/L039-host-test/build/host_batch_test.exe
if ($LASTEXITCODE -ne 0) { throw '完整交接断言失败' }
ctest --test-dir lessons/L039-host-test/build --output-on-failure
if ($LASTEXITCODE -ne 0) { throw 'CTest 未通过' }
python lessons/L039-host-test/host/check_mutations.py
if ($LASTEXITCODE -ne 0) { throw '错误副本未被正确检出' }

& ./lessons/L039-host-test/build/host_batch_test.exe --demo-failure
if ($LASTEXITCODE -ne 1) { throw '故意失败的示例没有产生预期退出码1' }

#ifndef BATCH_H
#define BATCH_H
#include <stdint.h>
#define BATCH_HALF_SAMPLES 64u
#define BATCH_SAMPLES 128u
#define BATCH_HALF_BYTES 128u
#define MODE_IDLE 0u
#define MODE_STARTING 1u
#define MODE_RUNNING 2u
#define MODE_FAULT 3u
#define MODE_CLEANING 4u
#define HALF_FREE 0u
#define HALF_CAPTURE 1u
#define HALF_TX 2u
#define EV_HT 1u
#define EV_TC 2u
#define EV_TX_DONE 3u
#define EV_POLL 4u
#define EV_IO_ERROR 5u
#define EV_TX_START_ERROR 6u
#define ACT_NONE 0u
#define ACT_ARM 1u
#define ACT_TX 2u
#define ACT_STOP_SOURCE 3u
#define ACT_CLEAN 4u
#define FAULT_NONE 0u
#define FAULT_ORDER 1u
#define FAULT_BUSY 2u
#define FAULT_DEADLINE 3u
#define FAULT_CALLBACK 4u
#define FAULT_START 5u
#define FAULT_DEVICE 6u
#define FAULT_STALE 7u
#define FAULT_ARGUMENT 8u

typedef struct {
    uint32_t kind, now, session, half, token;
} BatchEvent;
typedef struct {
    uint32_t kind, session, half, token;
} BatchAction;
typedef struct {
    uint32_t code, event, tick, session, half, token;
} BatchSnapshot;
typedef struct {
    uint32_t window_ms, mode, session, expected_half, sequence;
    uint32_t half_state[2];
    uint32_t tx_active, tx_half, tx_token, tx_start_tick;
    uint32_t current_fault, stop_ok, stop_errors, cleanup_errors;
    BatchSnapshot first_fault;
    uint16_t samples[BATCH_SAMPLES];
} Batch;

/* Caller owns Batch and serializes ALL calls; no allocation or HAL dependency. */
/* init requires quiescent hardware and no outstanding users; NOT a recovery API. */
uint32_t batch_init(Batch *s, uint32_t window_ms);
uint32_t batch_start(Batch *s, BatchAction *out);
void batch_arm_result(Batch *s, uint32_t io_error, uint32_t now,
                      BatchAction *out);
void batch_event(Batch *s, BatchEvent event, BatchAction *out);
void batch_stop_result(Batch *s, uint32_t io_error);
uint32_t batch_recover(Batch *s, BatchAction *out);
void batch_cleanup_result(Batch *s, uint32_t io_error, BatchAction *out);
#endif

#include "batch.h"
#include <string.h>
_Static_assert(sizeof(uint16_t) == 2u, "Requires 8-bit bytes");

static void no_action(BatchAction *a)
{ memset(a, 0, sizeof(*a)); }
static void fault(Batch *s, uint32_t code, BatchEvent e, BatchAction *a)
{
    /* Freeze the decision before any external action. First physical action is STOP. */
    s->mode = MODE_FAULT;
    s->current_fault = code;
    s->stop_ok = 0u;
    if (s->first_fault.code == FAULT_NONE) {
        s->first_fault.code = code;
        s->first_fault.event = e.kind;
        s->first_fault.tick = e.now;
        s->first_fault.session = e.session;
        s->first_fault.half = e.half;
        s->first_fault.token = e.token;
    }
    a->kind = ACT_STOP_SOURCE;
    a->session = s->session;
}
static void new_session(Batch *s, BatchAction *a)
{
    BatchEvent e = {0};
    if (s->session == UINT32_MAX) {
        e.session = s->session;
        fault(s, FAULT_ARGUMENT, e, a);
        return;
    }
    ++s->session;
    s->sequence = 0u;
    s->expected_half = 0u;
    s->half_state[0] = HALF_CAPTURE;
    s->half_state[1] = HALF_FREE;
    s->tx_active = 0u;
    s->tx_half = 0u;
    s->tx_token = 0u;
    s->tx_start_tick = 0u;
    s->current_fault = FAULT_NONE;
    s->stop_ok = 0u;
    memset(s->samples, 0, sizeof(s->samples));
    s->mode = MODE_STARTING;
    a->kind = ACT_ARM;
    a->session = s->session;
}
uint32_t batch_init(Batch *s, uint32_t window_ms)
{
    memset(s, 0, sizeof(*s));
    if (window_ms == 0u || window_ms >= UINT32_C(0x80000000)) { return 0u; }
    s->window_ms = window_ms;
    return 1u;
}
uint32_t batch_start(Batch *s, BatchAction *out)
{
    no_action(out);
    if (s->mode != MODE_IDLE || s->window_ms == 0u) { return 0u; }
    new_session(s, out);
    return 1u;
}
void batch_arm_result(Batch *s, uint32_t io_error, uint32_t now,
                      BatchAction *out)
{
    BatchEvent e = {EV_IO_ERROR, now, s->session, 0u, 0u};
    no_action(out);
    if (s->mode != MODE_STARTING) { return; }
    if (io_error != 0u) { fault(s, FAULT_START, e, out); }
    else { s->mode = MODE_RUNNING; }
}
void batch_event(Batch *s, BatchEvent e, BatchAction *out)
{
    uint32_t finished, next;
    no_action(out);
    /* Faulted/cleaning sessions do not release memory in response to callbacks. */
    if (s->mode != MODE_RUNNING) { return; }
    if (e.session != s->session) { fault(s, FAULT_STALE, e, out); return; }
    /* Unsigned subtraction handles one tick wrap; callers must poll regularly. */
    if (s->tx_active != 0u &&
        (uint32_t)(e.now - s->tx_start_tick) >= s->window_ms) {
        fault(s, FAULT_DEADLINE, e, out); return;
    }
    if (e.kind == EV_HT || e.kind == EV_TC) {
        finished = e.kind == EV_HT ? 0u : 1u;
        next = finished ^ 1u;
        if (e.half != finished || finished != s->expected_half ||
            s->half_state[finished] != HALF_CAPTURE) {
            fault(s, FAULT_ORDER, e, out); return;
        }
        if (s->tx_active != 0u || s->half_state[next] != HALF_FREE) {
            fault(s, FAULT_BUSY, e, out); return;
        }
        if (s->sequence == UINT32_MAX) {
            fault(s, FAULT_ARGUMENT, e, out); return;
        }
        ++s->sequence;
        s->half_state[finished] = HALF_TX;
        s->half_state[next] = HALF_CAPTURE;
        s->expected_half = next;
        s->tx_active = 1u;
        s->tx_half = finished;
        s->tx_token = s->sequence;
        s->tx_start_tick = e.now;
        out->kind = ACT_TX;
        out->session = s->session;
        out->half = finished;
        out->token = s->tx_token;
    } else if (e.kind == EV_TX_DONE) {
        if (s->tx_active == 0u || e.half != s->tx_half || e.token != s->tx_token) {
            fault(s, FAULT_CALLBACK, e, out); return;
        }
        s->half_state[s->tx_half] = HALF_FREE;
        s->tx_active = 0u;
    } else if (e.kind == EV_TX_START_ERROR) {
        fault(s, FAULT_START, e, out);
    } else if (e.kind == EV_IO_ERROR) {
        fault(s, FAULT_DEVICE, e, out);
    } else if (e.kind != EV_POLL) {
        fault(s, FAULT_ARGUMENT, e, out);
    }
}
void batch_stop_result(Batch *s, uint32_t io_error)
{
    if (s->mode != MODE_FAULT) { return; }
    s->stop_ok = io_error == 0u ? 1u : 0u;
    if (io_error != 0u) { ++s->stop_errors; }
}
uint32_t batch_recover(Batch *s, BatchAction *out)
{
    no_action(out);
    if (s->mode != MODE_FAULT) { return 0u; }
    s->mode = MODE_CLEANING;
    out->kind = ACT_CLEAN;
    out->session = s->session;
    return 1u;
}
void batch_cleanup_result(Batch *s, uint32_t io_error, BatchAction *out)
{
    no_action(out);
    if (s->mode != MODE_CLEANING) { return; }
    if (io_error != 0u) {
        ++s->cleanup_errors;
        s->mode = MODE_FAULT; /* Keep current/first fault; NEVER rearm on failure. */
    } else {
        new_session(s, out); /* Adapter promises all old hardware activity is drained. */
    }
}

#include "batch.h"
#include <stdio.h>
#include <string.h>

typedef struct {
    Batch s;
    BatchAction log[32];
    uint32_t count, overflow, arm_error, tx_error, stop_error, clean_error;
    uint8_t wire[BATCH_HALF_BYTES];
} Fixture;
static uint32_t failures, checks;
static const char *case_name;
#define CHECK(x) do { ++checks; if (!(x)) { ++failures; \
    printf("FAIL %s line %u: %s\n", case_name, (unsigned)__LINE__, #x); } } while (0)

/* Fixed fake: execute requested actions, do not decide ownership or expected results. */
static void drive(Fixture *f, BatchAction a, uint32_t now)
{
    while (a.kind != ACT_NONE) {
        if (f->count >= 32u) { f->overflow = 1u; return; }
        f->log[f->count++] = a;
        if (a.kind == ACT_ARM) {
            batch_arm_result(&f->s, f->arm_error, now, &a);
        } else if (a.kind == ACT_TX) {
            if (a.half > 1u) { f->overflow = 1u; return; }
            memcpy(f->wire, &f->s.samples[a.half * BATCH_HALF_SAMPLES],
                   BATCH_HALF_BYTES);
            if (f->tx_error != 0u) {
                BatchEvent e = {EV_TX_START_ERROR, now, a.session, a.half, a.token};
                batch_event(&f->s, e, &a);
            } else { a.kind = ACT_NONE; }
        } else if (a.kind == ACT_STOP_SOURCE) {
            batch_stop_result(&f->s, f->stop_error);
            a.kind = ACT_NONE;
        } else if (a.kind == ACT_CLEAN) {
            batch_cleanup_result(&f->s, f->clean_error, &a);
        } else { f->overflow = 1u; return; }
    }
}
static void fixture(Fixture *f)
{
    BatchAction a = {0};
    memset(f, 0, sizeof(*f));
    CHECK(batch_init(&f->s, 64u) == 1u);
    CHECK(batch_start(&f->s, &a) == 1u);
    drive(f, a, 0u);
    CHECK(f->s.mode == MODE_RUNNING);
    CHECK(f->overflow == 0u);
}
static void send(Fixture *f, uint32_t kind, uint32_t now,
                 uint32_t half, uint32_t token, uint32_t session)
{
    BatchAction a = {0};
    BatchEvent e = {kind, now, session, half, token};
    batch_event(&f->s, e, &a);
    drive(f, a, now);
    printf("TRACE %s event=%u tick=%u mode=%u fault=%u tx=%u actions=%u\n",
           case_name, (unsigned)kind, (unsigned)now, (unsigned)f->s.mode,
           (unsigned)f->s.current_fault, (unsigned)f->s.tx_active, (unsigned)f->count);
    CHECK(f->overflow == 0u);
}
static void event(Fixture *f, uint32_t kind, uint32_t now,
                  uint32_t half, uint32_t token)
{ send(f, kind, now, half, token, f->s.session); }
static void recover(Fixture *f, uint32_t now)
{
    BatchAction a = {0};
    CHECK(batch_recover(&f->s, &a) == 1u);
    drive(f, a, now);
}
static uint32_t logged_kind(const Fixture *f, uint32_t index)
{ return index < f->count ? f->log[index].kind : ACT_NONE; }
static void fault_is(Fixture *f, uint32_t code)
{
    CHECK(f->s.mode == MODE_FAULT);
    CHECK(f->s.current_fault == code);
    CHECK(f->s.first_fault.code == code);
    CHECK(logged_kind(f, f->count - 1u) == ACT_STOP_SOURCE);
    CHECK(f->s.stop_ok == 1u);
}
static void normal(void)
{
    Fixture f;
    uint32_t i;
    uint16_t expected[BATCH_HALF_SAMPLES];
    case_name = "A_TX_done_B_TX_done_A";
    fixture(&f);
    CHECK(f.s.half_state[0] == HALF_CAPTURE);
    CHECK(f.s.half_state[1] == HALF_FREE);
    for (i = 0u; i < BATCH_HALF_SAMPLES; ++i) {
        f.s.samples[i] = (uint16_t)(0x100u + i);
        expected[i] = (uint16_t)(0x100u + i);
    }
    event(&f, EV_HT, 64u, 0u, 0u);
    CHECK(f.count == 2u);
    CHECK(f.log[0].kind == ACT_ARM);
    CHECK(f.log[1].kind == ACT_TX);
    CHECK(f.log[1].half == 0u && f.log[1].token == 1u);
    CHECK(f.s.half_state[0] == HALF_TX);
    CHECK(f.s.half_state[1] == HALF_CAPTURE);
    CHECK(memcmp(f.wire, expected, sizeof(expected)) == 0);
    event(&f, EV_POLL, 70u, 0u, 0u);
    CHECK(f.s.half_state[0] == HALF_TX); /* start is NOT completion */
    event(&f, EV_TX_DONE, 76u, 0u, 1u);
    CHECK(f.s.half_state[0] == HALF_FREE);
    CHECK(f.s.tx_active == 0u);
    CHECK(f.count == 2u); /* never send on completion */
    event(&f, EV_TC, 128u, 1u, 0u);
    CHECK(f.log[2].kind == ACT_TX && f.log[2].half == 1u);
    CHECK(f.log[2].token == 2u);
    CHECK(f.s.half_state[0] == HALF_CAPTURE);
    event(&f, EV_TX_DONE, 140u, 1u, 2u);
    event(&f, EV_HT, 192u, 0u, 0u);
    CHECK(f.log[3].half == 0u && f.log[3].token == 3u);
    event(&f, EV_TX_DONE, 204u, 0u, 3u);
    CHECK(f.s.mode == MODE_RUNNING && f.s.first_fault.code == FAULT_NONE);
}
static void cases(void)
{
    Fixture f;
    BatchSnapshot saved;
    uint32_t n;
    case_name = "TC_before_HT"; fixture(&f);
    event(&f, EV_TC, 64u, 1u, 0u); fault_is(&f, FAULT_ORDER);
    CHECK(f.count == 2u); /* ARM, STOP; never TX */

    case_name = "duplicate_HT"; fixture(&f);
    event(&f, EV_HT, 64u, 0u, 0u);
    event(&f, EV_HT, 65u, 0u, 0u); fault_is(&f, FAULT_ORDER);
    CHECK(f.count == 3u);

    case_name = "busy_before_deadline"; fixture(&f);
    event(&f, EV_HT, 64u, 0u, 0u);
    event(&f, EV_TC, 127u, 1u, 0u); fault_is(&f, FAULT_BUSY);
    CHECK(f.s.half_state[0] == HALF_TX);
    CHECK(f.count == 3u); /* no second TX */
    saved = f.s.first_fault; n = f.count;
    event(&f, EV_IO_ERROR, 128u, 0u, 0u);
    event(&f, EV_TX_DONE, 129u, 0u, 1u);
    CHECK(memcmp(&saved, &f.s.first_fault, sizeof(saved)) == 0);
    CHECK(f.count == n && f.s.half_state[0] == HALF_TX);

    case_name = "deadline_minus_one"; fixture(&f);
    event(&f, EV_HT, 64u, 0u, 0u);
    event(&f, EV_TX_DONE, 127u, 0u, 1u);
    CHECK(f.s.mode == MODE_RUNNING && f.s.half_state[0] == HALF_FREE);
    case_name = "deadline_equal"; fixture(&f);
    event(&f, EV_HT, 64u, 0u, 0u);
    event(&f, EV_TX_DONE, 128u, 0u, 1u); fault_is(&f, FAULT_DEADLINE);
    CHECK(f.s.half_state[0] == HALF_TX);
    case_name = "deadline_plus_one"; fixture(&f);
    event(&f, EV_HT, 64u, 0u, 0u);
    event(&f, EV_POLL, 129u, 0u, 0u); fault_is(&f, FAULT_DEADLINE);

    case_name = "duplicate_completion"; fixture(&f);
    event(&f, EV_HT, 64u, 0u, 0u);
    event(&f, EV_TX_DONE, 76u, 0u, 1u);
    event(&f, EV_TX_DONE, 77u, 0u, 1u); fault_is(&f, FAULT_CALLBACK);
    CHECK(f.s.half_state[0] == HALF_FREE && f.count == 3u);
    case_name = "wrong_half"; fixture(&f);
    event(&f, EV_HT, 64u, 0u, 0u);
    event(&f, EV_TX_DONE, 76u, 1u, 1u); fault_is(&f, FAULT_CALLBACK);
    CHECK(f.s.half_state[0] == HALF_TX);
    case_name = "wrong_token"; fixture(&f);
    event(&f, EV_HT, 64u, 0u, 0u);
    event(&f, EV_TX_DONE, 76u, 0u, 0u); fault_is(&f, FAULT_CALLBACK);
    CHECK(f.s.half_state[0] == HALF_TX);
    case_name = "unexpected_completion"; fixture(&f);
    event(&f, EV_TX_DONE, 1u, 0u, 0u); fault_is(&f, FAULT_CALLBACK);

    case_name = "TX_start_failure"; fixture(&f); f.tx_error = 1u;
    event(&f, EV_HT, 64u, 0u, 0u); fault_is(&f, FAULT_START);
    CHECK(f.count == 3u && f.log[1].kind == ACT_TX);
    case_name = "stop_failure_then_explicit_recovery"; fixture(&f);
    f.stop_error = 1u;
    event(&f, EV_IO_ERROR, 20u, 0u, 0u);
    CHECK(f.s.mode == MODE_FAULT && f.s.current_fault == FAULT_DEVICE);
    CHECK(f.s.first_fault.code == FAULT_DEVICE);
    CHECK(f.s.stop_ok == 0u && f.s.stop_errors == 1u);
    saved = f.s.first_fault; f.clean_error = 1u;
    recover(&f, 21u);
    CHECK(f.s.mode == MODE_FAULT && f.s.cleanup_errors == 1u);
    CHECK(logged_kind(&f, f.count - 1u) == ACT_CLEAN);
    CHECK(memcmp(&saved, &f.s.first_fault, sizeof(saved)) == 0);
    f.stop_error = 0u; f.clean_error = 0u;
    recover(&f, 22u);
    CHECK(logged_kind(&f, f.count - 2u) == ACT_CLEAN);
    CHECK(logged_kind(&f, f.count - 1u) == ACT_ARM);
    CHECK(f.s.mode == MODE_RUNNING && f.s.session == 2u);
    CHECK(f.s.current_fault == FAULT_NONE && f.s.tx_active == 0u);
    CHECK(f.s.samples[0] == 0u && f.s.samples[127] == 0u);
    CHECK(memcmp(&saved, &f.s.first_fault, sizeof(saved)) == 0);
    n = f.count;
    send(&f, EV_TX_DONE, 23u, 0u, 1u, 1u);
    CHECK(f.count == n + 1u && logged_kind(&f, f.count - 1u) == ACT_STOP_SOURCE);
    CHECK(f.s.current_fault == FAULT_STALE && f.s.mode == MODE_FAULT);
    CHECK(memcmp(&saved, &f.s.first_fault, sizeof(saved)) == 0);

    case_name = "arm_failure";
    memset(&f, 0, sizeof(f)); f.arm_error = 1u;
    { BatchAction a = {0}; CHECK(batch_init(&f.s, 64u) == 1u);
      CHECK(batch_start(&f.s, &a) == 1u); drive(&f, a, 0u); }
    fault_is(&f, FAULT_START);
    CHECK(f.count == 2u && f.log[0].kind == ACT_ARM);

    case_name = "tick_wrap"; fixture(&f);
    event(&f, EV_HT, UINT32_MAX - 31u, 0u, 0u);
    event(&f, EV_TX_DONE, 31u, 0u, 1u);
    CHECK(f.s.mode == MODE_RUNNING && f.s.tx_active == 0u);
    case_name = "tick_wrap_equal"; fixture(&f);
    event(&f, EV_HT, UINT32_MAX - 31u, 0u, 0u);
    event(&f, EV_TX_DONE, 32u, 0u, 1u); fault_is(&f, FAULT_DEADLINE);

    case_name = "invalid_event"; fixture(&f);
    event(&f, 99u, 1u, 0u, 0u); fault_is(&f, FAULT_ARGUMENT);
    case_name = "token_exhaustion"; fixture(&f); f.s.sequence = UINT32_MAX;
    event(&f, EV_HT, 64u, 0u, 0u); fault_is(&f, FAULT_ARGUMENT);
    case_name = "command_guards"; fixture(&f);
    { BatchAction a = {0}; CHECK(batch_start(&f.s, &a) == 0u);
      CHECK(a.kind == ACT_NONE); CHECK(batch_recover(&f.s, &a) == 0u);
      CHECK(a.kind == ACT_NONE); }
    { Batch invalid; /* Fresh, quiescent object: never re-init an active session. */
      CHECK(batch_init(&invalid, 0u) == 0u);
      CHECK(batch_init(&invalid, UINT32_MAX) == 0u); }
}
int main(int argc, char **argv)
{
    if (argc == 2 && strcmp(argv[1], "--demo-failure") == 0) {
        Fixture f;
        case_name = "intentional_missing_TX_DONE"; fixture(&f);
        event(&f, EV_HT, 64u, 0u, 0u);
        CHECK(f.s.half_state[0] == HALF_FREE); /* deliberately false oracle */
    } else if (argc == 2 && strcmp(argv[1], "--minimal") == 0) { normal(); }
    else { normal(); cases(); }
    printf("checks=%u failures=%u\n", (unsigned)checks, (unsigned)failures);
    return failures == 0u ? 0 : 1;
}

cmake_minimum_required(VERSION 3.20)
project(L039_host_test LANGUAGES C)
set(CMAKE_C_STANDARD 11)
set(CMAKE_C_STANDARD_REQUIRED ON)
set(CMAKE_C_EXTENSIONS OFF)
add_library(batch_core STATIC core/batch.c)
target_include_directories(batch_core PUBLIC core)
add_executable(host_batch_test host/test_batch.c)
target_link_libraries(host_batch_test PRIVATE batch_core)
if(CMAKE_C_COMPILER_ID MATCHES "GNU|Clang")
  target_compile_options(batch_core PRIVATE -Wall -Wextra -Werror -Wpedantic)
  target_compile_options(host_batch_test PRIVATE -Wall -Wextra -Werror -Wpedantic)
endif()
enable_testing()
add_test(NAME batch_contract COMMAND host_batch_test)

"""Deliberately alter only copied SUT files. Success means BOTH mutants are detected."""
import argparse
from pathlib import Path
import subprocess

p = argparse.ArgumentParser()
p.add_argument("--cc", default="gcc")
p.add_argument("--build-dir", default="build/mutations")
a = p.parse_args()
root = Path(__file__).resolve().parents[1]
out = (root / a.build_dir).resolve()
if not out.is_relative_to(root / "build"):
    raise SystemExit("Mutation artifacts must stay inside this lesson's ignored build/.")
out.mkdir(parents=True, exist_ok=True)
source = (root / "core/batch.c").read_text(encoding="utf-8")
mutants = [
    ("accept_equal_deadline", ">= s->window_ms", "> s->window_ms"),
    ("ignore_completion_token", "e.token != s->tx_token", "0u != 0u"),
]
for name, old, new in mutants:
    if source.count(old) != 1:
        raise SystemExit(f"Mutation anchor must occur once: {old}")
    cfile = out / f"{name}.c"
    exe = out / f"{name}.exe"
    cfile.write_text(source.replace(old, new), encoding="utf-8")
    subprocess.run([a.cc, "-std=c11", "-Wall", "-Wextra", "-Werror", "-Wpedantic",
                    "-I", str(root / "core"), str(cfile),
                    str(root / "host/test_batch.c"), "-o", str(exe)], check=True)
    result = subprocess.run([str(exe)], text=True, capture_output=True)
    print(f"=== {name} exit={result.returncode} ===")
    print(result.stdout, end="")
    if result.returncode != 1 or "FAIL " not in result.stdout:
        raise SystemExit("Mutant survived or crashed: a logical assertion failure was required.")
print("mutants_detected=2/2; original source was not modified")

#ifndef REFERENCE_F407_H
#define REFERENCE_F407_H
#include "stm32f4xx_hal.h"
#include "batch.h"
/* Chip-level choices MUST be checked against the chosen package and board schematic. */
typedef struct {
    GPIO_TypeDef *adc_port;
    uint32_t adc_pin, adc_channel;
    GPIO_TypeDef *tx_port;
    uint32_t tx_pin, tx_alternate;
    uint32_t supply_mv; /* Board documentation/measurement, NOT inferred from the MCU. */
} ReferencePins;
typedef struct {
    uint32_t mode, session, current_fault, stop_ok, stop_errors, cleanup_errors;
    uint32_t ht_count, tc_count, tx_count, error_count, last_hal_error;
    BatchSnapshot first_fault;
} ReferenceDiag;
/* Init result: 0 running, 1 fatal configuration/init error, 2 armed attempt faulted. */
uint32_t Reference_Init(const ReferencePins *pins);
void Reference_Service(void);
void Reference_RequestRecovery(void); /* Explicit operator decision; no automatic restart. */
void Reference_GetDiag(ReferenceDiag *out);
#endif

#ifndef STM32F4XX_HAL_CONF_H
#define STM32F4XX_HAL_CONF_H
/* Original, restricted reference configuration; HSE/LSE are NOT selected. */
#define HAL_MODULE_ENABLED
#define HAL_ADC_MODULE_ENABLED
#define HAL_CORTEX_MODULE_ENABLED
#define HAL_DMA_MODULE_ENABLED
#define HAL_FLASH_MODULE_ENABLED
#define HAL_GPIO_MODULE_ENABLED
#define HAL_PWR_MODULE_ENABLED
#define HAL_RCC_MODULE_ENABLED
#define HAL_TIM_MODULE_ENABLED
#define HAL_UART_MODULE_ENABLED
#define HSI_VALUE 16000000U
#define HSE_VALUE 0U
#define HSE_STARTUP_TIMEOUT 100U
#define LSI_VALUE 32000U
#define LSE_VALUE 32768U
#define LSE_STARTUP_TIMEOUT 5000U
#define EXTERNAL_CLOCK_VALUE 0U
#define VDD_VALUE 0U
#define TICK_INT_PRIORITY 15U
#define USE_RTOS 0U
#define PREFETCH_ENABLE 1U
#define INSTRUCTION_CACHE_ENABLE 1U
#define DATA_CACHE_ENABLE 1U
#define USE_HAL_ADC_REGISTER_CALLBACKS 0U
#define USE_HAL_UART_REGISTER_CALLBACKS 0U
#define USE_HAL_TIM_REGISTER_CALLBACKS 0U
#include "stm32f4xx_hal_rcc.h"
#include "stm32f4xx_hal_gpio.h"
#include "stm32f4xx_hal_dma.h"
#include "stm32f4xx_hal_cortex.h"
#include "stm32f4xx_hal_adc.h"
#include "stm32f4xx_hal_flash.h"
#include "stm32f4xx_hal_pwr.h"
#include "stm32f4xx_hal_tim.h"
#include "stm32f4xx_hal_uart.h"
#define assert_param(expr) ((void)0U)
#endif

/* Original reference adapter. NOT a board build or hardware-verification record. */
#include "reference_f407.h"
#include <string.h>
#include <stddef.h>

_Alignas(4) static Batch g_batch; /* Must be in DMA-accessible SRAM, NEVER F407 CCM. */
_Static_assert(offsetof(Batch, samples) % 4u == 0u, "ADC buffer alignment");
static ADC_HandleTypeDef g_adc;
static UART_HandleTypeDef g_uart;
static TIM_HandleTypeDef g_tim;
static DMA_HandleTypeDef g_adc_dma, g_tx_dma;
static ReferencePins g_pins;
static BatchAction g_hw_ticket;
static volatile uint32_t g_callbacks, g_recover, g_ready;
static volatile uint32_t g_ht, g_tc, g_tx, g_error, g_last_hal_error;
static const IRQn_Type g_irqs[4] = {
    DMA2_Stream0_IRQn, DMA1_Stream6_IRQn, ADC_IRQn, USART2_IRQn
};
static uint32_t lock(void)
{ uint32_t p = __get_PRIMASK(); __disable_irq(); return p; }
static void unlock(uint32_t p)
{ __set_PRIMASK(p); }
static void irq_enable(uint32_t enable)
{
    uint32_t i;
    for (i = 0u; i < 4u; ++i) {
        if (enable != 0u) { HAL_NVIC_EnableIRQ(g_irqs[i]); }
        else { HAL_NVIC_DisableIRQ(g_irqs[i]); }
    }
}
static uint32_t gpio_clock(GPIO_TypeDef *port)
{
    if (port == GPIOA) { __HAL_RCC_GPIOA_CLK_ENABLE(); }
    else if (port == GPIOB) { __HAL_RCC_GPIOB_CLK_ENABLE(); }
    else if (port == GPIOC) { __HAL_RCC_GPIOC_CLK_ENABLE(); }
    else if (port == GPIOD) { __HAL_RCC_GPIOD_CLK_ENABLE(); }
    else if (port == GPIOE) { __HAL_RCC_GPIOE_CLK_ENABLE(); }
    else if (port == GPIOF) { __HAL_RCC_GPIOF_CLK_ENABLE(); }
    else if (port == GPIOG) { __HAL_RCC_GPIOG_CLK_ENABLE(); }
    else if (port == GPIOH) { __HAL_RCC_GPIOH_CLK_ENABLE(); }
    else if (port == GPIOI) { __HAL_RCC_GPIOI_CLK_ENABLE(); }
    else { return 1u; }
    return 0u;
}
static uint32_t one_pin(uint32_t pin)
{ return pin != 0u && pin <= GPIO_PIN_15 && (pin & (pin - 1u)) == 0u ? 1u : 0u; }
static uint32_t clock_init(void)
{
    RCC_OscInitTypeDef o = {0};
    RCC_ClkInitTypeDef c = {0};
    __HAL_RCC_PWR_CLK_ENABLE();
    __HAL_PWR_VOLTAGESCALING_CONFIG(PWR_REGULATOR_VOLTAGE_SCALE2);
    o.OscillatorType = RCC_OSCILLATORTYPE_HSI;
    o.HSIState = RCC_HSI_ON;
    o.HSICalibrationValue = RCC_HSICALIBRATION_DEFAULT;
    o.PLL.PLLState = RCC_PLL_ON;
    o.PLL.PLLSource = RCC_PLLSOURCE_HSI;
    o.PLL.PLLM = 16u; o.PLL.PLLN = 336u;
    o.PLL.PLLP = RCC_PLLP_DIV4; o.PLL.PLLQ = 7u;
    if (HAL_RCC_OscConfig(&o) != HAL_OK) { return 1u; }
    c.ClockType = RCC_CLOCKTYPE_SYSCLK | RCC_CLOCKTYPE_HCLK |
                  RCC_CLOCKTYPE_PCLK1 | RCC_CLOCKTYPE_PCLK2;
    c.SYSCLKSource = RCC_SYSCLKSOURCE_PLLCLK;
    c.AHBCLKDivider = RCC_SYSCLK_DIV1;
    c.APB1CLKDivider = RCC_HCLK_DIV2;
    c.APB2CLKDivider = RCC_HCLK_DIV2;
    /* Requires documented 2.7..3.6 V supply; caller checked it before this call. */
    return HAL_RCC_ClockConfig(&c, FLASH_LATENCY_2) == HAL_OK ? 0u : 1u;
}
static uint32_t adc_uart_init(void)
{
    ADC_ChannelConfTypeDef ch = {0};
    g_adc.Instance = ADC1;
    g_adc.Init.ClockPrescaler = ADC_CLOCK_SYNC_PCLK_DIV4;
    g_adc.Init.Resolution = ADC_RESOLUTION_12B;
    g_adc.Init.ScanConvMode = DISABLE;
    g_adc.Init.ContinuousConvMode = DISABLE;
    g_adc.Init.DiscontinuousConvMode = DISABLE;
    g_adc.Init.ExternalTrigConvEdge = ADC_EXTERNALTRIGCONVEDGE_RISING;
    g_adc.Init.ExternalTrigConv = ADC_EXTERNALTRIGCONV_T2_TRGO;
    g_adc.Init.DataAlign = ADC_DATAALIGN_RIGHT;
    g_adc.Init.NbrOfConversion = 1u;
    g_adc.Init.DMAContinuousRequests = ENABLE;
    g_adc.Init.EOCSelection = ADC_EOC_SINGLE_CONV;
    if (HAL_ADC_Init(&g_adc) != HAL_OK) { return 1u; }
    ch.Channel = g_pins.adc_channel;
    ch.Rank = 1u;
    ch.SamplingTime = ADC_SAMPLETIME_84CYCLES;
    if (HAL_ADC_ConfigChannel(&g_adc, &ch) != HAL_OK) { return 1u; }
    g_uart.Instance = USART2;
    g_uart.Init.BaudRate = 115200u;
    g_uart.Init.WordLength = UART_WORDLENGTH_8B;
    g_uart.Init.StopBits = UART_STOPBITS_1;
    g_uart.Init.Parity = UART_PARITY_NONE;
    g_uart.Init.Mode = UART_MODE_TX;
    g_uart.Init.HwFlowCtl = UART_HWCONTROL_NONE;
    g_uart.Init.OverSampling = UART_OVERSAMPLING_16;
    return HAL_UART_Init(&g_uart) == HAL_OK ? 0u : 1u;
}
static uint32_t peripherals_init(void)
{
    GPIO_InitTypeDef io = {0};
    TIM_MasterConfigTypeDef master = {0};
    __HAL_RCC_DMA1_CLK_ENABLE(); __HAL_RCC_DMA2_CLK_ENABLE();
    __HAL_RCC_ADC1_CLK_ENABLE(); __HAL_RCC_TIM2_CLK_ENABLE();
    __HAL_RCC_USART2_CLK_ENABLE();
    /* Dedicated reference project ONLY: these reset domains must have no other owner. */
    __HAL_RCC_TIM2_FORCE_RESET(); __HAL_RCC_TIM2_RELEASE_RESET();
    __HAL_RCC_USART2_FORCE_RESET(); __HAL_RCC_USART2_RELEASE_RESET();
    __HAL_RCC_ADC_FORCE_RESET(); __HAL_RCC_ADC_RELEASE_RESET();
    __HAL_RCC_DMA1_FORCE_RESET(); __HAL_RCC_DMA1_RELEASE_RESET();
    __HAL_RCC_DMA2_FORCE_RESET(); __HAL_RCC_DMA2_RELEASE_RESET();
    if (gpio_clock(g_pins.adc_port) != 0u || gpio_clock(g_pins.tx_port) != 0u) { return 1u; }
    io.Pin = g_pins.adc_pin; io.Mode = GPIO_MODE_ANALOG; io.Pull = GPIO_NOPULL;
    HAL_GPIO_Init(g_pins.adc_port, &io);
    io.Pin = g_pins.tx_pin; io.Mode = GPIO_MODE_AF_PP;
    io.Speed = GPIO_SPEED_FREQ_VERY_HIGH; io.Alternate = g_pins.tx_alternate;
    HAL_GPIO_Init(g_pins.tx_port, &io);

    g_adc_dma.Instance = DMA2_Stream0;
    g_adc_dma.Init.Channel = DMA_CHANNEL_0;
    g_adc_dma.Init.Direction = DMA_PERIPH_TO_MEMORY;
    g_adc_dma.Init.PeriphInc = DMA_PINC_DISABLE;
    g_adc_dma.Init.MemInc = DMA_MINC_ENABLE;
    g_adc_dma.Init.PeriphDataAlignment = DMA_PDATAALIGN_HALFWORD;
    g_adc_dma.Init.MemDataAlignment = DMA_MDATAALIGN_HALFWORD;
    g_adc_dma.Init.Mode = DMA_CIRCULAR;
    g_adc_dma.Init.Priority = DMA_PRIORITY_HIGH;
    g_adc_dma.Init.FIFOMode = DMA_FIFOMODE_DISABLE;
    g_adc_dma.Init.MemBurst = DMA_MBURST_SINGLE;
    g_adc_dma.Init.PeriphBurst = DMA_PBURST_SINGLE;
    if (HAL_DMA_Init(&g_adc_dma) != HAL_OK) { return 1u; }
    g_tx_dma.Instance = DMA1_Stream6;
    g_tx_dma.Init.Channel = DMA_CHANNEL_4;
    g_tx_dma.Init.Direction = DMA_MEMORY_TO_PERIPH;
    g_tx_dma.Init.PeriphInc = DMA_PINC_DISABLE;
    g_tx_dma.Init.MemInc = DMA_MINC_ENABLE;
    g_tx_dma.Init.PeriphDataAlignment = DMA_PDATAALIGN_BYTE;
    g_tx_dma.Init.MemDataAlignment = DMA_MDATAALIGN_BYTE;
    g_tx_dma.Init.Mode = DMA_NORMAL;
    g_tx_dma.Init.Priority = DMA_PRIORITY_MEDIUM;
    g_tx_dma.Init.FIFOMode = DMA_FIFOMODE_DISABLE;
    g_tx_dma.Init.MemBurst = DMA_MBURST_SINGLE;
    g_tx_dma.Init.PeriphBurst = DMA_PBURST_SINGLE;
    if (HAL_DMA_Init(&g_tx_dma) != HAL_OK) { return 1u; }
    __HAL_LINKDMA(&g_adc, DMA_Handle, g_adc_dma);
    __HAL_LINKDMA(&g_uart, hdmatx, g_tx_dma);
    g_tim.Instance = TIM2;
    g_tim.Init.Prescaler = 83u;
    g_tim.Init.CounterMode = TIM_COUNTERMODE_UP;
    g_tim.Init.Period = 999u;
    g_tim.Init.ClockDivision = TIM_CLOCKDIVISION_DIV1;
    g_tim.Init.AutoReloadPreload = TIM_AUTORELOAD_PRELOAD_ENABLE;
    if (HAL_TIM_Base_Init(&g_tim) != HAL_OK) { return 1u; }
    master.MasterOutputTrigger = TIM_TRGO_UPDATE;
    master.MasterSlaveMode = TIM_MASTERSLAVEMODE_DISABLE;
    if (HAL_TIMEx_MasterConfigSynchronization(&g_tim, &master) != HAL_OK) { return 1u; }
    return adc_uart_init();
}
/* IRQ-safe short actions ONLY. Caller masks interrupts; no blocking abort here. */
static void short_actions(BatchAction a)
{
    while (a.kind != ACT_NONE) {
        if (a.kind == ACT_ARM) {
            uint32_t bad;
            memset(&g_hw_ticket, 0, sizeof(g_hw_ticket));
            __HAL_TIM_SET_COUNTER(&g_tim, 0u);
            __HAL_TIM_CLEAR_FLAG(&g_tim, TIM_FLAG_UPDATE);
            __DMB();
            bad = HAL_ADC_Start_DMA(&g_adc, (uint32_t *)g_batch.samples,
                                     BATCH_SAMPLES) == HAL_OK ? 0u : 1u;
            if (bad == 0u && HAL_TIM_Base_Start(&g_tim) != HAL_OK) { bad = 1u; }
            batch_arm_result(&g_batch, bad, HAL_GetTick(), &a);
            g_callbacks = bad == 0u ? 1u : 0u;
        } else if (a.kind == ACT_TX) {
            g_hw_ticket = a; /* UART hardware does NOT carry this software ticket. */
            __DMB();
            if (HAL_UART_Transmit_DMA(&g_uart,
                    (uint8_t *)&g_batch.samples[a.half * BATCH_HALF_SAMPLES],
                    (uint16_t)BATCH_HALF_BYTES) != HAL_OK) {
                BatchEvent e = {EV_TX_START_ERROR, HAL_GetTick(), a.session, a.half, a.token};
                g_last_hal_error = g_uart.ErrorCode;
                batch_event(&g_batch, e, &a);
            } else { a.kind = ACT_NONE; }
        } else if (a.kind == ACT_STOP_SOURCE) {
            uint32_t bad;
            g_callbacks = 0u;
            bad = HAL_TIM_Base_Stop(&g_tim) == HAL_OK ? 0u : 1u;
            if ((TIM2->CR1 & TIM_CR1_CEN) != 0u) { bad = 1u; }
            if (bad != 0u) { __HAL_TIM_DISABLE(&g_tim); } /* best effort, not proof */
            batch_stop_result(&g_batch, bad);
            a.kind = ACT_NONE;
        } else { /* ACT_CLEAN is forbidden here; foreground alone performs it. */
            g_callbacks = 0u; __HAL_TIM_DISABLE(&g_tim); return;
        }
    }
}
static void emit(uint32_t kind, uint32_t half, uint32_t token)
{
    uint32_t p = lock();
    if (g_callbacks != 0u) {
        BatchAction a = {0};
        BatchEvent e = {kind, HAL_GetTick(), g_batch.session, half, token};
        batch_event(&g_batch, e, &a);
        short_actions(a);
    }
    unlock(p);
}
static uint32_t cleanup_hardware(void)
{
    uint32_t bad = 0u, i;
    /* Disable only device IRQs: SysTick MUST continue for HAL timeout accounting. */
    irq_enable(0u);
    if (HAL_TIM_Base_Stop(&g_tim) != HAL_OK) { bad = 1u; }
    if ((TIM2->CR1 & TIM_CR1_CEN) != 0u) { __HAL_TIM_DISABLE(&g_tim); bad = 1u; }
    if (HAL_ADC_Stop_DMA(&g_adc) != HAL_OK) { bad = 1u; }
    if (HAL_UART_AbortTransmit(&g_uart) != HAL_OK) { bad = 1u; }
    if ((DMA2_Stream0->CR & DMA_SxCR_EN) != 0u ||
        (DMA1_Stream6->CR & DMA_SxCR_EN) != 0u) { bad = 1u; }
    if (bad != 0u) { return 1u; } /* NO buffer clear, NO restart, IRQs remain disabled. */
    if (HAL_DMA_DeInit(&g_adc_dma) != HAL_OK || HAL_DMA_DeInit(&g_tx_dma) != HAL_OK) { return 1u; }
    if (HAL_DMA_Init(&g_adc_dma) != HAL_OK || HAL_DMA_Init(&g_tx_dma) != HAL_OK) { return 1u; }
    if (HAL_ADC_DeInit(&g_adc) != HAL_OK || HAL_UART_DeInit(&g_uart) != HAL_OK) { return 1u; }
    if (adc_uart_init() != 0u) { return 1u; }
    /* Peripheral flags first, NVIC pending second. No old stream may still generate events. */
    __HAL_ADC_CLEAR_FLAG(&g_adc, ADC_FLAG_OVR | ADC_FLAG_EOC | ADC_FLAG_STRT);
    __HAL_UART_CLEAR_FLAG(&g_uart, UART_FLAG_TC);
    __HAL_TIM_CLEAR_FLAG(&g_tim, TIM_FLAG_UPDATE);
    for (i = 0u; i < 4u; ++i) { HAL_NVIC_ClearPendingIRQ(g_irqs[i]); }
    __DMB();
    return 0u;
}
uint32_t Reference_Init(const ReferencePins *pins)
{
    BatchAction a = {0};
    uint32_t i, p;
    if (pins == NULL || g_ready != 0u) { return 1u; }
    if (pins->supply_mv < 2700u || pins->supply_mv > 3600u ||
        one_pin(pins->adc_pin) == 0u || one_pin(pins->tx_pin) == 0u ||
        pins->adc_channel > ADC_CHANNEL_15 || pins->tx_alternate > 15u) { return 1u; }
    g_pins = *pins;
    HAL_NVIC_SetPriorityGrouping(NVIC_PRIORITYGROUP_4);
    if (clock_init() != 0u || peripherals_init() != 0u) { return 1u; }
    for (i = 0u; i < 4u; ++i) { HAL_NVIC_SetPriority(g_irqs[i], 5u, 0u); }
    if (batch_init(&g_batch, 64u) == 0u) { return 1u; }
    p = lock();
    irq_enable(1u);
    if (batch_start(&g_batch, &a) == 0u) { unlock(p); return 1u; }
    short_actions(a);
    g_ready = 1u;
    i = g_batch.mode == MODE_RUNNING ? 0u : 1u;
    unlock(p);
    return i == 0u ? 0u : 2u; /* 2: initialized, but first arm faulted; service/recovery remain usable. */
}
void Reference_Service(void)
{
    uint32_t p, bad;
    BatchAction a = {0};
    if (g_ready == 0u) { return; }
    emit(EV_POLL, 0u, 0u);
    p = lock();
    if (g_recover == 0u || g_batch.mode != MODE_FAULT) { unlock(p); return; }
    g_recover = 0u;
    g_callbacks = 0u;
    if (batch_recover(&g_batch, &a) == 0u) { unlock(p); return; }
    unlock(p);
    bad = cleanup_hardware(); /* Main context with SysTick running, NEVER inside an IRQ. */
    p = lock();
    batch_cleanup_result(&g_batch, bad, &a);
    if (bad == 0u) { irq_enable(1u); }
    short_actions(a);
    unlock(p);
}
void Reference_RequestRecovery(void)
{
    uint32_t p = lock();
    if (g_ready != 0u && g_batch.mode == MODE_FAULT) { g_recover = 1u; }
    unlock(p);
}
void Reference_GetDiag(ReferenceDiag *out)
{
    uint32_t p = lock();
    out->mode = g_batch.mode; out->session = g_batch.session;
    out->current_fault = g_batch.current_fault; out->first_fault = g_batch.first_fault;
    out->stop_ok = g_batch.stop_ok; out->stop_errors = g_batch.stop_errors;
    out->cleanup_errors = g_batch.cleanup_errors;
    out->ht_count = g_ht; out->tc_count = g_tc; out->tx_count = g_tx;
    out->error_count = g_error; out->last_hal_error = g_last_hal_error;
    unlock(p);
}
void HAL_ADC_ConvHalfCpltCallback(ADC_HandleTypeDef *h)
{ if (h == &g_adc) { ++g_ht; emit(EV_HT, 0u, 0u); } }
void HAL_ADC_ConvCpltCallback(ADC_HandleTypeDef *h)
{ if (h == &g_adc) { ++g_tc; emit(EV_TC, 1u, 0u); } }
void HAL_UART_TxHalfCpltCallback(UART_HandleTypeDef *h)
{ (void)h; /* Progress only: NEVER release the batch here. */ }
void HAL_UART_TxCpltCallback(UART_HandleTypeDef *h)
{ if (h == &g_uart) { ++g_tx; emit(EV_TX_DONE, g_hw_ticket.half, g_hw_ticket.token); } }
void HAL_ADC_ErrorCallback(ADC_HandleTypeDef *h)
{ if (h == &g_adc) { ++g_error; g_last_hal_error = h->ErrorCode; emit(EV_IO_ERROR, 0u, 0u); } }
void HAL_UART_ErrorCallback(UART_HandleTypeDef *h)
{ if (h == &g_uart) { ++g_error; g_last_hal_error = h->ErrorCode; emit(EV_IO_ERROR, 0u, 0u); } }
void DMA2_Stream0_IRQHandler(void) { HAL_DMA_IRQHandler(&g_adc_dma); }
void DMA1_Stream6_IRQHandler(void) { HAL_DMA_IRQHandler(&g_tx_dma); }
void ADC_IRQHandler(void) { HAL_ADC_IRQHandler(&g_adc); }
void USART2_IRQHandler(void) { HAL_UART_IRQHandler(&g_uart); }
void SysTick_Handler(void) { HAL_IncTick(); }