lei.chen/myxce
1
0
Fork 1
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

feat(scheduler-core): implement REPL execution control (task 12.1)

Browse source 
Adds the interactive simulation REPL's execution-control slice (Req 5
AC 22): a single-threaded input loop (readline-based) supporting
step [N], continue, quit, and help, pausing before the first replay
event and blocking the driver loop while active.

Review round 1 raised two findings, both resolved here:

- GNU readline (GPL) was linked directly into xce_scheduler, a shipped
  production daemon. Switched the whole project to libedit (BSD) for
  line editing -- scheduler and controller (xce_test) both now use
  editline/readline.h, API-compatible (readline()/add_history()).

- Getting a clean regression run after the libedit swap required a
  full clean rebuild, which exposed a genuine pre-existing SIGSEGV
  (bug-1504): SnapshotData.internalState was a capnp Data field, and
  this codebase's capnpc-c backend silently no-ops Data-field
  encoding without zero-initializing the caller's stack struct,
  leaving an uninitialized capn_ptr written onto the wire. Fixed by
  switching internalState to List(UInt8) (with a new internalStateLen
  wire field), matching the working FetchFileReply.content/bytesRead
  precedent -- no hand-written accessor code needed.

A second, unrelated instance of the same bug class was found in the
controller's WAL-catchup path (WalCatchupEntry.payload) and
deliberately left unfixed as bug-1505, out of scheduler-core's
boundary; needs its own project-wide Data-field audit.

Scheduler suite: 34/34 clean. RED-phase reproduction recorded in
tasks.md (repl_should_pause() step-budget check disabled -> 2/4
tests fail as expected -> reverted -> 34/34 green).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JPPXeKSUXUqcqvzNXY1rzJ
This commit is contained in:
Rongsong Shen 2026-08-07 08:17:35 +00:00
parent de00ccff37
commit 02f7f48ff9
Signed by: rshen
SSH key fingerprint: SHA256:8Vf2pZ3h6rJa7EhGK+WaAQ9Mta/apZvteW6g9U/WKKk
17 changed files with 1491 additions and 81 deletions
Download patch file Download diff file Expand all files Collapse all files

7
.kiro/specs/scheduler-core/tasks.md
View file

