/*
 * test_repl_help.c - contract test for the interactive simulation REPL's
 * Help & Breakpoint Discoverability component (scheduler-sim-repl-verbosity
 * spec, task 9.1, Requirements 7.1-7.4): `help`'s listing groups commands
 * into four labeled sections, aligns every command's description to one
 * consistent column position throughout (not independently hand-padded per
 * line), lists `info config` together with the other `info` subcommands in
 * the state-inspection section, lists `set units` alongside `set output`/
 * `set verify` in the snapshot-and-parameters section, and
 * enumerates the complete set of valid `break <EVENT_TYPE>` values on its
 * `break` line. `break`'s own unrecognized-event-type error message
 * (Requirement 7.5) is NOT covered here -- that lives in the sibling
 * test_repl_breakpoints_inspection.c per design.md's own file-placement
 * guidance for this component.
 *
 * Split into its own file rather than appended to
 * test_repl_execution_control.c -- see design.md's own
 * "**Correction (post-review, task 2.1)**" note (that file was already 949
 * lines, over this project's 800-line cap, before this task's own tests
 * would have been added) and the analogous
 * "**Correction (post-review, task 3.1)**"/"**Correction (post-review, task
 * 8.1)**" notes that already split test_repl_event_echo.c/
 * test_repl_resource_table.c out of related files for the identical reason.
 * This file duplicates (rather than shares via a new header) the specific
 * small fixture helpers it needs, following this file family's established
 * convention -- same pattern test_repl_event_echo.c's own header comment
 * documents.
 *
 * Every test below drives `repl_print_help()` (repl.c, `static void`,
 * signature `void(void)`) DIRECTLY, no `xce_sched_sim_driver_t`/replay
 * fixture required -- `help` prints a fixed listing with no dependency on
 * simulation state, so the usual capnp-fixture/fork/waitpid machinery this
 * file family's other siblings need is unnecessary here. The white-box
 * #include set below is still the SAME full set those siblings use, because
 * repl.c itself (pulled in whole) transitively references symbols defined
 * across core.c/sim.c/sim_loop.c/repl_break.c/repl_info.c/repl_params.c/etc.
 * at link time, even though this file's own tests call none of them.
 *
 * THIS TASK (9.1) IS RED-PHASE ONLY: `repl_print_help()` (repl.c) still
 * prints one flat, hand-padded, unlabeled list today, with `info config`
 * appended last (disconnected from its `info` siblings) and no `break`
 * event-type listing at all -- see repl.c's current lines 248-273. Every
 * test below therefore fails its own runtime assertions against today's
 * code (missing section headers, inconsistent column alignment, `info
 * config` outside the state-inspection bounds, and no BP_KIND_TABLE tokens
 * on the `break` line), while still compiling and linking cleanly, since
 * every symbol referenced already exists today.
 *
 * Assumed literal section-header text this file pins (design.md's own
 * "Help & Breakpoint Discoverability" component, Responsibilities &
 * Constraints): "Execution Control", "Breakpoints", "State Inspection",
 * "Snapshot & Parameters" -- the exact four labels design.md itself names
 * for task 9.2 to implement against. Per-command usage/argument text (e.g.
 * "info job <jobid>", "break <EVENT_TYPE> [key=value ...]") is assumed
 * unchanged from today's repl.c (Requirement 7.6: no command's argument
 * parsing changes) -- only used for the NEW "set units" line is exact
 * argument syntax deliberately NOT pinned (existence and section placement
 * only), since task 9.1 predates task 9.2's implementation choice of its
 * exact wording.
 */
#include <errno.h>
#include <limits.h>
#include <stdatomic.h>
#include <stdbool.h>
#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <sys/wait.h>
#include <unistd.h>

#include <unity/unity.h>

#include "controller.capnp.h"
#include "kvmgr.h"
#include "scheduler.h"
#include "xstring.h"

/* Pull in the real functions under test into this TU (white-box #include,
 * same convention as test_repl_execution_control.c/test_repl_event_echo.c/
 * test_repl_resource_table.c). */
