AutoFilm-ESP32/docs/megaplans/audit/A01-machine-timing-queue.md

A01 — app_machine deadline fix + FreeRTOS event queue + host queue shim

STATUS: DONE DEPENDS: A00

READ: this file, docs/megaplans/AUDIT-MEGAPLAN.md, docs/audit_remediation_plan.md items 1–2, components/app_machine/app_machine.c, tests/host/CMakeLists.txt

Context: the working tree already carries uncommitted fixes for items 1–2 and the item-3 s_auto_advance = true flip. This phase lands items 1–2 only; the flag stays false until A02. The queue change adds #include "freertos/queue.h" to app_machine.c, which the host test build cannot resolve — a shim is required.

IN:

1. app_machine.c deadline fix (keep from working tree): start_running(void) takes no now_ms; sets s_remaining_ms = time_s * 1000, s_have_deadline = false, s_resume_pending = true. First app_machine_tick in ST_RUNNING computes s_deadline_ms = now_ms + s_remaining_ms from real uptime. app_machine_handle_cmd calls start_running() with no args.
2. app_machine.c cleanup: revert s_auto_advance to false; restore #define AGITATE_RPM 60u; remove the duplicate #define UI_EVT_QUEUE_LEN 16 (already defined via ui_cmd.h).
3. app_machine.c event queue (keep from working tree): static QueueHandle_t s_evtq; emit() does xQueueSend(s_evtq, &ev, 0) when non-NULL; app_machine_last_event() does xQueueReceive(s_evtq, out, 0) == pdTRUE. In app_machine_init: if (s_evtq == NULL) { s_evtq = xQueueCreate(UI_EVT_QUEUE_LEN, sizeof(ui_evt_t)); } else { xQueueReset(s_evtq); } — host tests re-init repeatedly and stale events must not leak between inits.
4. components/app_machine/CMakeLists.txt: add freertos to PRIV_REQUIRES (explicit dependency for freertos/queue.h).
5. New host shim so test_machine keeps compiling the same app_machine.c:
   • tests/host/freertos/FreeRTOS.h — BaseType_t, UBaseType_t, TickType_t, pdTRUE, pdFALSE, pdPASS, pdMS_TO_TICKS.
   • tests/host/freertos/queue.h — QueueHandle_t + prototypes for xQueueCreate, xQueueSend, xQueueReceive, xQueueReset.
   • tests/host/freertos/queue.c — malloc'd ring buffer; xQueueSend returns pdFALSE (drop) when full; xQueueReceive returns pdFALSE when empty; xQueueReset clears.
   • tests/host/CMakeLists.txt — add freertos/queue.c to the test_machine sources (tests/host is already on its include path, so "freertos/FreeRTOS.h" resolves to the shim).
6. Behaviour must be identical for host tests: all existing test_machine.c cases pass unchanged (auto_advance still false).

OUT: s_auto_advance = true (A02), TWDT setup (A03), hal_temp internals (A04), any UI change.

FORBIDDEN: committing the auto-advance flag; changing recipe values; Arduino types; deleting or weakening host test assertions.

VERIFY:

cmake -S tests/host -B build/host && cmake --build build/host && ctest --test-dir build/host --output-on-failure

All green. Firmware builds run in CI on push.

COMMITS (order matters — every commit must compile on host):

1. Add FreeRTOS queue shim for host tests (shim alone; old code doesn't include the headers yet — harmless)
2. Fix step deadline to derive from real uptime
3. Replace machine event ring with FreeRTOS queue

Stage hunks per concern (git add -p or re-apply in order) — the dirty file combines all three changes plus the A02 flag.

DoD checkboxes:

• start_running takes no now_ms; deadline set on the first RUNNING tick.
• emit/app_machine_last_event go through s_evtq; app_machine_init creates or resets the queue.
• s_auto_advance still false.
• Host ctest green with zero test changes.
• STATUS → DONE here and in the megaplan table.