myxce/.kiro/specs/scheduler-controller-msg-gap/requirements.md

# Requirements: scheduler-controller-msg-gap

> Generated: 2026-05-11T01:34:00-07:00
> Updated: 2026-05-11T02:00:00-07:00
> Feature: scheduler-controller-msg-gap
> Status: Requirements Generated

## Overview

Analyze the codebase to find gaps in the scheduler's handling of controller messages — missing message types, unhandled edge cases, or incomplete message processing paths.

## Codebase Analysis Summary

The scheduler (`src/scheduler/src/handler.c`) receives controller messages through the `scheduler_req_handler` dispatcher, which handles two top-level opcodes:

- **OPCode_push** — carries ConfigData or Dataset (`datamsg`) messages. Raw `pushmsg` packets are reassembled into `datamsg` by the `vtask_entry()` assembly layer in `src/lib/xcectx.c` (lines 93–106); the handler never sees individual `pushmsg` fragments.
- **OPCode_notify** — carries NotifyData event messages

The controller (`src/controller/sched.c`) sends six NotifyData event types and two Data table types. The scheduler's handler has **6 gap locations** where the case is present but stubbed out or empty-bodied. The `Request_body_pushmsg` branch in `scheduler_req_handler` (which calls `sched_handle_jobpush`/`sched_handle_workerpush`) is dead code — it can never be reached because `vtask_entry` rewrites all `pushmsg` into `datamsg` before invoking the handler.

## Requirements

### Requirement 1: Resource data message handling

The scheduler SHALL process `Data_data_resources` dataset messages received from the controller. Upon receipt, the system SHALL update the internal resource catalog (resource name, type, flags, ordering type, interval) in the scheduler's resource manager (`sched->resmgr`), reconciling additions, removals, and modifications against the existing set.

The scheduler SHALL process `Data_data_resvals` dataset messages received from the controller. Upon receipt, the system SHALL update the shared resource value array (`sched->sharedInst`) with the new values indexed by position, and SHALL reset the `sharedInUse` tracking array for the next scheduling session.

**Acceptance criteria:**
- EARS-UB-1.1: WHEN the scheduler receives a dataset with `table == Data_data_resources`, THEN the system shall add or update each resource in `sched->resmgr`
- EARS-UB-1.2: WHEN the scheduler receives a dataset with `table == Data_data_resvals`, THEN the system shall update `sched->sharedInst` at each value's index position
- EARS-UB-1.3: WHEN either handler encounters a NULL element in the dataset rows, THEN the system shall skip that element and continue processing remaining rows
- EARS-UB-1.4: WHEN either handler encounters a memory allocation failure, THEN the system shall return `-ENOMEM` and free any partially allocated structures

### Requirement 2: Dead code removal — pushmsg handler branches

The scheduler SHALL remove the dead `Request_body_pushmsg` branch in `scheduler_req_handler` and the stub functions `sched_handle_jobpush` and `sched_handle_workerpush`. These paths can never execute because the `vtask_entry()` assembly layer in `src/lib/xcectx.c` rewrites all `pushmsg` packets into `datamsg` before invoking the request handler.

**Acceptance criteria:**
- EARS-UB-2.1: WHEN `scheduler_req_handler` is compiled, THEN the `Request_body_pushmsg` case and its two child branches (job/worker push) shall not exist
- EARS-UB-2.2: WHEN the scheduler is linked, THEN the symbols `sched_handle_jobpush` and `sched_handle_workerpush` shall not be present in the binary

### Requirement 3: NotifyData event handling for job updates

The scheduler SHALL process `NotifyData_data_schedUpdateJob` notify messages beyond the current trace-log-only behavior. Upon receipt, the system SHALL locate the job in `sched->jobs` by jobid, update the job's mutable fields (state, priority, queue, resource request) from the notify payload, and invoke `plugin_job_update` to notify plugins of the change.

**Acceptance criteria:**
- EARS-UB-3.1: WHEN the scheduler receives a notify with `event == NotifyData_data_schedUpdateJob`, THEN the system shall find the existing job by jobid and update its mutable fields
- EARS-UB-3.2: WHEN the jobid in the update notify does not match any existing job (i.e., the job was never pushed via the initial dataset bulk load), THEN the system shall return `-ENOENT` — jobs are created only via the `Data_data_schedjobs` dataset path, never via notify
- EARS-UB-3.3: WHEN the update payload carries job data that is NULL, THEN the system shall return `-EINVAL`

### Requirement 4: NotifyData event handling for queue updates

The scheduler SHALL process `NotifyData_data_schedUpdateQueue` notify messages from the controller. Upon receipt, the system SHALL locate the queue in `sched->queues` by name and update its status, priority, accept_interval, sched_delay, and resource request fields from the notify payload.

**Acceptance criteria:**
- EARS-UB-4.1: WHEN the scheduler receives a notify with `event == NotifyData_data_schedUpdateQueue`, THEN the system shall find the existing queue by name and update its mutable configuration fields
- EARS-UB-4.2: WHEN the queue name in the update notify does not match any existing queue (i.e., the queue was never loaded via the initial config push), THEN the system shall return `-ENOENT` — queues are created only via the `Conf4Sched` config path, never via notify
- EARS-UB-4.3: WHEN the update payload carries queue data that is NULL, THEN the system shall return `-EINVAL`