@ -354,12 +354,13 @@
- [ ] 12. Core: Interactive REPL
- [ ] 12.1 Implement REPL execution control
- [x] 12.1 Implement REPL execution control
- Implement a single input-loop REPL (not a separate thread) that pauses before the first event and blocks the simulation loop while active, supporting step-N-sessions, continue-to-next-breakpoint-or-EOF, and quit
- Observable: starting simulation with the REPL enabled pauses before any event is processed; issuing a step command advances exactly the requested number of sessions and returns control to the prompt
- _Requirements: 5.22_
- _Note: use readline() for the input loop's line editing (history, arrow keys) — xce_test's REPL already sets this precedent (src/controller/testsuite/test.c:3827) and readline is already a linked project dependency, zero new cost. Confirm readline's GPL licensing is acceptable for this build target before committing to it (vs. libedit/linenoise) if that hasn't already been settled elsewhere in the codebase._
- _Note: use readline() for the input loop's line editing (history, arrow keys) — xce_test's REPL already sets this precedent (src/controller/testsuite/test.c:3827) and readline is already a linked project dependency, zero new cost. Confirm readline's GPL licensing is acceptable for this build target before committing to it (vs. libedit/linenoise) if that hasn't already been settled elsewhere in the codebase._ **Resolved: switched project-wide to libedit (BSD) instead — see Implementation Notes.**
- _Depends: 11.2_
- _Verified: RED-phase reproduction performed during review round 2 — temporarily changed `repl_should_pause()` (repl.c) from `return (rs->step_budget <= 0);` to `return false;`, rebuilt, ran `sched_repl_execution_control_test`: 2/4 tests failed exactly as expected (`test_should_pause_fires_on_exactly_the_nth_session`, `test_step_1_processes_exactly_one_session_then_quit_exits`), the 2 unrelated tests (`test_should_pause_never_fires_in_continue_mode`, `test_pre_replay_pause_blocks_before_any_event_is_processed`) stayed green. Reverted; rebuilt; full scheduler suite 34/34 GREEN._
- [ ] 12.2 Implement REPL breakpoints and state inspection
- Support setting/listing/deleting breakpoints on event type with optional field filters, and inspection commands reporting current simulation position, and job/queue/worker/resource/summary state
@ -402,3 +403,5 @@
- Task 9.3's review found a genuine task-breakdown gap, not fixable within 9.3's own boundary: `record_snapshot_interval` (the field task 9.3's periodic-checkpoint mechanism reads) has no CLI or admin-request wiring anywhere in the codebase — `--record-snapshot-interval` appears in AC 11's own normative text but in zero task's actual scope. Neither task 9.4 (admin request handler — dispatches `SchedAdminRequest` actions, which don't carry an interval field either, per controller.capnp's `SchedAdminRequest{action, recordFile}`) nor group 10 (controller-side dispatch) owns scheduler startup CLI flags; only `main.c`'s argp table does, following task 9.1's own `--record-dir` precedent. As currently scoped, AC 11's mechanism is fully implemented and tested (via the struct field directly) but has no path to ever be configured non-zero in a real deployment. Needs a small follow-up task before this spec is considered complete: add a `--record-snapshot-interval N` CLI flag to `main.c`, wired to `sched.record_snapshot_interval`, mirroring `--record-dir`'s exact pattern (task 9.1).
- Task 9.3's review also flagged `test_record_lifecycle.c`'s size (826→1232 lines across tasks 9.2+9.3) as past this suite's established over-800 precedent (prior max `test_driver_translate.c`≈867) — the content itself is genuine, non-duplicative coverage (not padding), and a natural split point exists along the AC10 (lifecycle/TOCTOU)/AC11 (periodic-checkpoint/error-handling) seam by extracting shared fixture helpers into a common header. Non-blocking; worth a future cleanup pass, not urgent.
- Cross-task interaction, flagged before task 9.4 exists — resolution decided (not a fail/retry, a deferral): task 9.2's `sched_record_start()` calls `xce_sched_core_save_snapshot()` as its first action (AC 10 step 1) — the same function task 8.2 gated to return `-EBUSY` whenever `session_active != 0`. `main.c`'s driver loop is single-threaded (`while(1) { xce_sched_driver_run_normal_mode_round(&sched); ...; sleep(1); }`); incoming requests (including the future `SchedAdminRequest`) arrive asynchronously via `scheduler_req_handler` (handler.c) on the I/O side, same as job/queue/worker updates. **Decision**: task 9.4 must NOT call `sched_record_start()` directly from the request-handling thread (that both risks racing `session_active` and violates this codebase's async-I/O rule against blocking/file-I/O in a request-handler callback). Instead, `recordStart` must be enqueued the same way job/queue/worker updates already are (`pend_updates` dataq or an equivalent dedicated pending-admin-request slot) and picked up by `xce_sched_driver_translate_pending_events()` — which already runs at the top of every round, strictly before `begin_session()`, so it is guaranteed between-sessions by the same construction argument design.md uses for `core_push_events()`. This means recording "takes effect" at the next scheduling round, not synchronously on request arrival. Consequence for task 9.4: since AC 10 specifies a synchronous request-reply carrying the resolved filename, the actual `SchedAdminReply` send must be deferred until the driver thread performs the queued start (not sent eagerly from the handler thread) — needs a completion signal back to the waiting request context (e.g. a condition variable, or replying once `xce_sched_driver_translate_pending_events()` reports the deferred start applied). Given this deferral makes the direct `-EBUSY` race effectively unreachable from the admin path, the AC 10 error-codes table doesn't need a new "busy" entry for this case — `sched_record_start()` keeps its `-EBUSY` return as a defensive/fail-loud contract check (task 9.2's job, no torn state), it just should no longer be a path task 9.4's dispatch can actually trigger by construction.
- Task 12.1's review found a licensing gap (fixed): the readline()-based REPL input loop originally linked GNU readline (GPL) directly into `xce_scheduler`, a shipped production daemon (unlike `xce_test`, a debug-only binary controller's own readline use was already confined to). Switched project-wide to libedit (BSD) — `nixSupport/xce.nix`, both `meson.build`s, `repl.c`, and `src/controller/testsuite/test.c` now use `editline/readline.h` (API-compatible: `readline()`/`add_history()`), no hand-written accessor changes needed anywhere.
- Task 12.1's review also surfaced bug-1504 (fixed) and bug-1505 (deferred, out of boundary) — see `.wolf/buglog.json`. Verifying the licensing fix required a full clean rebuild (new nix dependency), which exposed a genuine, pre-existing, deterministic SIGSEGV in `write_SnapshotData` unrelated to task 12.1's own repl.c: `SnapshotData.internalState` was a capnp `Data` field, and this codebase's capnpc-c backend silently no-ops Data-field encoding in generated `encode_XXX()` helpers without zero-initializing the caller's stack struct first — a real, reproducible UB crash, not a flaky test. Fixed (bug-1504) by switching `internalState` to `List(UInt8)` (controller.capnp, typemap.h, test_e2e_capnp.c) — this same capnpc-c backend DOES correctly auto-generate real encode/decode for `List(UInt8)` (proven precedent: `FetchFileReply.content`/`bytesRead`), eliminating the whole no-op class for this field with no hand-written accessor code. Re-verified with a full clean rebuild: scheduler suite 34/34, no regressions. While chasing this, also hit a **second, unrelated instance of the same bug class** in the controller's HA/WAL-catchup subsystem (`WalCatchupEntry.payload`, bug-847's own territory) — confirmed systemic (affects any `:Data` field in `controller.capnp` fed through the generic codec, not a one-off) but deliberately **left unfixed** (bug-1505) as out of scheduler-core's boundary; needs its own project-wide `:Data`-field audit as a separate task.

175
.wolf/buglog.json
View file

@ -14667,5 +14667,178 @@
"related_bugs": [],
"occurrences": 1,
"last_seen": "2026-08-04T00:00:00Z"
},
{
"id": "bug-1498",
"timestamp": "2026-08-05T00:00:00Z",
"error_message": "test_toctou_hardlink_planted_after_validation_rejected FAILED: Expected Non-NULL -- fgets() on the outside 'victim' file returned NULL (file was 0 bytes) after the TOCTOU regression test ran, even though sched_record_start()/the reproduced open-hardening sequence both correctly REJECTED the hard-link swap and returned an error.",
"file": "src/scheduler/src/recording.c",
"root_cause": "sched_record_start()'s TOCTOU-hardened open used O_WRONLY|O_CREAT|O_TRUNC|O_NOFOLLOW. O_TRUNC truncates the target atomically as PART OF the open(2) syscall itself, before any userspace code -- including the fstat()+st_nlink==1 safety check right after open() -- ever runs. Against a hard-linked victim (same inode as the outside file, no symlink involved so O_NOFOLLOW never triggers), open() succeeds and O_TRUNC immediately zeroes the shared inode's content; the subsequent st_nlink>1 check then correctly rejects and closes the fd, but the outside victim file was already corrupted by that point. The check ran too late to matter -- classic 'check-after-side-effect' TOCTOU-adjacent bug, caught by the test's own outside-file-content assertion (added specifically to prove containment, not just that the return code was negative).",
"fix": "Removed O_TRUNC from the initial open() flags (now O_WRONLY|O_CREAT|O_NOFOLLOW). After fstat()+st_nlink==1 passes, explicitly call ftruncate(fd, 0) to get the same truncate-on-legitimate-overwrite behavior, but only once safety is verified. Same fix applied to the test's own toctou_hardened_open() helper (a verbatim reproduction of the production sequence, used because a literal multi-threaded race against sched_record_start()'s few-instruction internal window would be flaky).",
"tags": [
"scheduler-core",
"task-9.2",
"recording.c",
"toctou",
"hardlink",
"O_TRUNC",
"check-after-side-effect",
"sched_record_start"
],
"related_bugs": [],
"occurrences": 1,
"last_seen": "2026-08-05T00:00:00Z"
},
{
"id": "bug-1499",
"timestamp": "2026-08-05T00:00:00Z",
"error_message": "sched_driver_session_ordering_test TIMEOUT (30s, killed by SIGTERM) after adding task 9.2's recording-write hooks to xce_sched_driver_run_normal_mode_round() -- picker thread, allocator thread, and the main round all blocked forever.",
"file": "src/scheduler/src/driver.c",
"root_cause": "While inserting the new 'if (sched->recording) { rec_ctx = sched_record_session_begin(...); }' block between plugin_begin_session()/sched_account_jobs() and the decision-drain loop, the pre-existing `xce_core_signal_go(&(sched->core));` call was accidentally dropped from the Edit's old_string/new_string pair -- it was the last line of the block being replaced but was not included in the replacement text. Without xce_core_signal_go(), the picker thread's cbuf_get(&core->wbuf) rendezvous never unblocks, which cascades: the stand-in allocator thread never receives a jobid from cbuf_get(&core->jbuf), so it never pushes the end-of-session NULL decision, so the main thread's own cbuf_get(&core->decisions) drain loop blocks forever -- a 3-way deadlock across all three threads.",
"fix": "Restored `xce_core_signal_go(&(sched->core));` immediately after the new recording session-begin block (matching requirements.md's own annotated pseudocode order: build ReplaySession{beginRound} THEN sched_go()). Caught by re-running the full scheduler test suite after the recording hooks were added -- test_driver_session_ordering.c is the ONLY test in the suite that drives a real picker/allocator thread pair through this exact function, so it was the only test capable of catching a signal_go() regression.",
"tags": [
"scheduler-core",
"task-9.2",
"driver.c",
"deadlock",
"xce_core_signal_go",
"accidental-deletion-in-edit",
"xce_sched_driver_run_normal_mode_round"
],
"related_bugs": [],
"occurrences": 1,
"last_seen": "2026-08-05T00:00:00Z"
},
{
"id": "bug-1500",
"timestamp": "2026-08-06T00:00:00Z",
"error_message": "test_run_processes_multiple_sessions_in_order_and_no_longer_returns_enosys FAIL: Expected 5000 Was 743938186628040 (a raw-looking CLOCK_MONOTONIC nanosecond value, not the fixture's own beginRound).",
"file": "src/scheduler/testsuite/test_sim_event_loop.c",
"root_cause": "The test's fixture-building helper called the real sched_record_start() THEN sched_record_stop() to produce a valid header+snapshot prefix (matching test_sim_startup.c's own write_valid_fixture() precedent), then re-opened the same path in append mode ('a') to hand-write additional ReplayEvent/ReplaySession messages after it. But sched_record_stop() (recording.c) unconditionally writes its OWN ReplayEvent{endSession} marker immediately after the snapshot as part of every completed recording (Req 5 AC 20) -- so the fixture already contained a premature end-of-stream marker BEFORE any of the test's own appended events/sessions. sched_sim_driver_run()'s event loop (sim_loop.c, task 11.2) correctly treats ReplayEvent{endSession} as the whole-stream termination signal and stopped reading right there, leaving sim->core's clock at its xce_sched_core_init() default (virtual_clock_base=0, speed_num=1, speed_den=1 -- AC 3's normal-mode row), so xce_core_now() returned an unfrozen, elapsed-wall-clock-driven value instead of the intended frozen 5000.",
"fix": "Changed the fixture helper to call ONLY sched_record_start() (never sched_record_stop()), and return the STILL-OPEN FILE* (sched.record_file) so the test appends its own hand-built events/sessions directly onto the same open stream, ending with its own append_end_of_stream_marker() call, then fclose()s it directly -- bypassing sched_record_stop()'s real event/session-recording API entirely for this hand-built-fixture use case.",
"tags": [
"scheduler-core",
"task-11.2",
"sim_loop.c",
"test-fixture",
"sched_record_stop",
"ReplayEvent_body_endSession",
"premature-termination-marker"
],
"related_bugs": [],
"occurrences": 1,
"last_seen": "2026-08-06T00:00:00Z"
},
{
"id": "bug-1501",
"timestamp": "2026-08-07T00:00:00Z",
"error_message": "gcc: 'expected =, ,, ;, asm or __attribute__ before is' / 'unknown type name is' / 'missing terminating character' cascade starting at sim_verify.c:59, plus 'implicit declaration of function sim_verify_str_eq' further down.",
"file": "src/scheduler/src/sim_verify.c",
"root_cause": "File header doc comment's Comparison-strategy paragraph wrote the literal text 'xce_job_alloc_t*/xce_pendreason_t*' to mean 'an xce_job_alloc_t pointer or an xce_pendreason_t pointer' -- the '*/' substring is C's block-comment CLOSE token, so the /* ... */ doc comment terminated early, right in the middle of prose. Everything from that point until the next real */ (the following function's own closing delimiter) was parsed as C code, producing a cascade of nonsense syntax errors and, once the compiler resynced, an implicit-declaration warning/error for a function whose real prototype/definition had been swallowed into the truncated comment. Exact recurrence of the bug-1493 pattern already logged for typemap.h (same 'accidental */ in a C block comment' root cause).",
"fix": "Reworded to 'xce_job_alloc_t* or xce_pendreason_t*' (space before 'or' instead of a bare slash-star-slash-adjacent sequence), eliminating the literal '*/' substring. Ran a repo grep for the same '[A-Za-z_]*/[A-Za-z_]' pattern across both new/modified files (sim_verify.c, sim_loop.c) before rebuilding to rule out a second occurrence.",
"tags": [
"scheduler-core",
"task-11.4",
"sim_verify.c",
"block-comment",
"accidental-comment-close",
"bug-1493-recurrence",
"build-failure"
],
"related_bugs": [
"bug-1493"
],
"occurrences": 1,
"last_seen": "2026-08-07T00:00:00Z"
},
{
"id": "bug-1502",
"timestamp": "2026-08-07T00:00:00Z",
"error_message": "Task 11.5 review round 1 REJECTED: previous implementer's self-reported RED-phase evidence (git stash of 4 'behavioral production files' -> 3 tests failing under meson test) did not reproduce -- reviewer got a hard ninja build failure instead (test_sim_event_loop.c:467 calling sim_process_replay_event_message with 5 args against a stashed-back 4-arg sim_loop.c declaration).",
"file": "src/scheduler/src/sim_loop.c",
"root_cause": "git stash scoped to only 4 production files silently desyncs test files (which already call the NEW post-task-11.5 signatures/behavior) against the stashed-back OLD production code -- a stash-based RED probe is not a valid methodology whenever tests and production code changed together in the same commit-to-be. The previous implementer's reported failure counts were therefore not reproducible as described.",
"fix": "Replaced the stash approach with a direct, targeted, in-place temporary edit of ONLY the behavioral logic inside sim_loop.c (never touching test files, sim_record.c, sim.c/sim.h, recording_session.c/recording.h, or either meson.build): hardcoded event_src to sim->replay_file (defeats AC16 what-if branching) and wrapped the 3 --sim-output write gates (header/snapshot, event pass-through, session-write via record_ctx) in 'if (0 && ...)' no-ops (defeats AC19). Rebuilt+ran `meson test -C xce.build --suite scheduler`: real RED = 30/32, sched_sim_alt_events_test and sched_sim_record_output_test FAIL with concrete assertion messages. Reverted all 4 edits using the exact original text; confirmed via `git diff src/scheduler/src/sim_loop.c` that only the original (pre-probe) task-11.5 diff remained, no probe residue (grep for 'TEMP RED-PHASE PROBE' and 'if (0 &&' both zero matches). Rebuilt+reran: 32/32 green again.",
"tags": [
"scheduler-core",
"task-11.5",
"sim_loop.c",
"red-phase-evidence",
"review-rejection",
"git-stash-pitfall",
"methodology"
],
"related_bugs": [],
"occurrences": 1,
"last_seen": "2026-08-07T00:00:00Z"
},
{
"id": "bug-1503",
"timestamp": "2026-08-07T03:11:00Z",
"error_message": "AddressSanitizer: attempting free on address which was not malloc()-ed, inside free_QueueConf() <- free_QueueConf_ptr() <- release_translated_payload() (driver.c) <- xce_sched_driver_translate_pending_events(). Crashing pointer was 56 bytes inside a 61-byte region allocated by makeString()->makeInstance().",
"file": "src/scheduler/testsuite/test_sim_equivalence.c",
"root_cause": "makeString() (lib/xstring.c) is backed by the vendored rtti library makeInstance() allocator, which does NOT return a plain malloc()-compatible pointer at offset 0 of its allocation (it returns a pointer into a larger rtti-managed block). Elsewhere in the codebase makeString()-allocated strings are safe because they are only ever released by the SAME rtti-aware teardown path that created them (e.g. kill_sched_* killers, or never freed at all in white-box test fixtures). This new test constructed xce_queue_t/xce_job_t fixtures with q->queue/submit->queue/user/project_name/resreq set via makeString(), then drove them through the REAL production cleanup path release_translated_payload() (driver.c), whose free_QueueConf_ptr()/free_Job_ptr() (controller.capnp.c, capnp-generated) call plain free() on those fields directly -- exactly the mismatch: an rtti-backed allocation freed via plain free().",
"fix": "Replaced every makeString() call used to populate xce_queue_t.queue / xce_job_t.submit->{queue,user,project_name,resreq} in test_sim_equivalence.c with strdup(), which returns a plain malloc()-compatible buffer safe for free_QueueConf_ptr()/free_Job_ptr() to free directly. Confirmed clean (no ASan bad-free) after the fix, full scheduler suite (33/33) green.",
"tags": [
"scheduler-core",
"makeString",
"strdup",
"asan",
"bad-free",
"driver.c",
"task-11.6"
],
"related_bugs": [],
"occurrences": 1,
"last_seen": "2026-08-07T03:11:00Z"
},
{
"id": "bug-1504",
"timestamp": "2026-08-07T08:00:00Z",
"error_message": "sched_sim_startup_test SIGSEGV in write_SnapshotData (lib/controller.capnp.c) -- deterministic crash inside libCapnC_Runtime's read_ptr/capn_setp, discovered during scheduler-core task 12.1 review remediation (full clean rebuild needed for a libedit dependency swap).",
"file": "src/schema/controller.capnp",
"root_cause": "SnapshotData.internalState was declared `:Data` in the capnp schema. This codebase's capnpc-c backend silently no-ops Data-field encoding inside generated encode_XXX() composite helpers (documented, deliberate limitation -- see controller.capnp's own prior comment citing ReplayHeader.configHash). But encode_SnapshotData_ptr()'s local `struct SnapshotData d;` is never zero-initialized before the (partially no-op) encode_SnapshotData() populates it, so the skipped Data field's capn_ptr is left as UNINITIALIZED STACK GARBAGE. write_SnapshotData() then unconditionally capn_setp()'s that garbage onto the wire. This is genuine UB: whether it crashes depends entirely on what garbage bytes land in that stack slot at each call site -- ReplayHeader.configHash has the identical gap but never crashed (lucky garbage); SnapshotData.internalState's stack layout in this one test's call chain was unlucky. A prior 'rm -rf xce.build' full rebuild (needed to pick up a new nix dependency) perturbed the whole binary's layout enough to flip this from dormant to a deterministic, reproducible SIGSEGV.",
"fix": "Changed SnapshotData.internalState from `Data` to `List(UInt8)` in controller.capnp, with a new companion internalStateLen (@11, UInt32) wire field for the maplistcount -- following the exact working precedent of FetchFileReply.content/bytesRead, which this same capnpc-c backend DOES correctly auto-generate real (non-no-op) encode/decode for (capn_new_list8/capn_set8 loop, not a placeholder comment). Updated typemap.h's sched_snapshot_data_t.internal_state_len from size_t to uint32_t to match the wire type, and updated test_e2e_capnp.c's test_snapshot_data_round_trip (which previously worked around the Data no-op with a manual low-level SnapshotData_get/set_internalState accessor) to rely on the now-working ordinary codec bridge instead. No hand-written low-level accessor code needed any more for this field.",
"tags": [
"scheduler-core",
"task-12.1",
"capnp-schema",
"codegen-limitation",
"sigsegv",
"uninitialized-memory",
"controller.capnp",
"snapshot"
],
"related_bugs": [
"bug-1493",
"bug-1505"
],
"occurrences": 1,
"last_seen": "2026-08-07T08:00:00Z"
},
{
"id": "bug-1505",
"timestamp": "2026-08-07T08:10:00Z",
"error_message": "controller_unit_test SIGSEGV in write_WalCatchupEntry (lib/controller.capnp.c), test_wal_catchup_append_term_fields_round_trip -- discovered incidentally while chasing bug-1504; NOT fixed, logged for its own follow-up.",
"file": "src/schema/controller.capnp",
"root_cause": "Same root cause as bug-1504 (Data-field codegen no-op leaves an uninitialized stack capn_ptr in the generated encode_XXX_ptr()'s local struct), a DIFFERENT field: WalCatchupEntry.payload (@2: Data), in the controller's HA/WAL-catchup subsystem (bug-847's own territory -- see controller.capnp's comment there), entirely unrelated to scheduler-core. Confirms this is a systemic, project-wide bug class affecting every `:Data` field in controller.capnp whose bytes are populated via the generic encode_XXX()/write_XXX() composite pipeline rather than fully hand-written low-level accessor code -- not a one-off. Known/suspected other Data fields with the same latent gap: ReplayHeader.configHash (dormant so far, no real consumer), CtrlHelloRequest.key, and possibly others not yet audited.",
"fix": "NOT FIXED. Deliberately deferred -- out of scheduler-core task 12.1's boundary (this is the controller's HA/WAL-replication subsystem), and a proper fix requires a project-wide audit of every `:Data` field in controller.capnp to decide case-by-case: convert to List(UInt8) (bug-1504's fix, when the field is genuinely a flat byte blob with no cross-segment/per-element concerns) vs. keep Data with real hand-written low-level accessor code at every encode/decode call site (matching the batchPayloads precedent, when List(UInt8) risks bug-847's per-element far-pointer loss for repeated/batch structures). Needs its own scoped task, not a one-off patch.",
"tags": [
"controller",
"ha",
"wal-catchup",
"capnp-schema",
"codegen-limitation",
"sigsegv",
"uninitialized-memory",
"controller.capnp",
"deferred",
"systemic"
],
"related_bugs": [
"bug-1504",
"bug-847"
],
"occurrences": 1,
"last_seen": "2026-08-07T08:10:00Z"
}
]
]