#include "../src/core.c"
#include "../src/core_clock.c"
#include "../src/core_events.c"
#include "../src/core_session.c"
#include "../src/decision.c"
#include "../src/plugin.c"
#include "../src/plugins/builtin_fcfs.c"
#include "../src/recording.c"
#include "../src/recording_session.c"
#include "../src/repl.c"
#include "../src/repl_fmt.c"
#include "../src/repl_rollup.c"
#include "../src/repl_break.c"
#include "../src/repl_info.c"
#include "../src/repl_params.c"
#include "../src/sim.c"
#include "../src/sim_loop.c"
#include "../src/sim_picker.c" /* bug-1567: sched_sim_driver_run() now calls sim_bootstrap_picker() (sim_loop.c-cap sibling) as an extern -- undefined reference at link time otherwise */
#include "../src/sim_limit.c" /* bug-1825: sched_sim_driver_run() now also calls sim_bootstrap_limit_plugin() (sim_loop.c-cap sibling, sim_picker.c's own bug-1567 precedent) as an extern -- undefined reference at link time otherwise */
#include "../src/sim_record.c"
#include "../src/sim_verify.c"
#include "../src/snapshot.c"
#include "../src/snapshot_load.c"
#include "../src/snapshot_wire.c"

void kill_sched_job(void* arg) { (void)arg; }
void kill_sched_queue(void* arg) { (void)arg; }
void kill_sched_worker(void* arg) { (void)arg; }
void kill_sched_user(void* arg) { (void)arg; }
void kill_sched_project(void* arg) { (void)arg; }
void kill_sched_resval(xce_val_t* val) { (void)val; }

/* repl_info.c (scheduler-sim-diagnostics spec, task 2.1) now calls
 * limit_get_configured_limits() (plugins/limit.c, not part of this TU) to
 * resolve `info limit`'s name/all argument -- link-satisfying stub only,
 * same rationale as kill_sched_job()/kill_sched_resval() above; this
 * file's own fixtures never register the limit plugin, so NULL
 * (limit_get_configured_limits()'s own documented "plugin absent" return)
 * is also the behaviorally correct answer here, not just a link
 * placeholder. repl_info_limit() itself is not yet wired into
 * repl_cmd_info() (task 4), so no test in this file can reach it anyway. */
var limit_get_configured_limits(xce_sched_core_t* core)
{
    (void)core;
    return NULL;
}

/* scheduler-sim-diagnostics spec, task 3.1: repl_info.c now also calls
 * limit_get_usage_instances() (plugins/limit.c, not part of this TU) to
 * read a limit's live usage instances -- identical link-satisfying stub,
 * same rationale as limit_get_configured_limits() immediately above; this
 * file's own fixtures never register the limit plugin, so NULL
 * (limit_get_usage_instances()'s own documented "plugin absent" return) is
 * also the behaviorally correct answer here, not just a link placeholder. */
var limit_get_usage_instances(xce_sched_core_t* core)
{
    (void)core;
    return NULL;
}

/* scheduler-sim-diagnostics spec, task 6 (bug-1825): sim_loop.c's
 * sched_sim_driver_run() now also calls sim_bootstrap_limit_plugin()
 * (sim_limit.c, pulled into this TU via the #include above), which in
 * turn calls limit_new_plugin() (plugins/limit.c, not part of this TU) --
 * identical link-satisfying stub rationale as limit_get_configured_
 * limits()/limit_get_usage_instances() immediately above. Returning NULL
 * here is also the behaviorally correct answer, not just a link
 * placeholder: sim_bootstrap_limit_plugin() already handles a NULL
 * limit_new_plugin() return gracefully (logs an ERROR, registers nothing,
 * returns) -- the exact same "out of memory" path sim_bootstrap_picker()
 * (sim_picker.c) takes for a NULL builtin_fcfs_new_plugin() -- so this
 * file's fixtures simply end up with no limit plugin registered, same
 * observable state as before this task. */
xce_sched_plugin_t* limit_new_plugin(void)
{
    return NULL;
}

