feat(scheduler-core): build normal-mode driver event translation path (task 5.1)

Adds driver.h/driver.c: xce_sched_driver_translate_pending_events()
drains core->pend_updates via the existing dataq-swap pattern (same
mechanism sched_update() uses), translates all 10 xce_sched_update_
request_t op types into the matching xce_core_event_t, and pushes the
batch through xce_core_push_events(). Scoped to xce_sched_core_t*
alone -- pend_updates already lives on core since task 4.1, and this
task is translation-only (no decision publishing, no mode-selection,
no recording -- all later work). handler.c (the enqueue side) is
untouched. First task in Group 5 (Core: Normal-Mode Driver).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019dw5WnN3DXStaEaPYfACU1

src/scheduler/include/driver.h

@@ -0,0 +1,55 @@
+#if !defined(_DRIVER_H_)
+
+#define _DRIVER_H_ 1
+
+#include "core.h"
+
+/*
+ * driver.h - normal-mode driver, controller event translation (scheduler-
+ * core spec, task 5.1, Req 5 AC 8 / AC 9). NEW file per design.md's File
+ * Structure Plan (`driver.h` bullet: "NEW (Phase 2): xce_sched_driver_t
+ * (normal-mode)"). This task deliberately does NOT define the full
+ * `xce_sched_driver_t` struct design.md sketches (embedding `xcecli_ctx_t`,
+ * `cluster_cfg`, recording-control fields) -- that struct's fields
+ * (decision publishing, `record_dir`/`record_file`, etc.) belong to task
+ * 5.2 and Phase 3's recording work, none of which this task implements or
+ * needs. See driver.c's own header comment for the full scoping rationale:
+ * this task's translation logic only needs an `xce_sched_core_t*` (which
+ * already carries `pend_updates[2]` as of task 4.1), not a driver-level
+ * struct wrapping one. Task 5.2 extends this header with the full
+ * `xce_sched_driver_t` and `sched_driver_run()` when it wires this function
+ * into a live driver loop -- nothing here needs to change for that.
+ */
+
+/*
+ * xce_sched_driver_translate_pending_events - Req 5 AC 8 ("Driver event
+ * queue" -- the driver buffers controller events between scheduling
+ * rounds) and Req 5 AC 9's translation half ("receive capnp push/notify
+ * messages from the controller, translate each to the corresponding core
+ * event type, and invoke the core's event push interface" -- decision
+ * publishing, AC 9's other half, is task 5.2's job, not this function's).
+ *
+ * Drains `core->pend_updates` -- the SAME existing dataq-swap-and-dequeue
+ * mechanism scheduler.c's `sched_update()` already uses, populated by the
+ * unchanged `handler.c` capnp push/notify enqueue path -- translating every
+ * dequeued `xce_sched_update_request_t` into the matching `xce_core_event_t`
+ * (see driver.c's op-type -> event-type table), accumulating the whole
+ * batch, and pushing it through `xce_core_push_events()` exactly once.
+ *
+ * Only valid to call between scheduling sessions (the same precondition
+ * `xce_core_push_events()` itself documents, core.h) -- this function does
+ * not drive a scheduling session and does not decide WHEN it is safe to
+ * call; that session-boundary orchestration (BEGIN_ROUND) is a later task's
+ * responsibility (see this file's header comment).
+ *
+ * Returns the number of events translated and pushed (>= 0, may be 0 if
+ * nothing was pending) on success. Returns a negative errno on failure:
+ * -EINVAL if `core` is NULL or its `pend_updates` queues are not
+ * initialized; -ENOMEM on an allocation failure while growing the
+ * translation batch (rare, defensive path); or `xce_core_push_events()`'s
+ * own negative return (e.g. -EBUSY if a session was unexpectedly active)
+ * passed straight through.
+ */
+extern int xce_sched_driver_translate_pending_events(xce_sched_core_t* core);
+
+#endif