13
src/controller/meson.build
View file

@ -56,9 +56,12 @@ controller = executable('xce_controller',
xce_test_src = [ 'testsuite/test.c', 'testsuite/waldump.c', 'testsuite/walcompare.c', 'testsuite/snapverify.c', 'testsuite/snapdiff.c', 'testsuite/configcompare.c']
readline_dep = dependency('readline')
ncurses_dep = dependency('ncurses')
history_dep = dependency('history')
# BSD-licensed readline replacement (scheduler-core spec, task 12.1 review
# finding): GNU readline is GPL; xce_test's REPL only needs readline()/
# add_history(), both provided by libedit's editline/readline.h emulation
# header under a permissive license. Single dependency, no separate
# ncurses/history split (libedit's own .pc pulls ncurses in privately).
libedit_dep = dependency('libedit')
ssl_dep = dependency('openssl') # also needed by configcompare.c (SHA256());
# controller_unit_test_deps below re-assigns
# the same dependency() result, harmless
@ -67,9 +70,7 @@ xce_test_deps = [
libxce_dep,
librtti_dep,
struct2json_dep,
readline_dep,
history_dep,
ncurses_dep,
libedit_dep,
tinylog_dep,
zlib_dep, # waldump: crc32 WAL validation
c_capnproto_dep, # waldump: decode JOB_SUBMIT jobid

5
src/controller/testsuite/test.c
View file

@ -10,8 +10,9 @@
#include <time.h>
#include <unistd.h>
#include <readline/history.h>
#include <readline/readline.h>
#include <editline/readline.h> /* libedit (BSD) -- provides readline()/
* add_history(), same as GNU readline's
* split readline.h/history.h pair */
#include <cjson/cJSON.h>
#include <cjson/s2j.h>

43
src/controller/testsuite/test_e2e_capnp.c
View file

@ -1080,14 +1080,16 @@ static void test_replay_decision_dispatch_union_round_trip(void)
/* non-trivial data (including >=1 entry in each of the top-level */
/* List(...) fields: queues/users/projects) and round-trips them */
/* field-for-field through encode_SnapshotData_ptr/decode_SnapshotData */
/* -- EXCEPT internalState (a Data field), whose generated codec is a */
/* documented no-op (same limitation as every other Data field in this */
/* schema, e.g. ReplayHeader.configHash in Test 7) -- verified instead */
/* via the low-level SnapshotData_get/set_internalState accessor on the */
/* SAME struct pointer the codec bridge already populated, same hybrid */
/* technique used nowhere else in this file but safe because encode_/ */
/* set_ operate on independent field slots of one already-allocated */
/* capnp struct. */
/* -- INCLUDING internalState, which is List(UInt8) (task 12.1 review */
/* finding: was Data, whose generated codec is a silent no-op in this */
/* codebase's capnpc-c setup and left write_SnapshotData() writing an */
/* uninitialized stack capn_ptr onto the wire -- a real, reproducible */
/* crash; see controller.capnp's SnapshotData comment for the full */
/* story). List(UInt8) gets a real generated encode_/decode_ (same */
/* precedent as FetchFileReply.content/bytesRead), so internal_state/ */
/* internal_state_len round-trip through the ordinary codec bridge */
/* like every other field here -- no low-level accessor workaround */
/* needed any more. */
/* */
/* Also demonstrates this task's internalVersion Observable: "a */
/* snapshot encoded with one internal-state version and decoded */
@ -1228,14 +1230,6 @@ static void test_snapshot_data_round_trip(void)
SnapshotData_ptr p;
encode_SnapshotData_ptr(cs, &p, &src);
/* internalState (Data field): codec no-op, set via low-level accessor
* on the same already-allocated struct pointer (see comment above). */
capn_list8 state_list = capn_new_list8(cs, (int)sizeof(internal_bytes));
capn_setv8(state_list, 0, internal_bytes, sizeof(internal_bytes));
capn_data state_data;
state_data.p = state_list.p;
SnapshotData_set_internalState(p, state_data);
capn_setp(capn_root(&c), 0, p.p);
int64_t sz = capn_size(&c);
TEST_ASSERT_TRUE(sz > 0);
@ -1316,16 +1310,13 @@ static void test_snapshot_data_round_trip(void)
TEST_ASSERT_EQUAL_UINT64(123456789ULL, dst.prng_seed);
TEST_ASSERT_EQUAL_UINT32(2u, dst.internal_version);
/* internalState -- low-level accessor read-back (Data field, codec
* no-op; see comment above). */
capn_data out_state = SnapshotData_get_internalState(dp);
TEST_ASSERT_EQUAL_INT((int)sizeof(internal_bytes),
capn_len((capn_list8){ out_state.p }));
uint8_t out_state_bytes[sizeof(internal_bytes)];
TEST_ASSERT_EQUAL_INT((int)sizeof(internal_bytes),
capn_getv8((capn_list8){ out_state.p }, 0,
out_state_bytes, sizeof(internal_bytes)));
TEST_ASSERT_EQUAL_MEMORY(internal_bytes, out_state_bytes, sizeof(internal_bytes));
/* internalState -- ordinary codec-bridge read-back (List(UInt8), real
* generated decode; see comment above). */
TEST_ASSERT_EQUAL_UINT32((uint32_t)sizeof(internal_bytes),
dst.internal_state_len);
TEST_ASSERT_NOT_NULL(dst.internal_state);
TEST_ASSERT_EQUAL_MEMORY(internal_bytes, dst.internal_state,
sizeof(internal_bytes));
/* Observable: version-mismatch rejection. A reader that expects the
* SAME internal_version accepts; a reader that expects a DIFFERENT

22
src/include/typemap.h
View file

@ -623,13 +623,19 @@ typedef struct {
* placeholder wholesale. Every domain-object pointer reuses a pre-existing
* native type (already used natively throughout the scheduler/controller)
* except users/projects (sched_snapshot_user_t/sched_snapshot_project_t
* above) and the two scheduler-internal-only opaque fields. internal_state
* follows the same raw uint8_t-pointer + size_t pattern as every other Data
* field in this file (e.g. replay_header_t.config_hash above) -- the generated
* encode_SnapshotData/decode_SnapshotData codec is a documented no-op for
* it; real extraction is task 9+ hand-written code. internal_version is a
* format tag for internal_state so an incompatible future internal layout
* is rejected rather than misinterpreted (this task's Observable). */
* above) and the two scheduler-internal-only opaque fields. internal_version
* is a format tag for internal_state so an incompatible future internal
* layout is rejected rather than misinterpreted (this task's Observable).
*
* internal_state/internal_state_len map controller.capnp's internalState,
* a List(UInt8) (task 12.1 review finding, fixed -- was Data, whose
* generated codec is a silent no-op in this codebase's capnpc-c setup and
* left a genuinely uninitialized capn_ptr on the wire, a real reproducible
* crash; see controller.capnp's SnapshotData comment for the full story).
* List(UInt8)'s generated encode_/decode_ actually runs (proven precedent:
* xce_fetchfile_reply_t.content/bytes_read below), so internal_state_len
* must be uint32_t to match internalStateLen's UInt32 wire type -- same
* maplistcount convention as content/bytes_read. */
typedef struct {
xce_conf4sched_t *config;
xce_jobs_data_t *jobs;
@ -644,7 +650,7 @@ typedef struct {
int n_projects;
uint64_t prng_seed;
uint8_t *internal_state;
size_t internal_state_len;
uint32_t internal_state_len;
uint32_t internal_version;
} sched_snapshot_data_t;

8
src/nixSupport/xce.nix
View file

@ -30,8 +30,12 @@ stdenv.mkDerivation {
separateDebugInfo = true;
}))
libtirpc
readline
ncurses
# BSD-licensed readline replacement (task 12.1, scheduler-core spec):
# GNU readline is GPL and would encumber xce_scheduler/xce_test's own
# licensing once linked into a production/shipped binary; libedit's
# editline/readline.h header is API-compatible (readline()/add_history())
# so callers change only their #include, not their calls.
libedit
struct2json
(capnpc.overrideAttrs (oldAttrs: {
separateDebugInfo = true;

82
src/scheduler/include/repl.h Normal file
View file

@ -0,0 +1,82 @@
#if !defined(_REPL_H_)
#define _REPL_H_ 1
#include "sim.h"
/*
* repl.h - interactive simulation REPL, execution-control slice (scheduler-
* core spec, task 12.1, Req 5 AC 22). New file per design.md's File
* Structure Plan ("repl.c -- NEW (Phase 3): interactive REPL command loop
* (Req 5 AC 22)"), Phase 3, sibling to sim.h/sim.c/sim_loop.c.
*
* This header declares repl.c's two driver-facing entry points, plus two
* `static inline` wrappers that fold the `sim->interactive` gate INTO the
* header itself. That inline-wrapper indirection is a deliberate, judgment-
* based deviation from this file family's usual "extern declared where
* consumed, no dedicated header" convention (sim_verify.c/sim_record.c/
* recording_session.c's entry points are all extern-declared directly
* inside sim_loop.c -- see that file's own header comment): sim_loop.c was
* already at 796/800 lines (this project's per-file cap, CLAUDE.md) before
* this task, leaving no room for even one bare `if (sim->interactive) { ...
* }` block at each of the two call sites design.md's REPL integration
* pseudocode requires (pre-replay pause, post-session pause), let alone two.
* Moving the gate into these inline wrappers keeps sim_loop.c's own diff to
* two single-line, brace-free call expressions -- this task's own text
* anticipates exactly this fallback ("move the hook logic into a tiny
* static inline helper in repl.h, or extract something unrelated out of
* sim_loop.c"). The two real functions (`xce_repl_start`/
* `xce_repl_post_session_check`) still carry the actual logic; a `static
* inline` here costs nothing at link time (each including TU gets its own
* copy, trivially small, no ODR risk -- sim_loop.c is the only production
* consumer).
*
* Boundary (Req 5 AC 17, "Simulation isolation", same as sim.h): this header
* only depends on sim.h (itself core.h + stdbool/stdint/stdio) -- no
* scheduler.h, no client.h, no capnp types. repl.c's own file header
* comment documents the same boundary for its implementation.
*/
/*
* xce_repl_start - the pre-replay pause (Req 5 AC 22's interaction model:
* "blocks on stdin at startup"). Prints the load banner ("[sim] loaded: ...
* snapshot @ ts=...", "[sim] ready. type 'help' for commands.") then enters
* the REPL command loop, blocking on stdin until the operator issues a
* command that hands control back (`step [N]`/`continue`) or terminates the
* process (`quit`, which never returns). Called once, by
* sched_sim_driver_run() (sim_loop.c), strictly before its event loop's
* `for(;;)` begins -- see xce_repl_pre_replay_pause() below for the actual
* production call site.
*/
extern void xce_repl_start(xce_sched_sim_driver_t* sim);
/*
* xce_repl_post_session_check - the per-session pause-decision point (Req 5
* AC 22's interaction model: "blocks on stdin ... at each breakpoint hit";
* task 12.1's own narrower scope: only a `step N` budget reaching zero, no
* breakpoints yet). Called once per completed ReplaySession, immediately
* after xce_core_end_session() (sim_loop.c), when sim->interactive is set.
* Internally decides whether to pause (a `step` budget hit zero; `continue`
* mode never pauses here in 12.1's scope) and, if so, re-enters the same
* blocking command loop xce_repl_start() uses. Task 12.2's own seam: it
* extends the INTERNAL pause decision (repl.c) to also check a breakpoint
* list -- this function's signature and sim_loop.c's own call site are not
* expected to change.
*/
extern void xce_repl_post_session_check(xce_sched_sim_driver_t* sim);
static inline void xce_repl_pre_replay_pause(xce_sched_sim_driver_t* sim)
{
if (sim->interactive) {
xce_repl_start(sim);
}
}
static inline void xce_repl_post_session_pause(xce_sched_sim_driver_t* sim)
{
if (sim->interactive) {
xce_repl_post_session_check(sim);
}
}
#endif

35
src/scheduler/include/sim.h
View file

@ -65,17 +65,34 @@
* write the output header/snapshot, so a re-derived value would drift from
* "the same SnapshotEntry that was loaded" (AC 19's own wording -- same ts,
* not merely a same-shaped one taken moments later).
*
* `repl_state` below is a SECOND field beyond design.md's literal sketch
* (scheduler-core spec, task 12.1, Req 5 AC 22) -- the interactive REPL's
* own execution-control state (current step-N/continue mode, remaining step
* budget; task 12.2/12.3 grow the same struct with breakpoints/param
* overrides). Declared here only as an opaque forward-declared pointer
* (xce_sched_repl_state_t, just below) -- the full struct body lives in
* repl.c, never in this header, matching plugin.h's own
* `xce_sched_core_t` forward-declare precedent for the identical "opaque
* pointer, defined in the consuming file" reason. NULL until
* xce_repl_start() lazily allocates it (repl.c) -- guaranteed NULL after a
* successful sched_sim_driver_start() the same way every other field here
* is, via that function's own `memset(sim, 0, sizeof(*sim))` (sim.c); no
* sim.c change was needed for this task.
*/
typedef struct xce_sched_repl_state_s xce_sched_repl_state_t;
typedef struct {
xce_sched_core_t core;
FILE* replay_file;
FILE* alt_events_file;
FILE* record_file;
uint64_t sim_speed_num;
uint64_t sim_speed_den;
bool verify;
bool interactive;
uint64_t snapshot_ts;
xce_sched_core_t core;
FILE* replay_file;
FILE* alt_events_file;
FILE* record_file;
uint64_t sim_speed_num;
uint64_t sim_speed_den;
bool verify;
bool interactive;
uint64_t snapshot_ts;
xce_sched_repl_state_t* repl_state;
} xce_sched_sim_driver_t;
/*

31
src/scheduler/meson.build
View file

@ -18,6 +18,7 @@ scheduler_srcs = [
'src/sim_loop.c',
'src/sim_verify.c',
'src/sim_record.c',
'src/repl.c',
'src/schedobj.c',
'src/plugin.c',
'src/resource.c',
@ -33,12 +34,23 @@ incdir = include_directories('src',
'../include',
'../lib')
# Task 12.1 (scheduler-core spec, Req 5 AC 22): the interactive REPL's
# line-editing input loop (src/repl.c) needs readline()/add_history().
# Uses libedit (BSD), not GNU readline (GPL) -- xce_scheduler is a shipped
# production daemon (unlike xce_test, a debug tool), so a GPL dependency
# would encumber the whole linked binary. libedit's editline/readline.h
# emulation header provides the same two calls under a permissive license;
# src/controller/meson.build (xce_test's own REPL) uses the identical dep
# for the same reason, kept consistent project-wide.
libedit_dep = dependency('libedit')
scheduler_deps = [
libxce_dep,
librtti_dep,
math_dep,
tinylog_dep,
thread_dep
thread_dep,
libedit_dep,
]
scheduler = executable('xce_scheduler',
@ -66,17 +78,18 @@ sched_core_isolation_lib = static_library(
# Task 11.3 (scheduler-core spec, Req 5 AC 17): isolated compile target for
# the simulation driver's own files, consumed by
# testsuite/test_sim_isolation.c to prove at build time that
# sim.c/sim_loop.c/sim_record.c reference zero controller-facing symbols
# (client/netio/xceapi/delay/idgen). All files are compiled together into ONE
# archive -- task 11.2 added sim_loop.c as a sibling file to task 11.1's
# sim.c, and task 11.5 adds sim_record.c as a third; covering only a subset
# of them would repeat core.c's own siblings' (core_events.c/core_session.c/
# core_clock.c) never-mechanically-covered gap for the sim driver. Same
# "compiling to an object is enough, no real linking needed" rationale as
# sim.c/sim_loop.c/sim_record.c/repl.c reference zero controller-facing
# symbols (client/netio/xceapi/delay/idgen). All files are compiled together
# into ONE archive -- task 11.2 added sim_loop.c as a sibling file to task
# 11.1's sim.c, task 11.5 added sim_record.c as a third, and task 12.1 adds
# repl.c as a fourth; covering only a subset of them would repeat core.c's
# own siblings' (core_events.c/core_session.c/core_clock.c)
# never-mechanically-covered gap for the sim driver. Same "compiling to an
# object is enough, no real linking needed" rationale as
# sched_core_isolation_lib above.
sched_sim_isolation_lib = static_library(
'sched_sim_isolation',
['src/sim.c', 'src/sim_loop.c', 'src/sim_record.c'],
['src/sim.c', 'src/sim_loop.c', 'src/sim_record.c', 'src/repl.c'],
include_directories: incdir,
dependencies: scheduler_deps,
install: false)

370
src/scheduler/src/repl.c Normal file
View file

@ -0,0 +1,370 @@
#include <ctype.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <editline/readline.h> /* libedit (BSD) -- readline()/add_history() */
#include "repl.h"
#include "utils.h"
/*
* repl.c - interactive simulation REPL, execution-control slice (scheduler-
* core spec, task 12.1, Req 5 AC 22). Implements a single input-loop REPL
* (NOT a separate thread, per this file family's own established
* single-threaded-driver discipline and design.md line 482/510) that pauses
* before the first event is processed and blocks the simulation loop while
* active. This task's own scope: `step [N]`/`continue`/`quit`/`help`, the
* pre-replay pause, and the blocking interaction model. Breakpoints, state
* inspection (`info job`/`info queue`/etc.), snapshot capture, and `set`/
* `info config` are tasks 12.2/12.3's own jobs -- see repl_should_pause()
* below for the single seam left for 12.2 to extend without restructuring
* sim_loop.c's call sites (repl.h's own header comment).
*
* Sanctioned deviation from requirements.md's literal text (Req 5 AC 22,
* "Implementation note": "The REPL is a single `fgets` loop"): this task's
* OWN text explicitly directs using readline() instead, for line editing
* and history. The "single loop in the driver thread, not a separate
* thread" invariant -- the part of the Implementation note that actually
* matters for correctness (design.md line 510: "REPL blocks the driver loop
* intentionally") -- is fully preserved regardless of which line-editing
* library backs readline()/add_history(); only the input loop's ergonomics
* change. Matches this spec's own established pattern of documenting
* deliberate, task-sanctioned deviations from design.md's literal prose
* (see sim.c/sim_loop.c's own file header comments for the same style
* across tasks 11.1-11.6).
*
* Licensing (task 12.1 review finding): GNU readline is GPL-licensed.
* xce_scheduler is a shipped production daemon -- linking it in directly
* (unlike xce_test, a separate debug/tooling binary) would GPL-encumber
* the whole linked binary. Uses libedit (BSD/NetBSD license) instead, via
* its editline/readline.h emulation header, which provides the identical
* readline()/add_history() surface this file calls -- zero behavioral
* difference, no GPL exposure. src/controller/testsuite/test.c's own REPL
* was switched to the same libedit dependency for project-wide consistency
* (see src/controller/meson.build's `libedit_dep`), even though xce_test's
* standalone-binary status meant it was never GPL-exposed the way
* xce_scheduler would have been.
*
* Boundary (Req 5 AC 17, "Simulation isolation", same as sim.h/sim.c/
* sim_loop.c/sim_record.c): this file touches only xce_sched_sim_driver_t/
* xce_sched_core_t (via repl.h -> sim.h -> core.h) plus stdio/libedit --
* no xcecli_ctx_t, no xce_cluster_config_t, no capnp socket, no controller
* RPC. test_sim_isolation.c (task 11.3) is extended by this task to cover
* repl.c/repl.h too, matching the 3-file (now 5-file) precedent it already
* established for sim.c/sim_loop.c/sim_record.c.
*/
#define XCE_REPL_PROMPT "(sim) "
typedef enum {
XCE_REPL_MODE_STEP = 0, /* pause once `step_budget` sessions complete */
XCE_REPL_MODE_CONTINUE /* task 12.1 scope: run unattended until EOF --
* no breakpoint mechanism exists yet */
} xce_repl_run_mode_t;
/*
* xce_sched_repl_state_s - the full definition of sim.h's opaque forward
* declaration. Deliberately private to this file (not exposed even in
* repl.h) -- sim_loop.c and every other production consumer touch it only
* through the pointer, never its fields, matching core.h's own
* xce_sched_core_t precedent for "opaque outside the owning module."
* White-box test files (this test suite's established convention -- see
* test_sim_isolation.c's own header comment on the genre) get full field
* access anyway via `#include "../src/repl.c"`.
*/
struct xce_sched_repl_state_s {
xce_repl_run_mode_t mode;
long step_budget;
};
/*
* repl_state_ensure - lazily allocates sim->repl_state on first use
* (xce_repl_start() is always the first caller in the real driver flow, but
* this stays defensive rather than assuming it). Returns the (possibly
* newly-allocated) state, or NULL on allocation failure -- callers must
* treat NULL as "REPL unavailable, do not block" rather than crash: the REPL
* is a debugging aid, never load-bearing for the simulation's own
* correctness (design.md's "Deterministic replay is preserved" invariant --
* the REPL only ever controls WHEN execution pauses, never WHAT is
* processed, so degrading to "never pauses" on OOM is safe, just less
* useful).
*/
static xce_sched_repl_state_t* repl_state_ensure(xce_sched_sim_driver_t* sim)
{
if (sim->repl_state != NULL) {
return sim->repl_state;
}
sim->repl_state
= (xce_sched_repl_state_t*)calloc(1, sizeof(*(sim->repl_state)));
return sim->repl_state;
}
/*
* repl_count_jobs - counts `core->jobs` via the SAME iter_make()/iter_next()
* walk core_session.c's core_gc_select_nodes()/scheduler.c's own job-listing
* code already establish as this codebase's idiom for enumerating a
* kvmgr-backed `var` container -- not a new tracking mechanism (no new
* state field, no persistent counter; a one-off read-only walk computed on
* demand at banner-print time). Used for the load banner's "N" below.
*
* Deviation note: requirements.md's own AC 22 pseudocode banner text reads
* "loaded: N events, snapshot @ ts=...". No field anywhere in
* xce_sched_sim_driver_t/xce_sched_core_t tracks a total replay-event count
* without a full file pre-scan -- and sched_sim_driver_start()'s own doc
* comment (sim.h) is explicit that `sim->replay_file`'s read position must
* land EXACTLY after the chosen SnapshotEntry, ready for sim_loop.c's
* sequential resume; scanning ahead to count events would disturb that
* position (or require a seek-back the file's own stream-based framing does
* not cheaply support). This task's own text is explicit on the same point
* ("pull from whatever sim/core state already has this, don't invent new
* tracking"). Reports the count of job records already restored into the
* loaded snapshot instead -- real, already-loaded state, zero new tracking,
* zero file re-scan -- and is labeled honestly below ("N jobs"), not
* mislabeled as an event count.
*/
static int repl_count_jobs(xce_sched_core_t* core)
{
iterator_t it;
xce_sched_job_t* job = NULL;
int count = 0;
int rc;
rc = iter_make(&it, core->jobs);
if (rc < 0) {
return 0;
}
for (;;) {
rc = iter_next(&it, (void**)&job);
if ((rc < 0) || (rc == RTTI_ITER_NO_DATA)) {
break;
}
count++;
}
return count;
}
static void repl_print_banner(const xce_sched_sim_driver_t* sim)
{
int njobs = repl_count_jobs((xce_sched_core_t*)&(sim->core));
printf("[sim] loaded: %d jobs, snapshot @ ts=%llu\n", njobs,
(unsigned long long)sim->snapshot_ts);
printf("[sim] ready. type 'help' for commands.\n");
}
/*
* repl_print_help - Req 5 AC 22's "help" command: "Print available commands
* with one-line descriptions." Deliberately covers ONLY the commands this
* task implements (step/continue/quit/help) -- AC 22's full table also
* lists breakpoints, state inspection, snapshot, and `set`/`info config`
* commands that do not exist yet; listing them here would document
* commands repl_dispatch() below would then reject as unrecognized. Tasks
* 12.2/12.3 extend this listing as they add those commands, matching this
* task's own text ("Don't over-build entries for commands that don't exist
* yet").
*/
static void repl_print_help(void)
{
printf("[sim] available commands:\n");
printf(" step [N] Advance N sessions (default 1), pause after.\n");
printf(" continue Run until next breakpoint hit or EOF.\n");
printf(" quit Exit the scheduler immediately.\n");
printf(" help Print this help listing.\n");
}
/*
* repl_cmd_quit - Req 5 AC 22's "quit": "Exit the scheduler immediately. No
* cleanup guarantees beyond `fclose` on open files." That fclose is the ONE
* guarantee the spec makes, not merely a floor -- honored explicitly here
* rather than left to implicit process-exit fd release. Mirrors
* sched_sim_driver_run()'s own clean-completion flush+close for
* sim->record_file (sim_loop.c) so a `quit` mid-session leaves any partial
* --sim-output write as durable as a normal completion would. Never
* returns.
*/
static void repl_cmd_quit(xce_sched_sim_driver_t* sim)
{
if (sim->record_file != NULL) {
fflush(sim->record_file);
fclose(sim->record_file);
sim->record_file = NULL;
}
if (sim->replay_file != NULL) {
fclose(sim->replay_file);
sim->replay_file = NULL;
}
if (sim->alt_events_file != NULL) {
fclose(sim->alt_events_file);
sim->alt_events_file = NULL;
}
exit(0);
}
/*
* repl_cmd_step - Req 5 AC 22's "step [N]": "Advance N sessions (default
* 1), pause after." `line` is the FULL command line (including the "step"
* token itself) -- skips it, then parses the remainder as an optional
* positive integer via strtol() with explicit trailing-garbage/non-numeric
* rejection (NOT a bare sscanf("%ld") on the whole remainder, which would
* silently accept "step abc" as N=<unchanged> by failing to convert without
* signalling an error the caller could see -- this codebase's own "fail
* loud" preference, project CLAUDE.md). Sets `sim->repl_state`'s mode/budget
* and returns true (control returns to the driver loop) only on a
* successfully parsed, positive N; prints an error and returns false
* (re-prompt) otherwise.
*/
static bool repl_cmd_step(xce_sched_sim_driver_t* sim, const char* line)
{
const char* rest = line;
long n;
char* endptr;
while ((*rest != '\0') && !isspace((unsigned char)*rest)) {
rest++;
}
while (isspace((unsigned char)*rest)) {
rest++;
}
if (*rest == '\0') {
n = 1; /* "step" with no argument -- Req 5 AC 22's documented
* default */
} else {
n = strtol(rest, &endptr, 10);
while (isspace((unsigned char)*endptr)) {
endptr++;
}
if ((endptr == rest) || (*endptr != '\0') || (n <= 0)) {
printf("[sim] step: N must be a positive integer -- usage: "
"step [N]\n");
return false;
}
}
sim->repl_state->mode = XCE_REPL_MODE_STEP;
sim->repl_state->step_budget = n;
return true;
}
/*
* repl_dispatch - parses one readline()-returned command line (already
* known non-blank by the caller) and executes it. Returns true if control
* should return to the driver's event loop (`step`/`continue`), false if
* the REPL should re-prompt (`help`, an unrecognized command, or a `step`
* parse error). `quit` never returns from repl_cmd_quit() -- its own return
* value below is unreachable, kept only so every branch has a well-typed
* value.
*/
static bool repl_dispatch(xce_sched_sim_driver_t* sim, const char* line)
{
char cmd[32];
if (sscanf(line, " %31s", cmd) != 1) {
return false; /* whitespace-only -- silently re-prompt */
}
if (strcmp(cmd, "step") == 0) {
return repl_cmd_step(sim, line);
}
if (strcmp(cmd, "continue") == 0) {
sim->repl_state->mode = XCE_REPL_MODE_CONTINUE;
return true;
}
if (strcmp(cmd, "quit") == 0) {
repl_cmd_quit(sim);
return true; /* unreachable */
}
if (strcmp(cmd, "help") == 0) {
repl_print_help();
return false;
}
printf("[sim] unknown command: '%s' (type 'help' for a list)\n", cmd);
return false;
}
/*
* repl_command_loop - the blocking prompt loop itself: readline() the
* `(sim) ` prompt, add_history() on non-blank input (same convention
* src/controller/testsuite/test.c's own REPL establishes at its readline()
* call site), dispatch, repeat until a command hands control back. NULL
* from readline() (Ctrl-D / stdin EOF) is treated exactly like an explicit
* `quit` -- the same convention test.c's own loop follows
* (`execute_line("quit")` on a NULL readline() return) -- never returns in
* that case either.
*/
static void repl_command_loop(xce_sched_sim_driver_t* sim)
{
for (;;) {
char* line = readline(XCE_REPL_PROMPT);
if (line == NULL) {
repl_cmd_quit(sim); /* never returns */
}
if (line[0] != '\0') {
add_history(line);
}
if (repl_dispatch(sim, line)) {
free(line);
return;
}
free(line);
}
}
void xce_repl_start(xce_sched_sim_driver_t* sim)
{
if (repl_state_ensure(sim) == NULL) {
ERROR("%s failed to allocate REPL state -- continuing unattended "
"(--interactive pre-replay pause skipped)",
__func__);
return;
}
repl_print_banner(sim);
repl_command_loop(sim);
}
/*
* repl_should_pause - Req 5 AC 22's per-session pause decision, task 12.1's
* own scope: pause only when a `step N` budget reaches zero. `continue`
* mode (AC 22: "Run until next breakpoint hit or EOF") always returns false
* here today -- no breakpoint mechanism exists yet (task 12.2's job). This
* is the single seam task 12.2 extends (adding a breakpoint-list check
* alongside the step-budget check below) without touching
* xce_repl_post_session_check() or sim_loop.c's call site at all.
*/
static bool repl_should_pause(xce_sched_sim_driver_t* sim)
{
xce_sched_repl_state_t* rs = sim->repl_state;
if (rs == NULL) {
return false; /* defensive: xce_repl_start() always allocates this
* first in the real driver flow */
}
if (rs->mode == XCE_REPL_MODE_STEP) {
rs->step_budget--;
return (rs->step_budget <= 0);
}
return false;
}
void xce_repl_post_session_check(xce_sched_sim_driver_t* sim)
{
if (repl_should_pause(sim)) {
repl_command_loop(sim);
}
}

3
src/scheduler/src/sim_loop.c
View file

@ -8,6 +8,7 @@
#include "controller.capnp.h"
#include "plugin.h"
#include "preason.h"
#include "repl.h"
#include "sim.h"
#include "utils.h"
#include "xstring.h"
@ -522,6 +523,7 @@ int sched_sim_driver_run(xce_sched_sim_driver_t* sim,
return rc;
}
xce_repl_pre_replay_pause(sim);
sim_register_default_picker(sim);
/* Req 5 AC 19 (task 11.5): the first two --sim-output messages, written
@ -735,6 +737,7 @@ int sched_sim_driver_run(xce_sched_sim_driver_t* sim,
free_ReplaySession_ptr(&decoded_session);
xce_core_end_session(&(sim->core));
xce_repl_post_session_pause(sim);
/* Req 5 AC 19: "On core_end_session(): finalize the
* ReplaySession ... write the complete message" -- mirrors

2
src/scheduler/src/snapshot_load.c
View file

@ -324,7 +324,7 @@ int xce_sched_core_load_snapshot(xce_sched_core_t* core,
core->session_duration_ns = blob[1];
} else {
WARN("%s internal_state version mismatch (got %u, expected %u) "
"or undersized (%zu bytes) -- skipping, session "
"or undersized (%u bytes) -- skipping, session "
"diagnostics left at defaults",
__func__, in->internal_version,
SCHED_SNAPSHOT_INTERNAL_VERSION, in->internal_state_len);

39
src/scheduler/testsuite/meson.build
View file

@ -2,7 +2,17 @@ scheduler_test_src = [
'test.c',
]
scheduler_test_deps = [libxce_deps, librtti_dep, unity_dep, libxce_dep]
# libedit_dep (defined in the parent meson.build, task 12.1, Req 5 AC 22):
# every white-box test TU that #includes ../src/sim_loop.c now transitively
# pulls in repl.h's inline wrappers, which reference repl.c's real
# readline()/add_history() calls the moment ANY such TU also #includes
# ../src/repl.c (already required at link time regardless -- sim_loop.c's
# own repl.h wrappers reference xce_repl_start()/xce_repl_post_session_check()
# unconditionally). Added to the shared deps list rather than per-test so
# every current and future sim-family white-box test picks it up
# automatically.
scheduler_test_deps = [libxce_deps, librtti_dep, unity_dep, libxce_dep,
libedit_dep]
incdir = include_directories('../include', '../../include', '.', '../src', '../../lib')
@ -535,6 +545,12 @@ sched_sim_isolation_test = executable(
'-DXCE_SIM_RECORD_C_PATH="'
+ (meson.current_source_dir() / '..' / 'src' / 'sim_record.c')
+ '"',
'-DXCE_SIM_REPL_C_PATH="'
+ (meson.current_source_dir() / '..' / 'src' / 'repl.c')
+ '"',
'-DXCE_SIM_REPL_H_PATH="'
+ (meson.current_source_dir() / '..' / 'include' / 'repl.h')
+ '"',
'-DXCE_SIM_LIB_PATH="'
+ sched_sim_isolation_lib.full_path()
+ '"'],
@ -636,6 +652,24 @@ sched_sim_equivalence_test = executable(
dependencies: [scheduler_test_deps],
install: false)
# Contract test for the interactive simulation REPL's execution-control slice
# (scheduler-core spec, task 12.1, Req 5 AC 22): starting simulation with
# --interactive pauses before any event is processed, and a `step N` command
# advances exactly N sessions before returning control to the prompt. Same
# white-box #include pattern as sched_sim_alt_events_test/sched_sim_verify_test
# (core.c, core_clock.c, core_events.c, core_session.c, decision.c, plugin.c,
# plugins/builtin_fcfs.c, recording.c, recording_session.c, sim.c, sim_loop.c,
# sim_record.c, sim_verify.c, snapshot.c/snapshot_wire.c/snapshot_load.c) PLUS
# the new ../src/repl.c under test. Needs libedit_dep (parent meson.build)
# at link time -- repl.c's real readline()/add_history() calls are pulled
# into this TU by the white-box #include.
sched_repl_execution_control_test = executable(
'sched_repl_execution_control_test',
['test_repl_execution_control.c'],
include_directories:[incdir],
dependencies: [scheduler_test_deps, libedit_dep],
install: false)
# Register as meson tests so `meson test --suite scheduler` runs them all.
# detect_leaks=0 matches the suite convention (fixtures are not torn down).
test('scheduler test', scheduler_test, suite: 'scheduler',
@ -726,3 +760,6 @@ test('scheduler sim record output test',
test('scheduler sim equivalence test',
sched_sim_equivalence_test, suite: 'scheduler',
env: ['ASAN_OPTIONS=detect_leaks=0'])
test('scheduler repl execution control test',
sched_repl_execution_control_test, suite: 'scheduler',
env: ['ASAN_OPTIONS=detect_leaks=0'])

643
src/scheduler/testsuite/test_repl_execution_control.c Normal file
View file

@ -0,0 +1,643 @@
/*
* test_repl_execution_control.c - contract test for the interactive
* simulation REPL's execution-control slice (scheduler-core spec, task
* 12.1, Req 5 AC 22).
*
* Observable under test (task 12.1's own text):
* (a) starting simulation with the REPL enabled pauses before any event
* is processed;
* (b) issuing a step command advances exactly the requested number of
* sessions and returns control to the prompt.
*
* Three tests, at three different granularities (same "unit-level precision
* PLUS integration-level end-to-end proof" split test_sim_event_loop.c's own
* header comment establishes):
*
* Test 1 (unit-level, white-box): drives repl_should_pause() -- the exact
* internal predicate sim_loop.c's post-session hook relies on -- directly,
* asserting it returns false for the first N-1 completed sessions and true
* on exactly the Nth. This is the precise "not N-1, not N+1" proof
* Observable (b) requires; it cannot be obtained by driving the full
* blocking driver (a real REPL prompt loop cannot be sampled mid-flight
* from a single-threaded test without either forking or instrumenting
* production code for tests, neither of which would be as precise as
* calling the exact decision function directly).
*
* Test 2 (integration-level, single-process, stdin freopen()'d from a
* script file): drives a REAL sched_sim_driver_run() with sim->interactive
* set against a real one-session `.replay` fixture whose session produces
* a real PEND decision, scripted with a single "continue\n" line. Proves
* Observable (a) by capturing stdout (dup()/dup2() around the run, same
* technique test_sim_verify.c's own capture_stdout_around() establishes)
* and asserting the pre-replay-pause banner text appears STRICTLY BEFORE
* the decision's own output line -- ordering, not just presence, is the
* proof that nothing was processed before the pause.
*
* Test 3 (integration-level, forked child process): drives a REAL
* sched_sim_driver_run() against a real THREE-session fixture (distinct
* jobid pushed just before each session boundary), scripted with "step
* 1\nquit\n". A child process is required because the CORRECT behavior is
* for `quit` to call exit(0) directly -- this is the genuinely falsifiable
* proof the task's own RED-phase guidance asks for: a broken
* implementation where `step` is a no-op (always runs to EOF, the exact
* probe this task's own text suggests) would run all three sessions to
* completion and return normally instead of ever reading "quit", which
* the parent detects both by exit status (0 only via quit's real exit(0),
* not by falling off the end of the child helper) AND by captured
* content (only the FIRST session's jobid may appear).
*
* Fixture strategy: the SAME real QUEUE_UPDATE+JOBS_PUSH-driving-the-real-
* builtin_fcfs-picker technique test_sim_alt_events.c/test_sim_verify.c's
* own integration-level fixtures establish (build_fixture_scheduler()
* records schedPolicy="builtin_fcfs" so sim_register_default_picker()
* resolves the real plugin; sched_job_is_ready()/sched_queue_is_ready() are
* unconditional `return 1` stubs, task 2.4's own documented, still-live
* scope note, so any queue/job pair immediately becomes a next_job()
* candidate).
*
* White-box #include of the same TU set test_sim_alt_events.c uses (see
* that file's own header comment) -- core.c/core_clock.c/core_events.c/
* core_session.c/decision.c/plugin.c/plugins/builtin_fcfs.c/recording.c/
* recording_session.c/sim.c/sim_loop.c/sim_record.c/sim_verify.c/
* snapshot.c/snapshot_load.c/snapshot_wire.c PLUS the new ../src/repl.c
* under test (task 12.1's own file, pulling readline()/add_history() calls
* into this TU -- see testsuite/meson.build's own comment on this
* executable's readline_dep/history_dep/ncurses_dep link requirement).
*/
#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_sim_alt_events.c/test_sim_verify.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/sim.c"
#include "../src/sim_loop.c"
#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; }
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;
}
/* Real reimplementation of schedobj.c's sched_resolve_job_picker -- same
* copy test_sim_alt_events.c/test_sim_verify.c/test_sim_event_loop.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 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_sim_alt_events.c/test_sim_verify.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_replexec%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_sim_verify.c's own capture_stdout_around() establishes. */
static char* capture_stdout_around(void (*fn)(void))
{
char tmp[] = "/tmp/xce_replexec_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;
}
/* ---------------------------------------------------------------------- */
/* Test 1: repl_should_pause() pauses on exactly the Nth completed */
/* session -- the precise unit-level proof of Observable (b). */
/* ---------------------------------------------------------------------- */
static void test_should_pause_fires_on_exactly_the_nth_session(void)
{
xce_sched_sim_driver_t sim;
memset(&sim, 0, sizeof(sim));
sim.interactive = true;
sim.repl_state = repl_state_ensure(&sim);
TEST_ASSERT_NOT_NULL(sim.repl_state);
sim.repl_state->mode = XCE_REPL_MODE_STEP;
sim.repl_state->step_budget = 3;
TEST_ASSERT_FALSE_MESSAGE(repl_should_pause(&sim),
"must not pause after session 1 of 3");
TEST_ASSERT_FALSE_MESSAGE(repl_should_pause(&sim),
"must not pause after session 2 of 3");
TEST_ASSERT_TRUE_MESSAGE(repl_should_pause(&sim),
"must pause after exactly session 3 of 3");
free(sim.repl_state);
printf("test_should_pause_fires_on_exactly_the_nth_session: PASS\n");
}
static void test_should_pause_never_fires_in_continue_mode(void)
{
xce_sched_sim_driver_t sim;
int i;
memset(&sim, 0, sizeof(sim));
sim.interactive = true;
sim.repl_state = repl_state_ensure(&sim);
TEST_ASSERT_NOT_NULL(sim.repl_state);
sim.repl_state->mode = XCE_REPL_MODE_CONTINUE;
/* Req 5 AC 22, task 12.1's own scope: "continue" runs to EOF -- no
* breakpoint mechanism exists yet, so this must never pause no matter
* how many sessions complete. */
for (i = 0; i < 5; i++) {
TEST_ASSERT_FALSE(repl_should_pause(&sim));
}
free(sim.repl_state);
printf("test_should_pause_never_fires_in_continue_mode: PASS\n");
}
/* ---------------------------------------------------------------------- */
/* Test 2: the pre-replay pause happens BEFORE any decision is produced */
/* -- Observable (a), proved by output ORDER, not merely presence. */
/* ---------------------------------------------------------------------- */
static xce_sched_sim_driver_t g_t2_sim;
static sched_sim_args_t g_t2_args;
static int g_t2_rc;
static void run_driver_for_t2_capture(void)
{
g_t2_rc = sched_sim_driver_run(&g_t2_sim, &g_t2_args);
}
static void test_pre_replay_pause_blocks_before_any_event_is_processed(void)
{
char replay_path[PATH_MAX];
char script_dir[PATH_MAX];
char script_path[PATH_MAX];
FILE* f;
char* captured;
char* ready_pos;
char* pend_pos;
FILE* saved_stdin_check;
f = write_header_and_snapshot(replay_path, sizeof(replay_path),
"_prepause");
TEST_ASSERT_NOT_NULL(f);
append_queue_update_event(f, 1000ULL, "normal");
append_jobs_push_event(f, 1500ULL, 4242ULL, "normal");
append_replay_session(f, 2000ULL); /* the only session boundary */
append_end_of_stream_marker(f);
fclose(f);
make_tmp_dir(script_dir, sizeof(script_dir), "_prepausescript");
snprintf(script_path, sizeof(script_path), "%s/script.txt", script_dir);
/* A single "continue" -- 12.1's own scope means continue never
* re-pauses, so the run reaches EOF cleanly without reading stdin
* again. */
write_text_file(script_path, "continue\n");
saved_stdin_check = freopen(script_path, "r", stdin);
TEST_ASSERT_NOT_NULL_MESSAGE(saved_stdin_check,
"freopen of scripted stdin must succeed");
memset(&g_t2_sim, 0, sizeof(g_t2_sim));
memset(&g_t2_args, 0, sizeof(g_t2_args));
g_t2_args.replay_path = replay_path;
g_t2_args.sim_start_ts = SCHED_SIM_START_TS_LATEST;
g_t2_args.sim_speed = 0;
g_t2_args.interactive = true;
captured = capture_stdout_around(run_driver_for_t2_capture);
TEST_ASSERT_EQUAL_INT(0, g_t2_rc);
ready_pos = strstr(captured, "[sim] ready. type 'help' for commands.");
pend_pos = strstr(captured, "PEND jobid=4242");
TEST_ASSERT_NOT_NULL_MESSAGE(ready_pos,
"pre-replay pause banner must be printed");
TEST_ASSERT_NOT_NULL_MESSAGE(pend_pos,
"the fixture's one session must have "
"produced a live PEND decision");
TEST_ASSERT_TRUE_MESSAGE(ready_pos < pend_pos,
"the pre-replay pause banner must appear "
"BEFORE any decision output -- proves no "
"event was processed before the pause");
free(captured);
printf("test_pre_replay_pause_blocks_before_any_event_is_processed: "
"PASS\n");
}
/* ---------------------------------------------------------------------- */
/* Test 3: "step 1" against a three-session fixture processes EXACTLY one */
/* session before re-pausing -- proved end to end via a forked child that */
/* then issues "quit" (real exit(0)), so a broken "step ignores N, always */
/* runs to EOF" implementation is genuinely distinguishable: it would */
/* never read "quit" at all and would exit via a different path/status. */
/* ---------------------------------------------------------------------- */
static void child_step_then_quit(const char* replay_path,
const char* script_path,
const char* capture_path)
{
xce_sched_sim_driver_t sim;
sched_sim_args_t args;
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);
/* Unreachable in a correct implementation: "quit" (the script's second
* line) must have called exit(0) from inside the post-session pause
* that follows session 1. Falling through here means either the
* pre-replay pause or the post-session pause never blocked on stdin at
* all. */
fflush(stdout);
_exit(111);
}
static void test_step_1_processes_exactly_one_session_then_quit_exits(void)
{
char replay_path[PATH_MAX];
char aux_dir[PATH_MAX];
char script_path[PATH_MAX];
char capture_path[PATH_MAX];
FILE* f;
pid_t pid;
int status;
char* captured;
f = write_header_and_snapshot(replay_path, sizeof(replay_path),
"_step1quit");
TEST_ASSERT_NOT_NULL(f);
append_queue_update_event(f, 1000ULL, "normal");
append_jobs_push_event(f, 1500ULL, 111ULL, "normal");
append_replay_session(f, 2000ULL); /* session boundary #1 */
append_jobs_push_event(f, 2500ULL, 222ULL, "normal");
append_replay_session(f, 3000ULL); /* session boundary #2 -- must NEVER
* be reached */
append_jobs_push_event(f, 3500ULL, 333ULL, "normal");
append_replay_session(f, 4000ULL); /* session boundary #3 -- must NEVER
* be reached */
append_end_of_stream_marker(f);
fclose(f);
make_tmp_dir(aux_dir, sizeof(aux_dir), "_step1quitaux");
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\nquit\n");
pid = fork();
TEST_ASSERT_TRUE_MESSAGE(pid >= 0, "fork() must succeed");
if (pid == 0) {
child_step_then_quit(replay_path, script_path, capture_path);
_exit(112); /* unreachable -- child_step_then_quit never returns */
}
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), not crash/signal");
TEST_ASSERT_EQUAL_INT_MESSAGE(0, WEXITSTATUS(status),
"quit's exit(0) is the only correct exit "
"path -- a nonzero/111 status means "
"'step 1' never paused (ran to EOF "
"instead), the RED-phase probe this "
"task's own text describes");
captured = read_whole_file(capture_path);
TEST_ASSERT_NOT_NULL_MESSAGE(strstr(captured, "PEND jobid=111"),
"session 1's decision must have run");
TEST_ASSERT_NULL_MESSAGE(strstr(captured, "PEND jobid=222"),
"session 2 must NEVER have run -- step 1 "
"must pause strictly after session 1");
TEST_ASSERT_NULL_MESSAGE(strstr(captured, "PEND jobid=333"),
"session 3 must NEVER have run either");
free(captured);
printf("test_step_1_processes_exactly_one_session_then_quit_exits: "
"PASS\n");
}
int main(void)
{
UNITY_BEGIN();
RUN_TEST(test_should_pause_fires_on_exactly_the_nth_session);
RUN_TEST(test_should_pause_never_fires_in_continue_mode);
RUN_TEST(test_pre_replay_pause_blocks_before_any_event_is_processed);
RUN_TEST(test_step_1_processes_exactly_one_session_then_quit_exits);
return UNITY_END();
}

70
src/scheduler/testsuite/test_sim_isolation.c
View file

@ -4,21 +4,27 @@
* or structural check confirms no controller-facing symbol is reachable
* from the simulation driver's compiled object" -- plus the AC's own
* "confirmed by the struct definition itself, not runtime checks alone"
* clause. Scope: sim.h + sim.c + sim_loop.c + sim_record.c together (task
* 11.1 + task 11.2's sibling file + task 11.5's sibling file, the
* --sim-output writer) -- NOT a re-audit of core.c (task 4.1's own
* territory, test_core_isolation.c) and NOT plugin.c/builtin_fcfs.c (shared
* clause. Scope: sim.h + sim.c + sim_loop.c + sim_record.c + repl.c/repl.h
* together (task 11.1 + task 11.2's sibling file + task 11.5's sibling
* file, the --sim-output writer + task 12.1's sibling files, the
* interactive REPL) -- NOT a re-audit of core.c (task 4.1's own territory,
* test_core_isolation.c) and NOT plugin.c/builtin_fcfs.c (shared
* normal-mode infra, out of this task's boundary). sim_verify.c (task 11.4)
* is likewise out of scope here -- it is never compiled into
* sched_sim_isolation_lib below and carries no isolation-sensitive logic of
* its own (pure struct comparison, no I/O); extending this guard to it was
* not part of task 11.4's own text and is left as-is.
* not part of task 11.4's own text and is left as-is. repl.c/repl.h are
* added here per task 12.1's own text (extending this exact 3-file
* precedent to a 5-file one) -- the REPL reads/writes stdin/stdout and
* touches xce_sched_sim_driver_t directly, the same category of
* driver-level code this guard already covers.
*
* Three layers, extending test_core_isolation.c's two-layer pattern (same
* genre: source-text scans of the real, current on-disk files, not a frozen
* snapshot):
*
* 1. Source-text scan of sim.h/sim.c/sim_loop.c: no #include of
* 1. Source-text scan of sim.h/sim.c/sim_loop.c/sim_record.c/repl.c/
* repl.h: no #include of
* client.h/netio.h/xceapi.h/delay.h/idgen.h/xce/cluster.h; no call-site
* substring matching a symbol exported only by those libraries (the
* exact FORBIDDEN_SYMBOLS list test_core_isolation.c already
@ -83,9 +89,17 @@
#error \
"XCE_SIM_RECORD_C_PATH must be defined by meson.build to sim_record.c's absolute path"
#endif
#ifndef XCE_SIM_REPL_C_PATH
#error \
"XCE_SIM_REPL_C_PATH must be defined by meson.build to repl.c's absolute path"
#endif
#ifndef XCE_SIM_REPL_H_PATH
#error \
"XCE_SIM_REPL_H_PATH must be defined by meson.build to repl.h's absolute path"
#endif
#ifndef XCE_SIM_LIB_PATH
#error \
"XCE_SIM_LIB_PATH must be defined by meson.build to the absolute path of sim.c+sim_loop.c+sim_record.c's isolated static_library() archive"
"XCE_SIM_LIB_PATH must be defined by meson.build to the absolute path of sim.c+sim_loop.c+sim_record.c+repl.c's isolated static_library() archive"
#endif
/* Forbidden headers (design.md "Allowed Dependencies", same list
@ -359,16 +373,22 @@ static void test_sim_source_paths_are_readable(void)
char* c = read_whole_file(XCE_SIM_C_PATH);
char* loop = read_whole_file(XCE_SIM_LOOP_C_PATH);
char* record = read_whole_file(XCE_SIM_RECORD_C_PATH);
char* repl_c = read_whole_file(XCE_SIM_REPL_C_PATH);
char* repl_h = read_whole_file(XCE_SIM_REPL_H_PATH);
TEST_ASSERT_NOT_NULL_MESSAGE(h, XCE_SIM_H_PATH);
TEST_ASSERT_NOT_NULL_MESSAGE(c, XCE_SIM_C_PATH);
TEST_ASSERT_NOT_NULL_MESSAGE(loop, XCE_SIM_LOOP_C_PATH);
TEST_ASSERT_NOT_NULL_MESSAGE(record, XCE_SIM_RECORD_C_PATH);
TEST_ASSERT_NOT_NULL_MESSAGE(repl_c, XCE_SIM_REPL_C_PATH);
TEST_ASSERT_NOT_NULL_MESSAGE(repl_h, XCE_SIM_REPL_H_PATH);
free(h);
free(c);
free(loop);
free(record);
free(repl_c);
free(repl_h);
}
static void test_sim_never_includes_forbidden_headers(void)
@ -377,38 +397,54 @@ static void test_sim_never_includes_forbidden_headers(void)
char* c_raw = read_whole_file(XCE_SIM_C_PATH);
char* loop_raw = read_whole_file(XCE_SIM_LOOP_C_PATH);
char* record_raw = read_whole_file(XCE_SIM_RECORD_C_PATH);
char* repl_c_raw = read_whole_file(XCE_SIM_REPL_C_PATH);
char* repl_h_raw = read_whole_file(XCE_SIM_REPL_H_PATH);
char* h;
char* c;
char* loop;
char* record;
char* repl_c;
char* repl_h;
TEST_ASSERT_NOT_NULL(h_raw);
TEST_ASSERT_NOT_NULL(c_raw);
TEST_ASSERT_NOT_NULL(loop_raw);
TEST_ASSERT_NOT_NULL(record_raw);
TEST_ASSERT_NOT_NULL(repl_c_raw);
TEST_ASSERT_NOT_NULL(repl_h_raw);
h = strip_c_comments(h_raw);
c = strip_c_comments(c_raw);
loop = strip_c_comments(loop_raw);
record = strip_c_comments(record_raw);
repl_c = strip_c_comments(repl_c_raw);
repl_h = strip_c_comments(repl_h_raw);
TEST_ASSERT_NOT_NULL(h);
TEST_ASSERT_NOT_NULL(c);
TEST_ASSERT_NOT_NULL(loop);
TEST_ASSERT_NOT_NULL(record);
TEST_ASSERT_NOT_NULL(repl_c);
TEST_ASSERT_NOT_NULL(repl_h);
assert_no_forbidden_includes(h, "sim.h");
assert_no_forbidden_includes(c, "sim.c");
assert_no_forbidden_includes(loop, "sim_loop.c");
assert_no_forbidden_includes(record, "sim_record.c");
assert_no_forbidden_includes(repl_c, "repl.c");
assert_no_forbidden_includes(repl_h, "repl.h");
free(h_raw);
free(c_raw);
free(loop_raw);
free(record_raw);
free(repl_c_raw);
free(repl_h_raw);
free(h);
free(c);
free(loop);
free(record);
free(repl_c);
free(repl_h);
}
static void test_sim_never_calls_forbidden_symbols(void)
@ -417,38 +453,54 @@ static void test_sim_never_calls_forbidden_symbols(void)
char* c_raw = read_whole_file(XCE_SIM_C_PATH);
char* loop_raw = read_whole_file(XCE_SIM_LOOP_C_PATH);
char* record_raw = read_whole_file(XCE_SIM_RECORD_C_PATH);
char* repl_c_raw = read_whole_file(XCE_SIM_REPL_C_PATH);
char* repl_h_raw = read_whole_file(XCE_SIM_REPL_H_PATH);
char* h;
char* c;
char* loop;
char* record;
char* repl_c;
char* repl_h;
TEST_ASSERT_NOT_NULL(h_raw);
TEST_ASSERT_NOT_NULL(c_raw);
TEST_ASSERT_NOT_NULL(loop_raw);
TEST_ASSERT_NOT_NULL(record_raw);
TEST_ASSERT_NOT_NULL(repl_c_raw);
TEST_ASSERT_NOT_NULL(repl_h_raw);
h = strip_c_comments(h_raw);
c = strip_c_comments(c_raw);
loop = strip_c_comments(loop_raw);
record = strip_c_comments(record_raw);
repl_c = strip_c_comments(repl_c_raw);
repl_h = strip_c_comments(repl_h_raw);
TEST_ASSERT_NOT_NULL(h);
TEST_ASSERT_NOT_NULL(c);
TEST_ASSERT_NOT_NULL(loop);
TEST_ASSERT_NOT_NULL(record);
TEST_ASSERT_NOT_NULL(repl_c);
TEST_ASSERT_NOT_NULL(repl_h);
assert_no_forbidden_symbols(h, "sim.h");
assert_no_forbidden_symbols(c, "sim.c");
assert_no_forbidden_symbols(loop, "sim_loop.c");
assert_no_forbidden_symbols(record, "sim_record.c");
assert_no_forbidden_symbols(repl_c, "repl.c");
assert_no_forbidden_symbols(repl_h, "repl.h");
free(h_raw);
free(c_raw);
free(loop_raw);
free(record_raw);
free(repl_c_raw);
free(repl_h_raw);
free(h);
free(c);
free(loop);
free(record);
free(repl_c);
free(repl_h);
}
/*
@ -523,8 +575,8 @@ static void test_sim_object_has_no_forbidden_undefined_symbols(void)
/* posix format for an undefined symbol: "<name> U" (no
* value/size columns). Skip anything that doesn't parse as
* exactly that -- e.g. a blank line, or an archive member header
* some nm versions print (this archive has three member objects,
* sim.c.o, sim_loop.c.o, and sim_record.c.o). */
* some nm versions print (this archive has four member objects,
* sim.c.o, sim_loop.c.o, sim_record.c.o, and repl.c.o). */
if (sscanf(line, "%511s %c", symbol, &type) != 2) {
continue;
}

24
src/schema/controller.capnp
View file

@ -1109,10 +1109,23 @@ struct SchedProject $C.mapname("sched_snapshot_project_t") {
# session/iterator state) with no capnp-visible structure -- the core owns
# its byte layout; internalVersion is a format tag so a future incompatible
# internal layout is rejected rather than misinterpreted (this task's
# Observable). Like every other Data field in this schema (see
# ReplayHeader.configHash above), internalState's generated encode_/decode_
# codec is a documented no-op -- real extraction is hand-written
# low-level-accessor code, task 9+'s job, same pattern.
# Observable).
#
# internalState is List(UInt8), NOT Data (task 12.1 review finding, fixed):
# every OTHER Data field in this schema (e.g. ReplayHeader.configHash) has
# its generated encode_/decode_ codec silently no-op'd by this codebase's
# capnpc-c setup -- the generated encode_SnapshotData_ptr()'s local `struct
# SnapshotData d;` is never zero-initialized, so a no-op'd Data field left
# capn_setp() writing an UNINITIALIZED stack capn_ptr onto the wire (real,
# reproducible SIGSEGV in write_SnapshotData, deterministic per call site's
# stack layout -- configHash happened to get lucky garbage, internalState
# did not). List(UInt8) sidesteps the whole no-op class: this same capnpc-c
# backend DOES correctly auto-generate real encode/decode for List(UInt8)
# (proven precedent: FetchFileReply.content/bytesRead above -- a genuine
# capn_new_list8()/capn_set8() loop, not a comment placeholder), so no
# hand-written low-level accessor code is needed here at all. Same
# maplistcount convention as content/bytesRead: internalStateLen (@11,
# below) carries the byte count as its own real wire scalar.
struct SnapshotData $C.mapname("sched_snapshot_data_t") {
config @0: Conf4Sched;
jobs @1: SchedJobData;
@ -1123,8 +1136,9 @@ struct SnapshotData $C.mapname("sched_snapshot_data_t") {
users @6: List(SchedUser) $C.maplistcount("n_users");
projects @7: List(SchedProject) $C.maplistcount("n_projects");
prngSeed @8: UInt64 $C.mapname("prng_seed");
internalState @9: Data $C.mapname("internal_state");
internalState @9: List(UInt8) $C.mapname("internal_state") $C.maplistcount("internal_state_len");
internalVersion @10: UInt32 $C.mapname("internal_version");
internalStateLen @11: UInt32 $C.mapname("internal_state_len");
}
struct SnapshotEntry $C.mapname("replay_snapshot_entry_t") {