myxce/.kiro/specs/scheduler-sim-step-verbosity/design.md

# Design Document

## Overview
`repl_print_event_summary()` (`repl_break.c`) prints a `"[sim] t=<ns> (<ISO8601>) session=<N>"` preamble line unconditionally before every echoed event's own content line — this is its only call site, `xce_repl_on_event()`, which already gates WHICH events reach it per `scheduler-sim-repl-verbosity`'s Event Echo Gate (structural events always; routine events only in `step` mode). Because the preamble is a fixed prefix printed on every call regardless of what the previous call printed, an operator watching several consecutive events that land in the same displayed second and session sees that context restated once per event, diluting the actual event content it's meant to introduce.

This feature makes `repl_print_event_summary()` preamble-aware of its own immediately-preceding output: it prints the preamble only when the rendered (second-granularity) timestamp or the displayed session number has changed since the last time a preamble was actually printed; otherwise it prints only the event's content line. No other REPL behavior changes.

**Users**: Operators running `step` or `continue` (structural-event) transcripts through `xce_scheduler --sim <file> --interactive`.
**Impact**: `repl_print_event_summary()` gains a short-circuit at its top; `xce_sched_repl_state_s` gains two small cache fields recording what was last actually printed.

### Goals
- Print the timestamp/session preamble once per distinct (rendered timestamp, session) run of consecutive echoed events, not once per event.
- Base "distinct" on the rendered, second-granularity timestamp and displayed session number — not the underlying raw nanosecond clock value, which changes on every event and would otherwise defeat deduplication entirely.
- Leave every echoed event's own content line, its ordering, and whether it is echoed at all completely unchanged.

### Non-Goals
- Changing the Event Echo Gate's routine/structural classification (`repl_event_is_structural()`) — which events reach `repl_print_event_summary()` at all is unaffected.
- Changing the Round Rollup / collapsing behavior `continue` mode already uses for routine events and per-round decision summaries.
- Changing decision output (`sim_print_decision`/`sim_print_decision_gate`), which has no preamble of its own and is untouched.
- Reformatting the preamble's own content (timestamp precision, session-number convention) — only whether it is printed, not what it looks like when it is.

## Boundary Commitments

### This Spec Owns
- The preamble-print decision inside `repl_print_event_summary()`'s single call site.
- Two new cache fields on `xce_sched_repl_state_s` (`repl_internal.h`) recording the last preamble actually printed.

### Out of Boundary
- The Event Echo Gate's classification logic (`repl_event_is_structural()`, `repl_break.c`) — unmodified, this spec only changes what happens after an event has already been selected for echoing.
- The Round Rollup / collapsing logic (`repl_rollup.c`) and `sim_print_decision_gate()` (`sim_loop.c`) — both unmodified.
- Every REPL command's parsing, dispatch, or output other than this one preamble line.

### Allowed Dependencies
- `xce_sched_repl_state_s` (`repl_internal.h`, existing) — the two new cache fields live here, alongside this file's other REPL-session-scoped state.
- `repl_format_ts_human()` (`repl_fmt.c`, existing, from `scheduler-sim-repl-verbosity`) — reused as-is to render the human-readable timestamp string used for the dedup comparison; not modified.

### Revalidation Triggers
- If `repl_format_ts_human()`'s rendered granularity or format ever changes, re-verify the dedup key still reflects what an operator actually sees as "the same displayed context."
- If `repl_print_event_summary()` ever gains a second call site, revisit whether a single "last printed" cache still correctly models "immediately preceding echoed event" across both sites.

## Architecture

### Existing Architecture Analysis
`repl_print_event_summary()` is `static` and has exactly one caller, `xce_repl_on_event()` (`repl_break.c`), itself reached only when `sim->interactive` and `sim->repl_state != NULL` — both already guaranteed by the time this function runs, so no new NULL-handling is introduced. The function currently: (1) unconditionally builds and prints the preamble, then (2) switches on `ev->type` to print the event's own content. This design touches only step (1); step (2) and the surrounding gate in `xce_repl_on_event()` are unchanged.

