/*
 * test_repl_snapshot_params.c - contract test for the interactive
 * simulation REPL's snapshot-capture and simulation-parameter command slice
 * (scheduler-core spec, task 12.3, Req 5 AC 22 "Snapshots"/"Simulation
 * parameters").
 *
 * Observable under test (task 12.3's own text): "a snapshot command
 * produces a file that the simulation driver can later load via a fresh
 * `--sim` invocation starting from that exact position." Proved end to end
 * (test_snapshot_written_file_is_loadable_by_fresh_sim_start below): a
 * forked child drives a REAL sched_sim_driver_run() against a real
 * fixture, issues `step 1` then `snapshot <path>` then `quit`, and the
 * PARENT then calls the real sched_sim_driver_start() a SECOND time
 * against the file the child wrote, asserting it succeeds and that the
 * reloaded core state (snapshot_ts, the pushed job) matches what the
 * child's session actually produced.
 *
 * The remaining tests cover `set speed`/`set output`/`set verify`/
 * `info config` and the auto-generated `snapshot` filename, at the same
 * "unit-level precision where possible, integration-level proof for the
 * one Observable that needs it" split test_repl_execution_control.c's own
 * header comment establishes.
 *
 * `set units raw|human|both` (scheduler-sim-repl-verbosity spec, task 7.1,
 * Requirement 6.2/6.3) is added below, alongside the existing `set speed`/
 * `set output`/`set verify` tests, per design.md's File Structure Plan
 * ("test_repl_snapshot_params.c -- extended with `set units raw|human|both`
 * parsing/validation tests ... alongside its existing `set speed`/`set
 * output`/`set verify` tests"). THIS SLICE IS RED-PHASE ONLY: neither
 * xce_sched_repl_state_s's `units_mode` field nor repl_cmd_set()'s `units`
 * branch exists yet (task 7.2, a separate later task, adds both) -- see
 * that test group's own header comment further below for the exact
 * build-failure shape this is expected to produce today.
 *
 * Fixture strategy and white-box #include set: identical to
 * test_repl_execution_control.c/test_repl_breakpoints_inspection.c (see
 * either file's own header comment) PLUS the new ../src/repl_params.c
 * under test (task 12.3's own file, repl_internal.h's "Why a split at
 * all" section).
 */
#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_breakpoints_inspection.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_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_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; }

/* 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_scheduler_t* sched, xvec_idval_t* vec,
                              xlist_t* limits)
{
    (void)sched;
    (void)vec;
    (void)limits;
    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. */
int sched_account_jobs(xce_sched_core_t* core)
{
    (void)core;
    return 0;
}

/* Real reimplementation of schedobj.c's sched_resolve_job_picker -- same
 * copy every sim-family white-box test carries (schedobj.c is not linked
 * here: it would need plugin_register(), which requires a genuine
 * xce_scheduler_t* neither this file's fixtures nor sim_loop.c's own
 * core-scoped registration path have, Req 5 AC 17). */
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;
}

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

/* ---------------------------------------------------------------------- */
/* Fixture helpers -- same techniques test_repl_execution_control.c/       */
/* test_repl_breakpoints_inspection.c already establish.                   */
/* ---------------------------------------------------------------------- */

static void make_tmp_dir(char* out, size_t out_len, const char* suffix)
{
    char tmpl[PATH_MAX];

    snprintf(tmpl, sizeof(tmpl), "/tmp/sched_replparams%s_XXXXXX", suffix);
    TEST_ASSERT_NOT_NULL(mkdtemp(tmpl));
    TEST_ASSERT_TRUE(strlen(tmpl) < out_len);
    strcpy(out, tmpl);
}

static void build_fixture_scheduler(xce_scheduler_t* sched, char* record_dir)
{
    int rc;

    memset(sched, 0, sizeof(*sched));
    mylock_init(&(sched->record_lock));

    rc = xce_sched_core_init(&(sched->core));
    TEST_ASSERT_EQUAL_INT(0, rc);

    sched->core.job_pick_plugin = (char*)"builtin_fcfs";
    sched->record_dir           = record_dir;
}