/* limit_seed_config() (plugins/limit.c, not part of this TU) -- bug-1825
 * remediation round 2's new honestly-typed config-seed entry point.
 * sim_bootstrap_limit_plugin() (sim_limit.c) only calls it after
 * plugin_register_core() has already succeeded against a real, non-NULL
 * limit_new_plugin() plugin -- unreachable in this file since the
 * limit_new_plugin() stub immediately above always returns NULL, but the
 * symbol must still resolve at link time. Same link-satisfying-stub
 * rationale as limit_new_plugin() immediately above. */
int limit_seed_config(xce_sched_plugin_t* plugin, xce_sched_core_t* core,
                      xce_conf4sched_t* config)
{
    (void)plugin;
    (void)core;
    (void)config;
    return 0;
}

/* resource-accounting.md's reconciliation (resource.c, not linked here --
 * this file only #includes core_events.c). core_events.c's
 * XCE_CORE_EVENT_JOB_RUSAGE handler calls this whenever job->accounts !=
 * NULL; link-satisfying stub only, same rationale as every other stub in
 * this block (see test_job_update.c's identical stub). */
int sched_reconcile_job_resource_usage(xce_sched_core_t*  c,
                                       xce_job_account_t* a,
                                       xce_job_rusages_t* r)
{
    (void)c; (void)a; (void)r; return 0;
}

void sched_worker_release_host_ctx(xce_sched_worker_t* w) { (void)w; }

int sched_fill_limit_requests(xce_sched_alloc_req_t* alloc_req,
                              xlist_t* limits, xlist_t* rusages, int nhosts,
                              int nslots)
{
    (void)alloc_req;
    (void)limits;
    (void)rusages;
    (void)nhosts;
    (void)nslots;
    return 0;
}

/* sched_sim_driver_run()'s (sim_loop.c, scheduler-sim-decision-parity task
 * 2.1) new round-boundary call to the relocated sched_account_jobs()
 * (core.h) -- a no-op stand-in here since this file does not link
 * scheduler.c/resource.c, same rationale test_sim_equivalence.c's own copy
 * documents. Never actually invoked by this file's own tests (they call
 * repl_print_help() only), but required for the TU to link -- sim_loop.c
 * (pulled in whole by the white-box #include set above) references it. */
int sched_account_jobs(xce_sched_core_t* core)
{
    (void)core;
    return 0;
}

/* bug-1836 (scheduler-driver-equivalence fix, Recorded-Decision
 * Reconciliation capacity gate): link-satisfying stubs, mirroring this
 * file's existing sched_account_jobs() no-op precedent immediately above --
 * sim_loop.c's sim_reconcile_unaccounted_jobs() now also calls
 * sched_check_host_satisfy()/sched_check_shared_satisfy() (resource.c) to
 * re-validate a recorded decision against live capacity, and
 * sched_charge_account() (resource.c) to keep that check's own view of
 * capacity up to date across multiple candidates in the same round. This
 * file never exercises real resource contention (same rationale as the
 * existing sched_account_jobs()/sched_ctx_get_uncomit_host() no-ops), so
 * the satisfy checks trivially always succeed and the charge call is a
 * no-op. */
int sched_check_host_satisfy(xce_sched_core_t* core, xce_sched_worker_t* w,
                             xvec_t* uncomitted, xvec_idval_t* wanted,
                             xvec_idval_t* unmeet)
{
    (void)core;
    (void)w;
    (void)uncomitted;
    (void)wanted;
    (void)unmeet;
    return 1;
}

int sched_check_shared_satisfy(xce_sched_core_t* core, xvec_t* uncomitted,
                               xvec_idval_t* wanted, xvec_idval_t* unmeet)
{
    (void)core;
    (void)uncomitted;
    (void)wanted;
    (void)unmeet;
    return 1;
}

int sched_charge_account(xce_sched_core_t* core, xce_job_account_t* acct)
{
    (void)core;
    (void)acct;
    return 0;
}

int sched_uncharge_account(xce_sched_core_t* core, xce_job_account_t* acct)
{
    (void)core;
    (void)acct;
    return 0;
}


