Design: own the synchronization object state; wrap only the scheduler (notification-backed k_sem first)

[swoisz]

Strategic direction distilled from the corruption-family investigations (#18, #21, #22, #38): every place Boreas owns the object state machine (k_work's dlist+sem+lock, the k_timer linux dispatcher), Zephyr semantics came cheap and the caller-owned-memory contract was enforceable. Every place we wrap a FreeRTOS object whole, we inherit the impedance mismatch — kernel wait-lists threaded through caller-owned control blocks, no severance signal, semantics ceilings — and pay for it in protocol PRs.

Principle: wrap the scheduler, own the synchronization state. Tasks/blocking/tick must come from FreeRTOS (that is ESP-IDF's ground truth). Synchronization object state (counts, bits, waiter queues) is cheap to own, and direct-to-task notifications are the clean seam: notification state lives inside the TCB, kernel-owned — nothing of ours ever enters a kernel list from caller memory, structurally eliminating the dead-frame/dangling-node bug family for that object.

Per-primitive verdict

Primitive	Verdict	Rationale
k_thread	wrap forever	tasks ARE the scheduler; the #18 lifecycle protocol is the right shape
k_mutex	keep wrapping	FreeRTOS priority inheritance is the whole value; reimplementing PI correctly is the hardest primitive in the catalog
k_sem	own it (notification-backed)	see below — three wins attached
k_event	likely own it second	currently on xEventGroupCreateStatic (k_event.c) — EventBits_t reserves the top 8 bits, capping usable events at 24 vs Zephyr's 32: a hard semantics ceiling, and the own-impl is structurally identical to the sem (state word + waiter list + notifications)
k_msgq	defer	FreeRTOS queues do the copy-ring + dual-wait-queue job well; revisit only if purge/peek parity or another lifetime bite forces it
k_timer, k_work	already own state	the existing proof this approach pays

k_sem, notification-backed (first work item)

{count, limit, waiter sys_dlist, portMUX} in the Boreas struct; block via xTaskNotifyWait on a dedicated index; give pops a waiter under the lock and xTaskNotifyGives its handle. Buys in one move:

• K_SEM_DEFINE is not a static initializer (requires runtime k_sem_init) #26 solved for free: K_SEM_DEFINE becomes a true compile-time initializer (plain struct, no runtime xSemaphoreCreateCountingStatic)
• Real k_sem_reset semantics: upstream wakes waiters with -EAGAIN; FreeRTOS cannot express this (today we silently drain)
• Removes the give-from-other-context stack-allocation caveat (zkernel README design-principle section) for sems
• Priority-ordered wakeup for exact upstream behavior
• A provably-correct base for the k_timer: remaining semantic divergences from upstream (remaining_get type, status_sync busy-poll) #28 k_timer_status_sync rewrite

Spike first (blocking question): task-notification index allocation. Some ESP-IDF internals use notifications (index 0); a dedicated index needs configTASK_NOTIFICATION_ARRAY_ENTRIES > 1 and a project-wide convention. Verify availability/configurability on both silicon and the linux port before committing to the design.

Sequencing

One primitive per PR via the established loop (linux suite + S3 + both-IDF CI). The #21 corruption regression harness exists precisely to validate this class of change. k_sem first; evaluate k_event after it lands clean; stop there unless something bites.

[swoisz]

Related: #22 (the object-lifetime principle this implements structurally), #26 (solved for free by the notification-backed k_sem), #28 (k_timer_status_sync rewrite gains a provably-correct base), #21/#18 (the bug family this eliminates per-object). Evidence trail: zkernel README design-principle section + the #21 investigation.

[swoisz]

Notification-index spike: PASSED. The design is viable on both targets:

• CONFIG_FREERTOS_TASK_NOTIFICATION_ARRAY_ENTRIES exists (range 1–32, default 1); per-task cost is one word per entry.
• The indexed APIs (xTaskNotifyWaitIndexed, vTaskNotifyGiveIndexedFromISR, …) live in FreeRTOS-Kernel/include/freertos/task.h — the same kernel tree serving both silicon and the linux port.
• Index-0 collisions are real: esp_ipc, pthread, usb/hcd_dwc, and the esp_eth MAC drivers all use default-index notifications. Boreas reserves index 1, enforced by a compile-time #error when configTASK_NOTIFICATION_ARRAY_ENTRIES < 2 (with the sdkconfig line to add in the message).

Proceeding with the notification-backed k_sem implementation. Protocol notes: waiter nodes live on the waiter's stack and are unlinked under the sem lock before k_sem_take returns (synchronous severance by construction); the timeout-vs-give race uses the consume-the-in-flight-give pattern proven in the k_work sync-slot work (#38); k_sem_reset wakes waiters with -EAGAIN (upstream semantics FreeRTOS could not express); K_SEM_DEFINE becomes a true compile-time initializer (closing the #26 gap and retiring the Xtensa .init_array caveat).

[swoisz]

Arc complete: k_sem converted in #41, k_event in #42 (full 32-bit events + upstream set/post/reset/timeout semantics). Per the verdict table, k_mutex and k_msgq deliberately stay FreeRTOS-wrapped. Shared scaffolding shipped: zkernel_internal.h (locks + reserved notification index), sdkconfig.boreas. Follow-up hardening (stress coverage for the handled races + two doc notes, from an independent design review) is tracked in the local TODO and will land as a test-focused PR.