### Requirement 5: NotifyData event handling for resource value updates

The scheduler SHALL process `NotifyData_data_schedUpdateResvals` notify messages from the controller. Upon receipt, the system SHALL iterate the `xce_resval_list_t` payload, and for each resource value, update the per-worker `resvals` array on the named worker, matching by host name.

**Acceptance criteria:**
- EARS-UB-5.1: WHEN the scheduler receives a notify with `event == NotifyData_data_schedUpdateResvals`, THEN the system shall update each named worker's `resvals` array with the new values
- EARS-UB-5.2: WHEN a named host in the updates does not correspond to any known worker, THEN the system shall skip that update entry and continue processing remaining entries
- EARS-UB-5.3: WHEN the update payload carries zero resource values, THEN the system shall return 0 without modifying state

### Requirement 6: NotifyData event handling for job resource usage

The scheduler SHALL process `NotifyData_data_schedJobRusages` notify messages from the controller. Upon receipt, the system SHALL locate the job by jobid, store the resource usage data (`xce_sched_job_rusages_t`) on the job object, and invoke `plugin_job_rusage_update` to notify plugins of the usage change.

**Acceptance criteria:**
- EARS-UB-6.1: WHEN the scheduler receives a notify with `event == NotifyData_data_schedJobRusages`, THEN the system shall store the usage data on the matching job
- EARS-UB-6.2: WHEN the jobid in the update does not match any existing job, THEN the system shall return `-ENOENT` without modifying state
- EARS-UB-6.3: WHEN the rusage payload is NULL, THEN the system shall return `-EINVAL`

### Requirement 7: Error handling consistency

The scheduler SHALL return meaningful error codes from all message handlers that enable the controller to distinguish between transient failures (ENOMEM) and permanent protocol errors (EINVAL, ENOENT). The scheduler's main loop in `sched_update()` SHALL log a WARN-level message when a handler returns a non-zero error code, including the offending opcode and sub-type for operational debugging.

**Acceptance criteria:**
- EARS-UB-7.1: WHEN a handler returns a non-zero error code, THEN `sched_update()` shall emit a WARN log including the `xce_sched_op_t` value and the error code
- EARS-UB-7.2: WHEN an unknown notify event type is received, THEN the handler shall return `-EINVAL` (already implemented — verify non-regression)
- EARS-UB-7.3: WHEN a push message arrives with an unknown `body_which` tag, THEN the handler shall return `-EINVAL` (already implemented — verify non-regression)

### Requirement 8: Human-readable message type names in logs

The scheduler SHALL log message type identifiers using symbolic names rather than numeric values. The existing helpers in `src/lib/helper.c` — `xce_request_op_name()`, `xce_request_msg_name()`, and `xce_dataset_table()` — already provide name lookups for OPCode, Request body tag, and Data table type. A new `xce_notify_event_name(int)` function SHALL be added to cover the NotifyData event type enum. All TRACE, DEBUG, INFO, and WARN messages in `handler.c` that reference these enums SHALL use these name-lookup functions instead of printing numeric values.

**Acceptance criteria:**
- EARS-UB-8.1: WHEN `scheduler_req_handler` logs a message that includes an opcode, THEN the log shall call `xce_request_op_name()` to show the symbolic name (e.g., `"push"`) rather than the numeric value
- EARS-UB-8.2: WHEN `sched_handle_dataset` logs a message that includes a data table type, THEN the log shall call `xce_dataset_table()` to show the symbolic name (e.g., `"schedjobs"`) rather than the numeric value (currently `TRACE("%s table = %d", ...)`)
- EARS-UB-8.3: WHEN `sched_handle_notify` logs a message that includes a notify event type, THEN the log shall call `xce_notify_event_name()` to show the symbolic name rather than the numeric value
- EARS-UB-8.4: WHEN `xce_notify_event_name()` receives a numeric value that does not correspond to a known NotifyData enum constant, THEN it shall return `"UNKNOWN(%d)"` with the numeric value substituted (matching the pattern used by the existing helpers)
- EARS-UB-8.5: WHEN `sched_update()` emits a WARN log for a handler error (per Requirement 7), THEN the log shall include symbolic names via the appropriate helper function

## Non-Requirements

The following areas are intentionally excluded from this specification:
- **New protocol message types** — only existing, already-defined message types in `controller.capnp` are in scope
- **Controller-side changes** — only the scheduler's inbound message handling is in scope
- **Plugin implementation details** — plugin update functions are called but not modified
- **Bulk (Dataset) job/worker push already works** — the `Data_data_schedjobs` and `Data_data_schedworkers` cases in `sched_handle_dataset` already delegate to `sched_on_jobs`/`sched_on_workers`
- **`pushmsg` handler path** — the `Request_body_pushmsg` branch in `scheduler_req_handler` and the functions `sched_handle_jobpush`/`sched_handle_workerpush` are dead code; the `vtask_entry()` assembly layer in `src/lib/xcectx.c` rewrites all `pushmsg` into `datamsg` before the handler is called, so incremental push handling is never needed

## Next Step

Run `/kiro:spec-design scheduler-controller-msg-gap` to proceed to design phase.