/* Real reimplementation of schedobj.c's sched_resolve_job_picker -- same
 * copy test_sim_alt_events.c/test_sim_verify.c/test_repl_execution_control.c/
 * test_repl_event_echo.c each carry (schedobj.c is not linked here: it would
 * need plugin_register(), which requires a genuine xce_scheduler_t* neither
 * this file's tests nor sim_loop.c's own core-scoped registration path have,
 * Req 5 AC 17). Never actually invoked by this file's own tests -- link-time
 * requirement only, same rationale as sched_account_jobs() above. */
int sched_resolve_job_picker(xce_sched_core_t* core, xce_sched_plugin_t** out)
{
    xce_sched_plugin_t* plugin = NULL;
    int                 rc     = 0;

    if ((core == NULL) || (out == NULL)) {
        return -EINVAL;
    }

    *out = NULL;

    if (core->job_pick_plugin == NULL) {
        return -EINVAL;
    }

    lock(core->plugins, RTTI_LOCK_READ);
    rc = key_find(core->plugins, core->job_pick_plugin, (void**)&plugin);
    unlock(core->plugins);

    if (rc <= 0) {
        return (rc < 0) ? rc : -ENOENT;
    }

    if ((plugin == NULL) || (plugin->picker_iface == NULL)
        || (plugin->picker_iface->next_job == NULL)
        || (plugin->picker_iface->begin_session == NULL)
        || (plugin->picker_iface->end_session == NULL)
        || (plugin->picker_iface->on_dispatch == NULL)
        || (plugin->picker_iface->on_pend == NULL)) {
        return -EINVAL;
    }

    *out = plugin;

    return 0;
}

/* scheduler-sim-live-allocation spec, task 4.1: sim_loop.c's real
 * sched_sim_driver_run() (white-box #include'd into this TU above) now
 * spawns sched_job_picker()/sched_allocator() (sched_election.c) directly
 * instead of its own, now-removed sim_picker_thread_fn() -- an undefined
 * reference at link time in this white-box TU otherwise, since
 * sched_election.c's own sched_allocator() calls the REAL
 * sched_make_allocation()/sched_commit_decision() (scheduler.c), neither
 * part of this file's own hand-picked white-box #include set (this file's
 * own header comment lists that set). This file's own test(s) do not
 * exercise genuine resource-matching allocation, so this link-satisfying
 * pair faithfully reproduces the exact PEND-only contract the REMOVED
 * sim_picker_thread_fn() itself used to provide -- split across the SAME
 * two-thread jbuf hand-off the real production pair now uses (one
 * producer, one consumer, matching the project's jbuf capacity-1
 * rendezvous invariant) instead of the old single fused thread -- so this
 * file's own existing assertions are unaffected by this task's production
 * change. Genuine resource-based dispatch through the real, unmodified
 * sched_job_picker()/sched_allocator() pair is proved separately by
 * test_sim_live_allocation.c (task 4.1's own dedicated fixture, which
 * links the real scheduler_srcs instead of white-boxing individual files,
 * precisely so it can reach the real allocation chain this stub
 * deliberately does not). */
void* sched_job_picker(void* arg)
{
    xce_sched_core_t*   core   = (xce_sched_core_t*)arg;
    xce_sched_plugin_t* picker = NULL;

    for (;;) {
        int      go    = 0;
        uint64_t jobid = 0;

        cbuf_get(&(core->wbuf), &go);

        if (sched_resolve_job_picker(core, &picker) < 0) {
            jobid = 0;
            cbuf_put(&(core->jbuf), &jobid);
            continue;
        }

        picker->picker_iface->begin_session(picker);

        for (;;) {
            xce_sched_job_t* job = picker->picker_iface->next_job(picker);

            if (job == NULL) {
                break;
            }

            jobid = job->jobid;
            cbuf_put(&(core->jbuf), &jobid);
        }

        jobid = 0;
        cbuf_put(&(core->jbuf), &jobid);

        picker->picker_iface->end_session(picker);
    }

    return NULL;
}

