a36f7122

scenario: add ScenarioState + tick state machine

a73x 2026-04-19 09:22

Commit message

scenario: add ScenarioState + tick state machine

Tick advances the directive cursor on a monotonic timeline,
invoking caller-supplied callbacks for bytes/capture/flip.
sleep-until-flip rendezvouses with the blink timer via a
caller-observed flag; times out at 2x blink period.

Assert-cell predicates still stubbed — Task 3 wires the
predicate evaluator.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

src/scenario.zig

@@ @@ -752,3 +752,332 @@ test "parse: bytes-hex rejects empty token list" { @@
+    try std.testing.expectEqual(@as(usize, 3), diag.line);
+    try std.testing.expect(std.mem.indexOf(u8, diag.message, "at least one token") != null);
+// ---------------------------------------------------------------
+// Tick state machine
+// ---------------------------------------------------------------
+/// Caller-supplied side-effects. The state machine itself is pure.
+pub const TickIO = struct {
+    ctx: *anyopaque,
+    /// Write bytes into the terminal's VT parser (caller decides whether
+    /// that goes through pty master or direct term.write).
+    write_bytes: *const fn (ctx: *anyopaque, bytes: []const u8) anyerror!void,
+    /// Perform an offscreen render and return an owned png.Image.
+    /// The Scenario will take ownership; caller must not free.
+    capture: *const fn (ctx: *anyopaque, label: []const u8) anyerror!png.Image,
+    /// Return true if the blink timer flipped since the previous tick.
+    /// Used by sleep-until-flip. If blink isn't armed at all, calls
+    /// to this return false forever and sleep-until-flip will time out.
+    blink_just_flipped: *const fn (ctx: *anyopaque) bool,
+};
+pub const TickError = error{
+    ScenarioTimeout,
+    SleepUntilFlipTimeout,
+    AssertFailed,
+    PredicateOnMissingLabel,
+} || std.mem.Allocator.Error || anyerror; // callbacks can surface anyerror
+pub const TickOutcome = enum {
+    working, // directives remain; call tick again later
+    done,    // no more directives
+};
+pub const ScenarioState = struct {
+    scenario: *const Scenario,
+    cursor: usize, // index into scenario.directives
+    origin_ns: i128, // monotonic wall-clock at start
+    deadline_ns: i128, // origin + timeout + slack; exceeding this → TickError.ScenarioTimeout
+    scheduled_offset_ns: i128, // "next directive may execute once (now - origin) >= this"
+    sleep_until_flip_started_ns: ?i128, // set when entering a sleep-until-flip directive
+    captures: std.StringHashMapUnmanaged(png.Image), // label → captured PNG
+    alloc: std.mem.Allocator,
+    pub fn init(
+        alloc: std.mem.Allocator,
+        scenario: *const Scenario,
+        origin_ns: i128,
+    ) ScenarioState {
+        return .{
+            .scenario = scenario,
+            .cursor = 0,
+            .origin_ns = origin_ns,
+            .deadline_ns = origin_ns + @as(i128, scenario.timeout_ms) * std.time.ns_per_ms,
+            .scheduled_offset_ns = 0,
+            .sleep_until_flip_started_ns = null,
+            .captures = .{},
+            .alloc = alloc,
+        };
+    }
+    pub fn deinit(self: *ScenarioState) void {
+        var it = self.captures.iterator();
+        while (it.next()) |entry| {
+            self.alloc.free(entry.key_ptr.*);
+            self.alloc.free(entry.value_ptr.pixels);
+        }
+        self.captures.deinit(self.alloc);
+    }
+    pub fn isDone(self: *const ScenarioState) bool {
+        return self.cursor >= self.scenario.directives.len;
+    }
+    pub fn tick(self: *ScenarioState, now_ns: i128, io: TickIO) TickError!TickOutcome {
+        // Check scenario-level timeout first.
+        if (now_ns > self.deadline_ns) return error.ScenarioTimeout;
+        const elapsed_ns = now_ns - self.origin_ns;
+        // Loop over directives that are ready to execute.
+        while (self.cursor < self.scenario.directives.len) {
+            // Check if the current directive's scheduled time has arrived.
+            if (elapsed_ns < self.scheduled_offset_ns) break;
+            const directive = self.scenario.directives[self.cursor];
+            switch (directive) {
+                .sleep => |ms| {
+                    self.scheduled_offset_ns += @as(i128, ms) * std.time.ns_per_ms;
+                    self.cursor += 1;
+                },
+                .sleep_until_flip => {
+                    if (self.sleep_until_flip_started_ns == null) {
+                        // First encounter: stamp the start time and hold.
+                        self.sleep_until_flip_started_ns = now_ns;
+                        return .working;
+                    }
+                    // Subsequent encounter: check flip or timeout.
+                    if (io.blink_just_flipped(io.ctx)) {
+                        self.sleep_until_flip_started_ns = null;
+                        self.cursor += 1;
+                        // Continue the loop to execute the next directive.
+                    } else {
+                        const started = self.sleep_until_flip_started_ns.?;
+                        const blink_timeout_ns: i128 = 500 * std.time.ns_per_ms * 2;
+                        if (now_ns - started > blink_timeout_ns) {
+                            return error.SleepUntilFlipTimeout;
+                        }
+                        return .working;
+                    }
+                },
+                .bytes => |slice| {
+                    try io.write_bytes(io.ctx, slice);
+                    self.cursor += 1;
+                },
+                .capture => |label| {
+                    const img = try io.capture(io.ctx, label);
+                    // Dupe the label into ScenarioState.alloc so captures outlive the arena.
+                    const label_copy = try self.alloc.dupe(u8, label);
+                    errdefer self.alloc.free(label_copy);
+                    try self.captures.put(self.alloc, label_copy, img);
+                    self.cursor += 1;
+                },
+                .assert_cell => unreachable, // Task 3 wires the predicate evaluator.
+                .assert_cell_at => unreachable, // Task 3 wires the predicate evaluator.
+            }
+        }
+        return if (self.isDone()) .done else .working;
+    }
+};
+// ---------------------------------------------------------------
+// Tick tests
+// ---------------------------------------------------------------
+const TestIO = struct {
+    writes: std.ArrayListUnmanaged(u8) = .{},
+    captures_called: std.ArrayListUnmanaged([]const u8) = .{},
+    flip_stub: bool = false,
+    alloc: std.mem.Allocator,
+    pub fn writeBytes(ctx: *anyopaque, bytes: []const u8) anyerror!void {
+        const self: *TestIO = @ptrCast(@alignCast(ctx));
+        try self.writes.appendSlice(self.alloc, bytes);
+    }
+    pub fn captureCb(ctx: *anyopaque, label: []const u8) anyerror!png.Image {
+        const self: *TestIO = @ptrCast(@alignCast(ctx));
+        const label_copy = try self.alloc.dupe(u8, label);
+        try self.captures_called.append(self.alloc, label_copy);
+        // Return a 1x1 white pixel that the Scenario takes ownership of.
+        const pixels = try self.alloc.alloc(u8, 4);
+        pixels[0] = 255;
+        pixels[1] = 255;
+        pixels[2] = 255;
+        pixels[3] = 255;
+        return .{ .width = 1, .height = 1, .pixels = pixels };
+    }
+    pub fn flipCb(ctx: *anyopaque) bool {
+        const self: *TestIO = @ptrCast(@alignCast(ctx));
+        const v = self.flip_stub;
+        self.flip_stub = false;
+        return v;
+    }
+    pub fn io(self: *TestIO) TickIO {
+        return .{
+            .ctx = self,
+            .write_bytes = writeBytes,
+            .capture = captureCb,
+            .blink_just_flipped = flipCb,
+        };
+    }
+    pub fn deinit(self: *TestIO) void {
+        for (self.captures_called.items) |lbl| self.alloc.free(lbl);
+        self.captures_called.deinit(self.alloc);
+        self.writes.deinit(self.alloc);
+    }
+};
+test "tick: empty scenario is immediately done" {
+    var s = try parseOk(
+        \\size 80 24
+        \\timeout 1000ms
+    );
+    defer s.deinit();
+    var state = ScenarioState.init(std.testing.allocator, &s, 0);
+    defer state.deinit();
+    try std.testing.expect(state.isDone());
+}
+test "tick: bytes directive fires write_bytes immediately" {
+    var s = try parseOk(
+        \\size 80 24
+        \\timeout 1000ms
+        \\bytes "abc"
+    );
+    defer s.deinit();
+    var state = ScenarioState.init(std.testing.allocator, &s, 0);
+    defer state.deinit();
+    var tio = TestIO{ .alloc = std.testing.allocator };
+    defer tio.deinit();
+    const r = try state.tick(0, tio.io());
+    try std.testing.expectEqual(TickOutcome.done, r);
+    try std.testing.expectEqualSlices(u8, "abc", tio.writes.items);
+    try std.testing.expect(state.isDone());
+}
+test "tick: sleep holds advancement until time passes" {
+    var s = try parseOk(
+        \\size 80 24
+        \\timeout 5000ms
+        \\sleep 500ms
+        \\bytes "x"
+    );
+    defer s.deinit();
+    var state = ScenarioState.init(std.testing.allocator, &s, 0);
+    defer state.deinit();
+    var tio = TestIO{ .alloc = std.testing.allocator };
+    defer tio.deinit();
+    // At t=0, sleep is consumed (moves scheduled offset forward); bytes is held.
+    const r1 = try state.tick(0, tio.io());
+    try std.testing.expectEqual(TickOutcome.working, r1);
+    try std.testing.expectEqual(@as(usize, 0), tio.writes.items.len);
+    // At t=250ms, still under scheduled offset — no advance.
+    const r2 = try state.tick(250 * std.time.ns_per_ms, tio.io());
+    try std.testing.expectEqual(TickOutcome.working, r2);
+    try std.testing.expectEqual(@as(usize, 0), tio.writes.items.len);
+    // At t=500ms, bytes fires.
+    const r3 = try state.tick(500 * std.time.ns_per_ms, tio.io());
+    try std.testing.expectEqual(TickOutcome.done, r3);
+    try std.testing.expectEqualSlices(u8, "x", tio.writes.items);
+}
+test "tick: capture calls io.capture and stores the result under the label" {
+    var s = try parseOk(
+        \\size 80 24
+        \\timeout 5000ms
+        \\capture snap1
+    );
+    defer s.deinit();
+    var state = ScenarioState.init(std.testing.allocator, &s, 0);
+    defer state.deinit();
+    var tio = TestIO{ .alloc = std.testing.allocator };
+    defer tio.deinit();
+    _ = try state.tick(0, tio.io());
+    try std.testing.expect(state.isDone());
+    try std.testing.expectEqual(@as(usize, 1), tio.captures_called.items.len);
+    try std.testing.expectEqualSlices(u8, "snap1", tio.captures_called.items[0]);
+    try std.testing.expect(state.captures.contains("snap1"));
+}
+test "tick: scenario timeout fires" {
+    var s = try parseOk(
+        \\size 80 24
+        \\timeout 100ms
+        \\sleep 500ms
+        \\bytes "x"
+    );
+    defer s.deinit();
+    var state = ScenarioState.init(std.testing.allocator, &s, 0);
+    defer state.deinit();
+    var tio = TestIO{ .alloc = std.testing.allocator };
+    defer tio.deinit();
+    // 200ms is past the 100ms scenario timeout.
+    const r = state.tick(200 * std.time.ns_per_ms, tio.io());
+    try std.testing.expectError(error.ScenarioTimeout, r);
+}
+test "tick: sleep-until-flip holds until flip callback returns true" {
+    var s = try parseOk(
+        \\size 80 24
+        \\timeout 5000ms
+        \\sleep-until-flip
+        \\bytes "x"
+    );
+    defer s.deinit();
+    var state = ScenarioState.init(std.testing.allocator, &s, 0);
+    defer state.deinit();
+    var tio = TestIO{ .alloc = std.testing.allocator };
+    defer tio.deinit();
+    // No flip yet — tick holds at the sleep-until-flip directive.
+    tio.flip_stub = false;
+    const r1 = try state.tick(100 * std.time.ns_per_ms, tio.io());
+    try std.testing.expectEqual(TickOutcome.working, r1);
+    try std.testing.expectEqual(@as(usize, 0), tio.writes.items.len);
+    // Flip observed — sleep-until-flip advances; bytes fires.
+    tio.flip_stub = true;
+    const r2 = try state.tick(200 * std.time.ns_per_ms, tio.io());
+    try std.testing.expectEqual(TickOutcome.done, r2);
+    try std.testing.expectEqualSlices(u8, "x", tio.writes.items);
+}
+test "tick: sleep-until-flip times out after 2x blink_period_ns of real wait" {
+    var s = try parseOk(
+        \\size 80 24
+        \\timeout 10000ms
+        \\sleep-until-flip
+    );
+    defer s.deinit();
+    var state = ScenarioState.init(std.testing.allocator, &s, 0);
+    defer state.deinit();
+    var tio = TestIO{ .alloc = std.testing.allocator };
+    defer tio.deinit();
+    // After 2 * 500ms = 1s with no flip observed, fail.
+    // First tick enters the directive, stamps the start time.
+    _ = try state.tick(0, tio.io());
+    // Second tick at t=1.1s — over the 2x blink_period budget.
+    const r = state.tick(1_100 * std.time.ns_per_ms, tio.io());
+    try std.testing.expectError(error.SleepUntilFlipTimeout, r);
+}