static FILE* write_header_and_snapshot(char* out_path, size_t out_path_len,
                                       const char* suffix)
{
    char            record_dir[PATH_MAX];
    xce_scheduler_t sched;
    int             rc;

    make_tmp_dir(record_dir, sizeof(record_dir), suffix);
    build_fixture_scheduler(&sched, record_dir);

    rc = sched_record_start(&sched, "fixture.replay");
    TEST_ASSERT_EQUAL_INT(0, rc);
    TEST_ASSERT_TRUE(strlen(sched.record_file_path) < out_path_len);
    strcpy(out_path, sched.record_file_path);

    return sched.record_file;
}

static void append_queue_update_event(FILE* f, uint64_t ts,
                                      const char* queue_name)
{
    xce_queue_t          queue;
    replay_event_t       src;
    struct capn          c;
    struct capn_segment* cs;
    ReplayEvent_ptr      p;

    memset(&queue, 0, sizeof(queue));
    queue.queue    = (char*)queue_name;
    queue.status   = QUEUE_STAT_OPEN;
    queue.priority = 1;

    memset(&src, 0, sizeof(src));
    src.ts                = ts;
    src.body_which        = ReplayEvent_body_queueUpdate;
    src.body.queue_update = &queue;

    capn_init_malloc(&c);
    cs = capn_root(&c).seg;
    encode_ReplayEvent_ptr(cs, &p, &src);
    capn_setp(capn_root(&c), 0, p.p);

    TEST_ASSERT_EQUAL_INT(0, write_capnp_message(f, &c));
    capn_free(&c);
}

static void append_jobs_push_event(FILE* f, uint64_t ts, uint64_t jobid,
                                   const char* queue_name)
{
    job_submit_data_t    submit;
    xce_job_t            job;
    xce_job_t*           jobs[1];
    xce_jobs_data_t      jobs_data;
    replay_event_t       src;
    struct capn          c;
    struct capn_segment* cs;
    ReplayEvent_ptr      p;

    memset(&submit, 0, sizeof(submit));
    submit.queue    = (char*)queue_name;
    submit.user     = (char*)"alice";
    submit.mintasks = 1;
    submit.maxtasks = 1;

    memset(&job, 0, sizeof(job));
    job.jobid  = jobid;
    job.state  = JOB_STAT_PEND;
    job.submit = &submit;

    jobs[0] = &job;

    memset(&jobs_data, 0, sizeof(jobs_data));
    jobs_data.n_total = 1;
    jobs_data.count   = 1;
    jobs_data.jobs    = jobs;

    memset(&src, 0, sizeof(src));
    src.ts             = ts;
    src.body_which     = ReplayEvent_body_jobsPush;
    src.body.jobs_push = &jobs_data;

    capn_init_malloc(&c);
    cs = capn_root(&c).seg;
    encode_ReplayEvent_ptr(cs, &p, &src);
    capn_setp(capn_root(&c), 0, p.p);

    TEST_ASSERT_EQUAL_INT(0, write_capnp_message(f, &c));
    capn_free(&c);
}

static void append_replay_session(FILE* f, uint64_t begin_round)
{
    struct capn          c;
    struct capn_segment* cs;
    ReplaySession_ptr    sp;

    capn_init_malloc(&c);
    cs = capn_root(&c).seg;
    sp = new_ReplaySession(cs);
    ReplaySession_set_beginRound(sp, begin_round);
    capn_setp(capn_root(&c), 0, sp.p);

    TEST_ASSERT_EQUAL_INT(0, write_capnp_message(f, &c));
    capn_free(&c);
}

static void append_end_of_stream_marker(FILE* f)
{
    replay_event_t       src;
    struct capn          c;
    struct capn_segment* cs;
    ReplayEvent_ptr      p;

    memset(&src, 0, sizeof(src));
    src.body_which = ReplayEvent_body_endSession;

    capn_init_malloc(&c);
    cs = capn_root(&c).seg;
    encode_ReplayEvent_ptr(cs, &p, &src);
    capn_setp(capn_root(&c), 0, p.p);

    TEST_ASSERT_EQUAL_INT(0, write_capnp_message(f, &c));
    capn_free(&c);
}

static void write_text_file(const char* path, const char* content)
{
    FILE* f = fopen(path, "w");

    TEST_ASSERT_NOT_NULL(f);
    TEST_ASSERT_TRUE(fputs(content, f) >= 0);
    fclose(f);
}