void* sched_allocator(void* arg)
{
    xce_sched_core_t*   core   = (xce_sched_core_t*)arg;
    xce_sched_plugin_t* picker = NULL;

    for (;;) {
        uint64_t         jobid    = 0;
        xce_decision_t*  decision = NULL;
        xce_sched_job_t* job;

        cbuf_get(&(core->jbuf), &jobid);
        if (jobid == 0) {
            decision = NULL;
            cbuf_put(&(core->decisions), &decision);
            continue;
        }

        job = sched_get_job(core, jobid);
        if (job == NULL) {
            continue;
        }

        (void)sched_resolve_job_picker(core, &picker);
        if (picker != NULL) {
            picker->picker_iface->on_pend(picker, job->jobid);
        }

        decision = make_pend_decision(make_pendreason(job->jobid));
        cbuf_put(&(core->decisions), &decision);
    }

    return NULL;
}

/* scheduler-sim-live-allocation spec, task 4.1 (bug-1829 fix): sim_loop.c's
 * real sched_sim_driver_run() (white-box #include'd into this TU above) now
 * also calls sim_bootstrap_seqjob_allocator()/sim_bootstrap_parjob_
 * allocator() (sim_alloc.c) -- undefined references at link time in this
 * white-box TU otherwise, since neither symbol is part of this file's own
 * hand-picked white-box #include set. This file's own test(s) exercise the
 * link-satisfying sched_job_picker()/sched_allocator() stub pair above
 * (which never reaches real primary allocation), so a true no-op is the
 * correct, behavior-preserving stand-in here -- the real bootstrap logic is
 * exercised separately by test_sim_live_allocation.c (task 4.1's own
 * dedicated fixture, which links the real scheduler_srcs). */
void sim_bootstrap_seqjob_allocator(xce_sched_sim_driver_t* sim)
{
    (void)sim;
}

void sim_bootstrap_parjob_allocator(xce_sched_sim_driver_t* sim)
{
    (void)sim;
}

void setUp(void) { return; }
void tearDown(void) { return; }

/* ---------------------------------------------------------------------- */
/* Fixture helpers -- duplicated from test_repl_execution_control.c/       */
/* test_repl_event_echo.c per this file family's established split         */
/* convention (see header comment above): copied, not shared via a new     */
/* header.                                                                  */
/* ---------------------------------------------------------------------- */

/* Same dup()/dup2()-around-STDOUT_FILENO capture technique
 * test_repl_execution_control.c's own capture_stdout_around() establishes. */
static char* capture_stdout_around(void (*fn)(void))
{
    char  tmp[] = "/tmp/xce_replhelp_stdoutcap_XXXXXX";
    int   fd    = mkstemp(tmp);
    int   saved_stdout;
    off_t len;
    char* buf;

    TEST_ASSERT_TRUE_MESSAGE(fd >= 0, "mkstemp for stdout capture must "
                                      "succeed");

    fflush(stdout);
    saved_stdout = dup(STDOUT_FILENO);
    TEST_ASSERT_TRUE_MESSAGE(saved_stdout >= 0, "dup(STDOUT_FILENO) must "
                                                "succeed");
    TEST_ASSERT_TRUE_MESSAGE(dup2(fd, STDOUT_FILENO) >= 0,
                             "dup2 redirect of STDOUT_FILENO must succeed");

    fn();

    fflush(stdout);
    dup2(saved_stdout, STDOUT_FILENO);
    close(saved_stdout);

    len = lseek(fd, 0, SEEK_CUR);
    TEST_ASSERT_TRUE(len >= 0);

    buf = (char*)calloc(1, (size_t)len + 1);
    TEST_ASSERT_NOT_NULL(buf);
    TEST_ASSERT_TRUE(lseek(fd, 0, SEEK_SET) == 0);
    if (len > 0) {
        ssize_t nread = read(fd, buf, (size_t)len);
        TEST_ASSERT_TRUE(nread == len);
    }
    close(fd);
    unlink(tmp);

    return buf;
}

static void run_print_help(void) { repl_print_help(); }