`xce_sched_repl_state_s` already carries several REPL-session-scoped caches added by prior tasks (the Round Rollup's collapse-state fields, `units_mode`) — the two new fields here follow that same established pattern: session-lifetime state, zero-initialized by `repl_state_ensure()`'s existing `calloc`, with no additional lifecycle code required (an empty string and a `0` session number can never equal a real echoed event's rendered values, so the "no preceding echoed event" case, AC 1.2, is satisfied by zero-initialization alone — the same convention every field in this struct except `units_mode` already relies on).

**Architecture Integration**:
- Selected pattern: extend one existing function's own early logic; no new component, no new file.
- Domain/feature boundaries: strictly inside the REPL Output domain (`repl_break.c`/`repl_internal.h`) `scheduler-sim-repl-verbosity` already established; no other domain (Round Rollup, Resource Formatter, Help/Breakpoint) is touched.
- Existing patterns preserved: `xce_sched_repl_state_s` as the single home for REPL-session-scoped display state; `repl_format_ts_human()` as the sole human-timestamp renderer.
- New components rationale: none — this is a localized behavior change to one existing function plus two state fields, not a new component.
- Steering compliance: `src/scheduler/CLAUDE.md`'s 800-line-per-file cap applies to `repl_break.c`, which is already at 949 lines (an accepted residual from `scheduler-sim-repl-verbosity` task 9.2). This spec's addition is small (a handful of lines inside one existing function), but implementation must re-check the file's line count after landing it and, per this file family's established practice, empirically test extracting `repl_print_event_summary()` (and its Event Echo Gate neighbors) into a new file if the total meaningfully exceeds the residual already accepted — not a decision to make speculatively before the actual diff size is known.

## File Structure Plan

### Modified Files
- `src/scheduler/src/repl_break.c` — `repl_print_event_summary()` gains a preamble-print decision at its top: render the candidate human timestamp and displayed session number, compare against `rs->last_echo_ts_human`/`rs->last_echo_session`; print the preamble and update both cache fields only when either differs (or the cache is still at its zero-initialized default), otherwise skip straight to the event's own content switch.
- `src/scheduler/src/repl_internal.h` — `xce_sched_repl_state_s` gains `last_echo_ts_human` (fixed-size char buffer, same size as the existing `repl_format_ts_human()` output buffers elsewhere in this file family) and `last_echo_session` (`uint64_t`), both doc-commented as this feature's cache, zero-initialized by the existing `repl_state_ensure()` allocation path with no additional lifecycle code.

### New/Modified Test Files
- `src/scheduler/testsuite/test_repl_event_echo.c` (extend, existing home for Event Echo Gate behavior this feature builds directly on top of) — the new preamble-dedup tests (see Testing Strategy). This file is at 705 lines going into this spec; re-check its line count after landing these tests and split into a new `test_repl_step_verbosity.c` (following this file family's established "duplicate fixture helpers, don't share" convention — see `scheduler-sim-repl-verbosity` design.md's own Corrections for the precedent) if it approaches this project's ~1000-line split trigger, rather than growing past it.

## Requirements Traceability

| Requirement | Summary | Components | Interfaces | Flows |
|-------------|---------|------------|------------|-------|
| 1.1 | Omit preamble when rendered timestamp+session unchanged | Event Echo Preamble Deduplicator | `repl_print_event_summary()` | n/a |
| 1.2 | Print preamble when rendered timestamp+session changed, or no prior echo | Event Echo Preamble Deduplicator | `repl_print_event_summary()` | n/a |
| 1.3 | Dedup key is rendered (second-granularity) timestamp + session, not raw ns | Event Echo Preamble Deduplicator | `repl_print_event_summary()` | n/a |
| 1.4 | Event content/ordering/echo-selection unaffected | Event Echo Preamble Deduplicator | `repl_print_event_summary()` | n/a |
| 2.1 | No event newly suppressed or added | Out of Boundary (Event Echo Gate unmodified) | n/a | n/a |
| 2.2 | Ordering preserved | Event Echo Preamble Deduplicator | `repl_print_event_summary()` | n/a |
| 2.3 | Every other command's behavior unchanged | Out of Boundary | n/a | n/a |
| 2.4 | No change to scheduling decisions/state | Out of Boundary (display-only change) | n/a | n/a |

## Components and Interfaces

| Component | Domain/Layer | Intent | Req Coverage | Key Dependencies (P0/P1) | Contracts |
|-----------|--------------|--------|---------------|---------------------------|-----------|
| Event Echo Preamble Deduplicator | REPL / repl_break.c | Print the timestamp/session preamble once per distinct rendered context instead of once per event | 1.1-1.4, 2.2 | `repl_format_ts_human()` (P0), `xce_sched_repl_state_s` (P0) | State |

### REPL Output (repl_break.c)

#### Event Echo Preamble Deduplicator
| Field | Detail |
|-------|--------|
| Intent | Suppress the timestamp/session preamble on an echoed event when it would exactly restate the immediately preceding echoed event's rendered context |
| Requirements | 1.1, 1.2, 1.3, 1.4, 2.2 |

**Responsibilities & Constraints**
- Computes the candidate human-readable timestamp via the existing `repl_format_ts_human(xce_core_now(&sim->core), ...)` call already present in `repl_print_event_summary()`, and the candidate displayed session number (`rs->session_count + 1`, the existing expression already used) — no new value sources.
- Compares the candidate pair against `rs->last_echo_ts_human`/`rs->last_echo_session`. Prints the preamble and updates both cache fields when they differ, or when the cache is still at its zero-initialized "never printed" default (empty string / session `0`, values no real echoed event can legitimately produce). Skips the preamble entirely, with no cache update, when they match (Requirement 1.1).
- The comparison is on the RENDERED values only — the underlying raw nanosecond `xce_core_now()` return value is never part of the dedup key, since it changes on every event and two events sharing the same displayed second still have different raw values (Requirement 1.3).
- The event's own content line (the existing `switch (ev->type)` block) is printed unconditionally regardless of the preamble decision — this component only ever suppresses the preamble, never the content (Requirement 1.4, 2.2).

**Dependencies**
- Inbound: `repl_print_event_summary()` (repl_break.c, existing) (P0)
- Outbound: `repl_format_ts_human()` (repl_fmt.c, existing) (P0)

**Contracts**: Service [ ] / API [ ] / Event [ ] / Batch [ ] / State [x]

##### State Management
- State model: two new fields on `xce_sched_repl_state_s` — `last_echo_ts_human` (the last rendered human timestamp actually printed in a preamble) and `last_echo_session` (the last displayed session number actually printed).
- Persistence & consistency: in-memory, scoped to one REPL session, written only by this component, read only by this component. Zero-initialized by `repl_state_ensure()`'s existing `calloc` — no dedicated default-assignment step is needed (unlike `units_mode`'s documented exception in `scheduler-sim-repl-verbosity`), because the zero defaults (empty string, session `0`) can never collide with a real echoed event's rendered values.
- Concurrency strategy: none required — single-threaded sim driver, same as every other REPL state field.

**Implementation Notes**
- Integration: no change to `repl_print_event_summary()`'s call site or signature — purely internal to the function body.
- Validation: covered entirely by the child-process stdout-capture technique `test_repl_event_echo.c` already establishes for Requirement 1 (Event Echo Gate) — no new test harness needed.
- Risks: `repl_break.c`'s existing 949-line accepted residual (see Architecture Integration above) — watch, don't pre-split.

## Data Models

### Domain Model
This feature adds no new domain concept — it extends the existing "REPL session-scoped display state" already modeled on `xce_sched_repl_state_s` (`repl_internal.h`), the same struct the Round Rollup and Resource Value Formatter components added fields to in `scheduler-sim-repl-verbosity`.

### Logical Data Model

| Field | Type | Purpose |
|-------|------|---------|
| `last_echo_ts_human` | `char[32]` | The human-readable timestamp last actually printed in an event's preamble (same buffer size `repl_format_ts_human()`'s other call sites already use) |
| `last_echo_session` | `uint64_t` | The displayed session number last actually printed in an event's preamble |

**Consistency & Integrity**: both fields reset together only at REPL session start, via `repl_state_ensure()`'s existing `calloc` zero-initialization — no explicit reset code path exists or is needed, since no other event in this struct's lifecycle should cause "what was last displayed" to become stale mid-session.

## Error Handling

### Error Strategy
No new failure modes: this feature performs only in-memory string/integer comparisons and a `fprintf` that already exists at this call site — no allocation, no I/O beyond the pre-existing `stdout` write.

### Monitoring
No new logging — the existing `[sim] ...` stdout convention is the only output surface, and this feature only changes how often one of its existing lines appears.

## Testing Strategy

### Integration Tests (extend `test_repl_event_echo.c`, child-process output capture — see File Structure Plan for the split-if-needed note)
- Two consecutive echoed events with identical rendered timestamp and session: the second event's preamble line is absent, its content line still appears (1.1, 1.4).
- Two consecutive echoed events whose session differs (a session boundary occurs between them): both events print their own full preamble (1.2).
- Two consecutive echoed events whose raw high-resolution timestamps differ but whose rendered (rounded) timestamp and session are identical: the second event's preamble is still omitted — the critical case distinguishing this feature's actual dedup key from a naive raw-timestamp comparison (1.3).
- The very first echoed event in a fresh REPL session prints its preamble (no prior echo exists to compare against) (1.2).
- A structural event echoed under `continue` mode after a stretch of suppressed routine events: its preamble prints or is suppressed based on the same rendered-context rule, exercising the dedup logic outside `step` mode too (1.1, 1.2).
- `step` mode's full event/content ordering and count are unchanged versus this feature's baseline — regression check alongside this file's existing Event Echo Gate assertions (2.1, 2.2).

### Regression (existing suites, re-run, no new tests)
- `test_repl_execution_control.c` and `test_repl_equivalence.c`: confirm no other REPL command's output changed and the REPL/batch decision-equivalence guarantee still holds (2.3, 2.4) — the same spot-check discipline `scheduler-sim-repl-verbosity`'s task 10.1/10.2 already established for this exact concern.