static char* read_whole_file(const char* path)
{
    FILE* f = fopen(path, "rb");
    long  len;
    char* buf;

    TEST_ASSERT_NOT_NULL(f);
    TEST_ASSERT_EQUAL_INT(0, fseek(f, 0, SEEK_END));
    len = ftell(f);
    TEST_ASSERT_TRUE(len >= 0);
    rewind(f);

    buf = (char*)malloc((size_t)len + 1);
    TEST_ASSERT_NOT_NULL(buf);
    if (len > 0) {
        TEST_ASSERT_EQUAL_INT((int)len, (int)fread(buf, 1, (size_t)len, f));
    }
    buf[len] = '\0';
    fclose(f);

    return buf;
}

/* 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_replparams_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 bool file_exists_nonempty(const char* path)
{
    FILE* f = fopen(path, "rb");
    long  len;

    if (f == NULL) {
        return false;
    }
    if (fseek(f, 0, SEEK_END) != 0) {
        fclose(f);
        return false;
    }
    len = ftell(f);
    fclose(f);

    return len > 0;
}

/* ---------------------------------------------------------------------- */
/* Test: `snapshot <FILE>` writes a standalone .replay file a FRESH        */
/* sched_sim_driver_start() can load, landing on the exact position the    */
/* snapshot was taken at -- the task's own central Observable.             */
/* ---------------------------------------------------------------------- */

static void child_step_snapshot_quit(const char* replay_path,
                                     const char* script_path,
                                     const char* capture_path,
                                     const char* output_dir)
{
    xce_sched_sim_driver_t sim;
    sched_sim_args_t       args;

    if (chdir(output_dir) != 0) {
        _exit(119);
    }
    if (freopen(script_path, "r", stdin) == NULL) {
        _exit(120);
    }
    if (freopen(capture_path, "w", stdout) == NULL) {
        _exit(121);
    }

    memset(&sim, 0, sizeof(sim));
    memset(&args, 0, sizeof(args));
    args.replay_path  = replay_path;
    args.sim_start_ts = SCHED_SIM_START_TS_LATEST;
    args.sim_speed    = 0; /* frozen virtual clock -- deterministic ts */
    args.interactive  = true;

    (void)sched_sim_driver_run(&sim, &args);

    /* Unreachable in a correct implementation -- "quit" must have called
     * exit(0) already. */
    fflush(stdout);
    _exit(111);
}