/*
 * description_column_after - locates the FIRST occurrence of `cmd_field`
 * that starts a line (i.e. only whitespace, or nothing, precedes it back to
 * the start of `text` or the preceding '\n' -- so a coincidental
 * mid-description occurrence of the same text is not mistaken for the
 * command entry itself), then returns the 0-based column (character offset
 * from that line's start) of the first non-whitespace character following
 * `cmd_field` -- i.e. where that line's description text begins. Used to
 * prove Requirement 7.2's "one consistent column position computed
 * consistently" claim: every command line's description must begin at the
 * SAME column, regardless of how long that line's own command/argument text
 * is. Deliberately does not assume any particular indent width (2 spaces,
 * 4 spaces, ...) -- only that indentation is spaces/tabs.
 */
static int description_column_after(const char* text, const char* cmd_field)
{
    size_t      flen  = strlen(cmd_field);
    const char* p      = text;
    const char* found  = NULL;

    while ((p = strstr(p, cmd_field)) != NULL) {
        const char* q = p;

        while ((q > text)
               && ((*(q - 1) == ' ') || (*(q - 1) == '\t'))) {
            q--;
        }
        if ((q == text) || (*(q - 1) == '\n')) {
            found = p;
            break;
        }
        p += flen;
    }

    TEST_ASSERT_NOT_NULL_MESSAGE(found, cmd_field);

    {
        const char* line_start = found;
        const char* d;

        while ((line_start > text) && (*(line_start - 1) != '\n')) {
            line_start--;
        }

        d = found + flen;
        while ((*d == ' ') || (*d == '\t')) {
            d++;
        }

        return (int)(d - line_start);
    }
}

/* BP_KIND_TABLE's complete token set (repl_break.c), duplicated here in
 * table order -- the exact same "same source" list Requirement 7.4/7.5 says
 * `help` and `break`'s error message must both fully enumerate. Kept as a
 * plain literal list (not a call into a not-yet-existing
 * repl_bp_kind_names() accessor) deliberately: this is a RED-phase test
 * written before task 9.2 adds that accessor -- referencing it now would
 * make this file fail to LINK rather than fail its assertions, which this
 * task's own instructions call out as the wrong kind of RED failure. */
static const char* BP_KIND_TOKENS[] = {
    "CONFIG_PUSH",      "JOB_PUSH",         "WORKERS_PUSH",
    "RESOURCES_PUSH",   "RESVALS_FULL",     "RESVALS_DELTA",
    "JOB_STATE_CHANGE", "JOB_UPDATE",       "QUEUE_UPDATE",
    "JOB_RUSAGE",        "BEGIN_ROUND",      "DECISION",
};
#define NUM_BP_KIND_TOKENS \
    (sizeof(BP_KIND_TOKENS) / sizeof(BP_KIND_TOKENS[0]))

/* ---------------------------------------------------------------------- */
/* Test 1: `help`'s listing groups commands into four labeled sections, in */
/* the fixed order design.md's own component description names, with each */
/* command's line falling within its correct section's bounds -- including */
/* `info config` landing inside State Inspection next to its `info`        */
/* siblings (Requirement 7.3), and `set units` landing inside Snapshot &   */
/* Parameters next to `set output`/`set verify` (Requirement 7.1/7.4's    */
/* section-organization half), and no `set speed` line anywhere (the REPL  */
/* speed parameter was removed, scheduler-sim-discrete-clock Req 3.3).     */
/* ---------------------------------------------------------------------- */

static void test_help_groups_commands_into_four_labeled_sections_in_order(
    void)
{
    char* captured = capture_stdout_around(run_print_help);
    char* exec_hdr;
    char* bp_hdr;
    char* state_hdr;
    char* snap_hdr;

    exec_hdr  = strstr(captured, "Execution Control");
    bp_hdr    = strstr(captured, "Breakpoints");
    state_hdr = strstr(captured, "State Inspection");
    snap_hdr  = strstr(captured, "Snapshot & Parameters");

    TEST_ASSERT_NOT_NULL_MESSAGE(
        exec_hdr, "help must print an 'Execution Control' section label "
                  "(Requirement 7.1)");
    TEST_ASSERT_NOT_NULL_MESSAGE(
        bp_hdr, "help must print a 'Breakpoints' section label "
                "(Requirement 7.1)");
    TEST_ASSERT_NOT_NULL_MESSAGE(
        state_hdr, "help must print a 'State Inspection' section label "
                   "(Requirement 7.1)");
    TEST_ASSERT_NOT_NULL_MESSAGE(
        snap_hdr, "help must print a 'Snapshot & Parameters' section label "
                  "(Requirement 7.1)");

    TEST_ASSERT_TRUE_MESSAGE(exec_hdr < bp_hdr,
                             "Execution Control must precede Breakpoints");
    TEST_ASSERT_TRUE_MESSAGE(bp_hdr < state_hdr,
                             "Breakpoints must precede State Inspection");
    TEST_ASSERT_TRUE_MESSAGE(state_hdr < snap_hdr,
                             "State Inspection must precede Snapshot & "
                             "Parameters");

    /* Execution Control: step/continue/quit/help, all before Breakpoints */
    {
        const char* fields[] = { "step [N]", "continue", "quit", "help" };
        size_t      i;

        for (i = 0; i < (sizeof(fields) / sizeof(fields[0])); i++) {
            char* pos = strstr(captured, fields[i]);

            TEST_ASSERT_NOT_NULL_MESSAGE(pos, fields[i]);
            TEST_ASSERT_TRUE_MESSAGE(
                (exec_hdr < pos) && (pos < bp_hdr),
                "every Execution Control command must fall strictly "
                "between the Execution Control and Breakpoints labels");
        }
    }

    /* Breakpoints: break/info break/delete, all before State Inspection */
    {
        const char* fields[]
            = { "break <EVENT_TYPE>", "info break", "delete <id>|all" };
        size_t i;

        for (i = 0; i < (sizeof(fields) / sizeof(fields[0])); i++) {
            char* pos = strstr(captured, fields[i]);

            TEST_ASSERT_NOT_NULL_MESSAGE(pos, fields[i]);
            TEST_ASSERT_TRUE_MESSAGE(
                (bp_hdr < pos) && (pos < state_hdr),
                "every Breakpoints command must fall strictly between the "
                "Breakpoints and State Inspection labels");
        }
    }

    /* State Inspection: every `info` subcommand, INCLUDING `info config`
     * (Requirement 7.3) -- all before Snapshot & Parameters. */
    {
        const char* fields[] = {
            "info session",  "info job <jobid>", "info jobs",
            "info queue <name>|all", "info worker <name>|all",
            "info resource <name>|all", "info summary", "info config",
        };
        size_t i;

        for (i = 0; i < (sizeof(fields) / sizeof(fields[0])); i++) {
            char* pos = strstr(captured, fields[i]);

            TEST_ASSERT_NOT_NULL_MESSAGE(pos, fields[i]);
            TEST_ASSERT_TRUE_MESSAGE(
                (state_hdr < pos) && (pos < snap_hdr),
                "every `info` subcommand -- including `info config` -- "
                "must fall strictly between the State Inspection and "
                "Snapshot & Parameters labels (Requirement 7.3)");
        }
    }

    /* Snapshot & Parameters: snapshot/set output/set verify/set
     * units, all after Snapshot & Parameters's own label (last section, so
     * only a lower bound applies). `set units`'s exact argument spelling is
     * deliberately not pinned here -- only its existence and placement. */
    {
        const char* fields[] = {
            "snapshot [FILE]", "set output <FILE>|off",
            "set verify on|off", "set units",
        };
        size_t i;

        for (i = 0; i < (sizeof(fields) / sizeof(fields[0])); i++) {
            char* pos = strstr(captured, fields[i]);

            TEST_ASSERT_NOT_NULL_MESSAGE(pos, fields[i]);
            TEST_ASSERT_TRUE_MESSAGE(
                snap_hdr < pos,
                "every snapshot/parameter command -- including `set "
                "units` -- must fall at or after the Snapshot & "
                "Parameters label (Requirement 7.1/7.4)");
        }
    }

    TEST_ASSERT_NULL_MESSAGE(strstr(captured, "set speed"),
                             "help must not list the removed `set speed` "
                             "parameter (scheduler-sim-discrete-clock Req "
                             "3.3)");

    free(captured);

    printf("test_help_groups_commands_into_four_labeled_sections_in_order: "
          "PASS\n");
}