static void test_snapshot_written_file_is_loadable_by_fresh_sim_start(void)
{
    char  replay_path[PATH_MAX];
    char  output_dir[PATH_MAX];
    char  aux_dir[PATH_MAX];
    char  script_path[PATH_MAX];
    char  capture_path[PATH_MAX];
    char  snap_path[PATH_MAX];
    FILE* f;
    pid_t pid;
    int   status;
    char* captured;
    xce_sched_sim_driver_t sim2;
    sched_sim_args_t       args2;
    int                     rc;
    xce_sched_job_t*        job;

    f = write_header_and_snapshot(replay_path, sizeof(replay_path),
                                  "_snapload");
    TEST_ASSERT_NOT_NULL(f);

    append_queue_update_event(f, 1000ULL, "normal");
    append_jobs_push_event(f, 1500ULL, 555ULL, "normal");
    append_replay_session(f, 2000ULL); /* session boundary #1 -- `step 1`
                                        * pauses here, frozen at ts=2000 */
    append_jobs_push_event(f, 2500ULL, 999ULL, "normal");
    append_replay_session(f, 3000ULL); /* must NEVER be reached */
    append_end_of_stream_marker(f);
    fclose(f);

    make_tmp_dir(output_dir, sizeof(output_dir), "_snaploadout");
    make_tmp_dir(aux_dir, sizeof(aux_dir), "_snaploadaux");
    snprintf(script_path, sizeof(script_path), "%s/script.txt", aux_dir);
    snprintf(capture_path, sizeof(capture_path), "%s/capture.out", aux_dir);
    write_text_file(script_path, "step 1\nsnapshot snap_out.replay\nquit\n");

    pid = fork();
    TEST_ASSERT_TRUE_MESSAGE(pid >= 0, "fork() must succeed");

    if (pid == 0) {
        child_step_snapshot_quit(replay_path, script_path, capture_path,
                                 output_dir);
        _exit(112); /* unreachable */
    }

    TEST_ASSERT_EQUAL_INT_MESSAGE(pid, waitpid(pid, &status, 0),
                                  "waitpid must reap the REPL child");
    TEST_ASSERT_TRUE_MESSAGE(WIFEXITED(status),
                             "the REPL child must exit normally via quit's "
                             "exit(0)");
    TEST_ASSERT_EQUAL_INT_MESSAGE(0, WEXITSTATUS(status),
                                  "quit's exit(0) is the only correct exit "
                                  "path");

    captured = read_whole_file(capture_path);
    TEST_ASSERT_NOT_NULL_MESSAGE(strstr(captured, "snapshot written"),
                                 "the snapshot command must print a "
                                 "confirmation line");
    free(captured);

    snprintf(snap_path, sizeof(snap_path), "%s/snap_out.replay", output_dir);
    TEST_ASSERT_TRUE_MESSAGE(file_exists_nonempty(snap_path),
                             "the snapshot command must have created a "
                             "non-empty file at the requested path");

    /* The central Observable: a FRESH sched_sim_driver_start() against the
     * snapshot the REPL just wrote must succeed and land exactly where the
     * `snapshot` command was issued -- after session 1, NOT session 2. */
    memset(&sim2, 0, sizeof(sim2));
    memset(&args2, 0, sizeof(args2));
    args2.replay_path  = snap_path;
    args2.sim_start_ts = SCHED_SIM_START_TS_LATEST;

    rc = sched_sim_driver_start(&sim2, &args2);
    TEST_ASSERT_EQUAL_INT_MESSAGE(0, rc,
                                  "a fresh --sim invocation must load the "
                                  "REPL-written snapshot successfully");
    TEST_ASSERT_EQUAL_UINT64_MESSAGE(2000ULL, sim2.snapshot_ts,
                                     "the reloaded snapshot's ts must be "
                                     "exactly the simulation position at "
                                     "the moment `snapshot` was issued "
                                     "(session 1's begin_round, frozen "
                                     "clock)");

    job = sched_get_job(&(sim2.core), 555ULL);
    TEST_ASSERT_NOT_NULL_MESSAGE(job, "job 555 (pushed before session 1) "
                                      "must be present in the reloaded "
                                      "snapshot's state");
    TEST_ASSERT_NULL_MESSAGE(sched_get_job(&(sim2.core), 999ULL),
                             "job 999 (pushed AFTER session 1, never "
                             "reached) must NOT be present -- proves the "
                             "snapshot captured the position at `snapshot` "
                             "time, not the whole file");

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

/* ---------------------------------------------------------------------- */
/* Test: `snapshot` with no FILE argument auto-generates a name using the  */
/* REPL's own event_index position counter.                                */
/* ---------------------------------------------------------------------- */

static void child_step_snapshot_noarg_quit(const char* replay_path,
                                           const char* script_path,
                                           const char* capture_path,
                                           const char* output_dir)
{
    xce_sched_sim_driver_t sim;
    sched_sim_args_t       args;

    if (chdir(output_dir) != 0) {
        _exit(119);
    }
    if (freopen(script_path, "r", stdin) == NULL) {
        _exit(120);
    }
    if (freopen(capture_path, "w", stdout) == NULL) {
        _exit(121);
    }

    memset(&sim, 0, sizeof(sim));
    memset(&args, 0, sizeof(args));
    args.replay_path  = replay_path;
    args.sim_start_ts = SCHED_SIM_START_TS_LATEST;
    args.sim_speed    = 0;
    args.interactive  = true;

    (void)sched_sim_driver_run(&sim, &args);

    fflush(stdout);
    _exit(111);
}

static void test_snapshot_auto_generates_filename_from_event_index(void)
{
    char  replay_path[PATH_MAX];
    char  output_dir[PATH_MAX];
    char  aux_dir[PATH_MAX];
    char  script_path[PATH_MAX];
    char  capture_path[PATH_MAX];
    char  expect_path[PATH_MAX];
    FILE* f;
    pid_t pid;
    int   status;

    f = write_header_and_snapshot(replay_path, sizeof(replay_path),
                                  "_snapauto");
    TEST_ASSERT_NOT_NULL(f);

    /* Two translatable events (QUEUE_UPDATE, JOBS_PUSH) before the one
     * session boundary -- event_index == 2 by the time `step 1` re-pauses. */
    append_queue_update_event(f, 1000ULL, "normal");
    append_jobs_push_event(f, 1500ULL, 777ULL, "normal");
    append_replay_session(f, 2000ULL);
    append_end_of_stream_marker(f);
    fclose(f);

    make_tmp_dir(output_dir, sizeof(output_dir), "_snapautoout");
    make_tmp_dir(aux_dir, sizeof(aux_dir), "_snapautoaux");
    snprintf(script_path, sizeof(script_path), "%s/script.txt", aux_dir);
    snprintf(capture_path, sizeof(capture_path), "%s/capture.out", aux_dir);
    write_text_file(script_path, "step 1\nsnapshot\nquit\n");

    pid = fork();
    TEST_ASSERT_TRUE_MESSAGE(pid >= 0, "fork() must succeed");

    if (pid == 0) {
        child_step_snapshot_noarg_quit(replay_path, script_path,
                                       capture_path, output_dir);
        _exit(112);
    }

    TEST_ASSERT_EQUAL_INT_MESSAGE(pid, waitpid(pid, &status, 0),
                                  "waitpid must reap the REPL child");
    TEST_ASSERT_TRUE_MESSAGE(WIFEXITED(status),
                             "the REPL child must exit normally via quit's "
                             "exit(0)");
    TEST_ASSERT_EQUAL_INT_MESSAGE(0, WEXITSTATUS(status),
                                  "quit's exit(0) is the only correct exit "
                                  "path");

    snprintf(expect_path, sizeof(expect_path), "%s/sim-snap-2.replay",
             output_dir);
    TEST_ASSERT_TRUE_MESSAGE(file_exists_nonempty(expect_path),
                             "an omitted FILE argument must auto-generate "
                             "'sim-snap-<event_index>.replay' in the "
                             "current directory");

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

/* ---------------------------------------------------------------------- */
/* Test: `set speed <N>` mutates BOTH the driver-level shadow copy AND the */
/* atomic core.speed_num/speed_den pair xce_core_now() actually reads.     */
/* ---------------------------------------------------------------------- */

static void test_set_speed_updates_shadow_and_core_atomics(void)
{
    xce_sched_sim_driver_t sim;
    bool                    handled;

    memset(&sim, 0, sizeof(sim));

    handled = repl_cmd_set(&sim, "set speed 7");
    TEST_ASSERT_FALSE_MESSAGE(handled, "`set` never hands control back");
    TEST_ASSERT_EQUAL_UINT64(7ULL, sim.sim_speed_num);
    TEST_ASSERT_EQUAL_UINT64(1ULL, sim.sim_speed_den);
    TEST_ASSERT_EQUAL_UINT64(
        7ULL, atomic_load_explicit(&(sim.core.speed_num), memory_order_acquire));
    TEST_ASSERT_EQUAL_UINT64(
        1ULL, atomic_load_explicit(&(sim.core.speed_den), memory_order_acquire));

    /* speed=0 (freeze / as-fast-as-possible) is a legitimate value, unlike
     * `step`'s N (which rejects <= 0). */
    handled = repl_cmd_set(&sim, "set speed 0");
    TEST_ASSERT_FALSE(handled);
    TEST_ASSERT_EQUAL_UINT64(0ULL, sim.sim_speed_num);
    TEST_ASSERT_EQUAL_UINT64(
        0ULL, atomic_load_explicit(&(sim.core.speed_num), memory_order_acquire));

    /* Malformed input must be rejected AND leave state unchanged. */
    handled = repl_cmd_set(&sim, "set speed abc");
    TEST_ASSERT_FALSE(handled);
    TEST_ASSERT_EQUAL_UINT64_MESSAGE(0ULL, sim.sim_speed_num,
                                     "a malformed `set speed` argument must "
                                     "not change the current speed");

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

/* ---------------------------------------------------------------------- */
/* Test: `set verify on|off` toggles sim->verify, the exact flag           */
/* sim_loop.c's own decision-verification branch already reads fresh.      */
/* ---------------------------------------------------------------------- */

static void test_set_verify_toggles_flag(void)
{
    xce_sched_sim_driver_t sim;
    bool                    handled;

    memset(&sim, 0, sizeof(sim));
    TEST_ASSERT_FALSE(sim.verify);

    handled = repl_cmd_set(&sim, "set verify on");
    TEST_ASSERT_FALSE(handled);
    TEST_ASSERT_TRUE(sim.verify);

    handled = repl_cmd_set(&sim, "set verify off");
    TEST_ASSERT_FALSE(handled);
    TEST_ASSERT_FALSE(sim.verify);

    /* Malformed value leaves the flag unchanged. */
    handled = repl_cmd_set(&sim, "set verify maybe");
    TEST_ASSERT_FALSE(handled);
    TEST_ASSERT_FALSE_MESSAGE(sim.verify, "a malformed `set verify` "
                                          "argument must not change the "
                                          "current flag");

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

/* ---------------------------------------------------------------------- */
/* Test: `set output <FILE>` opens the file, writes a real                 */
/* ReplayHeader+SnapshotEntry preamble (reusing sim_record.c's own writer, */
/* not hand-rolled), and `set output off` closes it cleanly.               */
/* ---------------------------------------------------------------------- */

static void test_set_output_opens_writes_preamble_and_off_closes(void)
{
    xce_sched_sim_driver_t sim;
    char                    tmp_dir[PATH_MAX];
    char                    out_path[PATH_MAX];
    char                    cmd[PATH_MAX + 32];
    bool                    handled;
    FILE*                   check;
    struct capn             c;
    capn_ptr                root;

    memset(&sim, 0, sizeof(sim));
    TEST_ASSERT_EQUAL_INT(0, xce_sched_core_init(&(sim.core)));
    sim.repl_state = repl_state_ensure(&sim);
    TEST_ASSERT_NOT_NULL(sim.repl_state);

    make_tmp_dir(tmp_dir, sizeof(tmp_dir), "_setoutput");
    snprintf(out_path, sizeof(out_path), "%s/out.replay", tmp_dir);
    snprintf(cmd, sizeof(cmd), "set output %s", out_path);

    handled = repl_cmd_set(&sim, cmd);
    TEST_ASSERT_FALSE(handled);
    TEST_ASSERT_NOT_NULL_MESSAGE(sim.record_file,
                                 "`set output FILE` must open sim->record_file");
    TEST_ASSERT_NOT_NULL(sim.repl_state->output_path);
    TEST_ASSERT_EQUAL_STRING(out_path, sim.repl_state->output_path);

    /* Flush so the reader below sees the two messages already written. */
    fflush(sim.record_file);

    check = fopen(out_path, "rb");
    TEST_ASSERT_NOT_NULL_MESSAGE(check, "the opened output file must exist "
                                        "on disk");
    TEST_ASSERT_EQUAL_INT_MESSAGE(0, capn_init_fp(&c, check, 0),
                                  "first message must be readable capnp");
    TEST_ASSERT_TRUE_MESSAGE(
        msg_root_has_shape(&c, &root, ReplayHeader_word_count,
                           ReplayHeader_pointer_count),
        "first message must be a ReplayHeader");
    capn_free(&c);

    TEST_ASSERT_EQUAL_INT_MESSAGE(0, capn_init_fp(&c, check, 0),
                                  "second message must be readable capnp");
    TEST_ASSERT_TRUE_MESSAGE(
        msg_root_has_shape(&c, &root, SnapshotEntry_word_count,
                           SnapshotEntry_pointer_count),
        "second message must be a SnapshotEntry");
    capn_free(&c);
    fclose(check);

    handled = repl_cmd_set(&sim, "set output off");
    TEST_ASSERT_FALSE(handled);
    TEST_ASSERT_NULL_MESSAGE(sim.record_file, "`set output off` must close "
                                              "sim->record_file");
    TEST_ASSERT_NULL_MESSAGE(sim.repl_state->output_path,
                             "`set output off` must clear the tracked path");

    /* A second `off` while already off must be a harmless no-op. */
    handled = repl_cmd_set(&sim, "set output off");
    TEST_ASSERT_FALSE(handled);
    TEST_ASSERT_NULL(sim.record_file);

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

/* ---------------------------------------------------------------------- */
/* Tests: `set units raw|human|both` (scheduler-sim-repl-verbosity spec,   */
/* task 7.1, Requirement 6.2/6.3).                                         */
/*                                                                          */
/* THESE THREE TESTS ARE RED-PHASE ONLY: neither xce_sched_repl_state_s's   */
/* `units_mode` field, the XCE_REPL_UNITS_RAW/HUMAN/BOTH enum constants,    */
/* nor repl_cmd_set()'s "units" branch exist anywhere in this codebase yet  */
/* -- task 7.2 (a separate, later task) adds all three. Referencing         */
/* `sim.repl_state->units_mode` and the enum constants below is therefore   */
/* expected to fail this file's COMPILATION (no member named 'units_mode', */
/* undeclared identifiers) -- a build failure for the whole translation     */
/* unit, not merely a runtime assertion failure. That build failure IS this */
/* slice's Observable evidence per tasks.md (task 7.1's own text: "the new  */
/* test cases fail against the current codebase, which has neither the      */
/* classifier/scaling helpers nor a `units` setting" -- a compile error is  */
/* a valid, and in this case the actual, form of "fail"). Once task 7.2     */
/* lands the field/enum/branch, these same tests (unmodified) become the    */
/* GREEN-phase proof.                                                       */
/*                                                                          */
/* Direct struct inspection (rs->units_mode) observes the setting rather    */
/* than routing through `info config`: today `info config` reports only     */
/* speed/output/verify/events_processed/current_ts/sessions
 * (test_info_config_reports_current_parameters below), it does not report
 * units_mode, and design.md's Traceability table never lists `info config`
 * as a Resource Value Formatter dependency -- extending it is out of this
 * task's scope (that belongs to task 8, the table-layout task). Direct
 * struct access is the same technique
 * test_set_speed_updates_shadow_and_core_atomics/
 * test_set_verify_toggles_flag already use for their own driver-state
 * fields (sim.sim_speed_num, sim.verify) above.
 */

static void test_set_units_raw_human_both_update_display_mode(void)
{
    xce_sched_sim_driver_t sim;
    bool                    handled;

    memset(&sim, 0, sizeof(sim));
    sim.repl_state = repl_state_ensure(&sim);
    TEST_ASSERT_NOT_NULL(sim.repl_state);

    handled = repl_cmd_set(&sim, "set units raw");
    TEST_ASSERT_FALSE_MESSAGE(handled, "`set` never hands control back");
    TEST_ASSERT_EQUAL_MESSAGE(XCE_REPL_UNITS_RAW, sim.repl_state->units_mode,
                              "`set units raw` must select the raw-only "
                              "display mode");

    handled = repl_cmd_set(&sim, "set units human");
    TEST_ASSERT_FALSE(handled);
    TEST_ASSERT_EQUAL_MESSAGE(
        XCE_REPL_UNITS_HUMAN, sim.repl_state->units_mode,
        "`set units human` must select the human-only display mode");

    handled = repl_cmd_set(&sim, "set units both");
    TEST_ASSERT_FALSE(handled);
    TEST_ASSERT_EQUAL_MESSAGE(
        XCE_REPL_UNITS_BOTH, sim.repl_state->units_mode,
        "`set units both` must select the combined raw+human display mode");

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

static void test_set_units_defaults_to_both_without_explicit_command(void)
{
    xce_sched_sim_driver_t sim;

    memset(&sim, 0, sizeof(sim));
    sim.repl_state = repl_state_ensure(&sim);
    TEST_ASSERT_NOT_NULL(sim.repl_state);

    TEST_ASSERT_EQUAL_MESSAGE(
        XCE_REPL_UNITS_BOTH, sim.repl_state->units_mode,
        "absent an explicit `set units` command, units_mode must default "
        "to `both` (Requirement 6.3) -- design.md's own State Management "
        "section calls this out explicitly as the one field in this struct "
        "that cannot rely on calloc's zero-initialization alone (unless "
        "`both` is deliberately given enum value 0), so repl_state_ensure() "
        "must set it explicitly");

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

static xce_sched_sim_driver_t g_units_invalid_sim;

static void run_set_units_bogus(void)
{
    repl_cmd_set(&g_units_invalid_sim, "set units bogus");
}

static void test_set_units_invalid_value_rejected_like_existing_pattern(void)
{
    char* captured;

    memset(&g_units_invalid_sim, 0, sizeof(g_units_invalid_sim));
    g_units_invalid_sim.repl_state = repl_state_ensure(&g_units_invalid_sim);
    TEST_ASSERT_NOT_NULL(g_units_invalid_sim.repl_state);

    captured = capture_stdout_around(run_set_units_bogus);
    TEST_ASSERT_NOT_NULL_MESSAGE(
        strstr(captured, "set units"),
        "an unrecognized `set units` value must be rejected with a "
        "units-specific usage message -- matching `set speed`'s "
        "\"[sim] set speed: usage: set speed <N>\" and `set verify`'s "
        "\"[sim] set verify: usage: set verify on|off\" per-key "
        "usage-error pattern (repl_params.c), NOT the generic \"[sim] set: "
        "unrecognized parameter 'units'\" message that fires today for an "
        "unrecognized KEY (units IS a recognized key once task 7.2 lands; "
        "only its VALUE here is invalid)");
    TEST_ASSERT_EQUAL_MESSAGE(
        XCE_REPL_UNITS_BOTH, g_units_invalid_sim.repl_state->units_mode,
        "a rejected `set units` value must leave the current display mode "
        "unchanged -- same discipline `set speed`/`set verify`'s own "
        "malformed-input tests already establish for their own fields");
    free(captured);

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

/* ---------------------------------------------------------------------- */
/* Test: `info config` reports speed/output/verify/events_processed/       */
/* current_ts/sessions, both while output is off and while it is active    */
/* with a known path.                                                      */
/* ---------------------------------------------------------------------- */

static xce_sched_sim_driver_t g_cfg_sim;

static void run_info_config(void) { repl_cmd_info(&g_cfg_sim, "info config"); }

static void test_info_config_reports_current_parameters(void)
{
    char* captured;
    char  tmp_dir[PATH_MAX];
    char  out_path[PATH_MAX];
    FILE* real_out;

    memset(&g_cfg_sim, 0, sizeof(g_cfg_sim));
    g_cfg_sim.repl_state = repl_state_ensure(&g_cfg_sim);
    TEST_ASSERT_NOT_NULL(g_cfg_sim.repl_state);

    g_cfg_sim.sim_speed_num             = 3;
    g_cfg_sim.sim_speed_den             = 1;
    g_cfg_sim.verify                    = true;
    g_cfg_sim.repl_state->event_index   = 7;
    g_cfg_sim.repl_state->session_count = 2;
    g_cfg_sim.record_file               = NULL;

    captured = capture_stdout_around(run_info_config);
    TEST_ASSERT_NOT_NULL(strstr(captured, "speed=3"));
    TEST_ASSERT_NOT_NULL(strstr(captured, "output=off"));
    TEST_ASSERT_NOT_NULL(strstr(captured, "verify=on"));
    TEST_ASSERT_NOT_NULL(strstr(captured, "events_processed=7"));
    TEST_ASSERT_NOT_NULL(strstr(captured, "sessions=2"));
    TEST_ASSERT_NOT_NULL(strstr(captured, "current_ts="));
    free(captured);

    /* Now with an active, known output path. */
    make_tmp_dir(tmp_dir, sizeof(tmp_dir), "_infocfg");
    snprintf(out_path, sizeof(out_path), "%s/active.replay", tmp_dir);
    real_out = fopen(out_path, "w");
    TEST_ASSERT_NOT_NULL(real_out);

    g_cfg_sim.record_file           = real_out;
    g_cfg_sim.repl_state->output_path = strdup(out_path);

    captured = capture_stdout_around(run_info_config);
    TEST_ASSERT_NOT_NULL_MESSAGE(strstr(captured, out_path),
                                 "info config must report the active "
                                 "output path when known");
    free(captured);

    fclose(real_out);
    free(g_cfg_sim.repl_state->output_path);

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

/* ---------------------------------------------------------------------- */
/* Test: repl_print_help() lists the task 12.3 commands.                   */
/* ---------------------------------------------------------------------- */

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

static void test_help_lists_snapshot_and_set_commands(void)
{
    char* captured = capture_stdout_around(run_print_help);

    TEST_ASSERT_NOT_NULL(strstr(captured, "snapshot"));
    TEST_ASSERT_NOT_NULL(strstr(captured, "set speed"));
    TEST_ASSERT_NOT_NULL(strstr(captured, "set output"));
    TEST_ASSERT_NOT_NULL(strstr(captured, "set verify"));
    TEST_ASSERT_NOT_NULL(strstr(captured, "info config"));
    free(captured);

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

int main(void)
{
    UNITY_BEGIN();

    RUN_TEST(test_snapshot_written_file_is_loadable_by_fresh_sim_start);
    RUN_TEST(test_snapshot_auto_generates_filename_from_event_index);
    RUN_TEST(test_set_speed_updates_shadow_and_core_atomics);
    RUN_TEST(test_set_verify_toggles_flag);
    RUN_TEST(test_set_output_opens_writes_preamble_and_off_closes);
    RUN_TEST(test_set_units_raw_human_both_update_display_mode);
    RUN_TEST(test_set_units_defaults_to_both_without_explicit_command);
    RUN_TEST(test_set_units_invalid_value_rejected_like_existing_pattern);
    RUN_TEST(test_info_config_reports_current_parameters);
    RUN_TEST(test_help_lists_snapshot_and_set_commands);

    return UNITY_END();
}