/* ---------------------------------------------------------------------- */
/* Test 2: every command's description is aligned to ONE consistent column */
/* position, computed the same way throughout the whole listing -- not     */
/* independently hand-padded per line (Requirement 7.2). Covers all four   */
/* sections' worth of commands whose usage/argument text is unchanged from */
/* today's repl.c (Requirement 7.6), so the ONLY reason their computed     */
/* description columns could differ is misalignment, not a wording change. */
/* ---------------------------------------------------------------------- */

static void test_help_uses_one_consistent_column_width_throughout(void)
{
    char* captured = capture_stdout_around(run_print_help);
    /* One representative field per command line whose usage/argument text
     * is unchanged from today's repl.c (Requirement 7.6) -- spans all four
     * sections. `set units` is deliberately excluded (its exact argument
     * spelling is a task 9.2 implementation choice, not yet pinned). */
    const char* fields[] = {
        "step [N]",
        "continue",
        "quit",
        "help",
        "break <EVENT_TYPE> [key=value ...]",
        "info break",
        "delete <id>|all",
        "info session",
        "info job <jobid>",
        "info jobs",
        "info queue <name>|all",
        "info worker <name>|all",
        "info resource <name>|all",
        "info summary",
        "info config",
        "snapshot [FILE]",
        "set output <FILE>|off",
        "set verify on|off",
    };
    size_t n      = sizeof(fields) / sizeof(fields[0]);
    int    col0   = description_column_after(captured, fields[0]);
    size_t i;

    for (i = 1; i < n; i++) {
        int col = description_column_after(captured, fields[i]);
        char msg[160];

        snprintf(msg, sizeof(msg),
                "'%s' description column (%d) must match '%s' description "
                "column (%d) -- one consistent column width throughout "
                "(Requirement 7.2), not independently hand-padded per line",
                fields[i], col, fields[0], col0);
        TEST_ASSERT_EQUAL_INT_MESSAGE(col0, col, msg);
    }

    free(captured);

    printf("test_help_uses_one_consistent_column_width_throughout: PASS\n");
}

/* ---------------------------------------------------------------------- */
/* Test 3: help's `break` line enumerates the COMPLETE set of valid        */
/* `<EVENT_TYPE>` values -- every BP_KIND_TABLE token appears between the  */
/* `break` entry and the next command entry (`info break`) (Requirement    */
/* 7.4).                                                                    */
/* ---------------------------------------------------------------------- */

static void test_help_break_line_lists_the_complete_event_type_set(void)
{
    char* captured = capture_stdout_around(run_print_help);
    char* break_pos;
    char* info_break_pos;
    size_t i;

    break_pos      = strstr(captured, "break <EVENT_TYPE>");
    info_break_pos = strstr(captured, "info break");

    TEST_ASSERT_NOT_NULL_MESSAGE(break_pos,
                                 "help must still list the `break` command");
    TEST_ASSERT_NOT_NULL_MESSAGE(info_break_pos,
                                 "help must still list `info break`");
    TEST_ASSERT_TRUE_MESSAGE(break_pos < info_break_pos,
                             "`break`'s entry must precede `info break`'s");

    for (i = 0; i < NUM_BP_KIND_TOKENS; i++) {
        char* tok_pos = strstr(captured, BP_KIND_TOKENS[i]);

        TEST_ASSERT_NOT_NULL_MESSAGE(
            tok_pos, BP_KIND_TOKENS[i]);
        TEST_ASSERT_TRUE_MESSAGE(
            (break_pos < tok_pos) && (tok_pos < info_break_pos),
            "every valid break <EVENT_TYPE> token must appear as part of "
            "help's `break` entry, between the `break` and `info break` "
            "lines (Requirement 7.4)");
    }

    free(captured);

    printf(
        "test_help_break_line_lists_the_complete_event_type_set: PASS\n");
}

int main(void)
{
    UNITY_BEGIN();

    RUN_TEST(test_help_groups_commands_into_four_labeled_sections_in_order);
    RUN_TEST(test_help_uses_one_consistent_column_width_throughout);
    RUN_TEST(test_help_break_line_lists_the_complete_event_type_set);

    return UNITY_END();
}