graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
Python
//! Structured startup phase receipts. Milestones recorded before the trace
//! file exists are buffered in a fixed array, then flushed when main attaches
//! the session tracer. Later milestones stream directly to that same trace.
const std = @import("std");
const Io = std.Io;
const trace = @import("trace.zig");
/// #364's teardown-side mirror of this module: `GRAFF_SHUTDOWN_DEBUG` phase
/// stamps for the quit path. Re-exported here — rather than imported directly
/// — because its only arming call site is main.zig, which sits exactly at the
/// 600-line ceiling and has no room for an import of its own. `arm`/`at`
/// return their `Io` for the same reason; see shutdown_trace.zig's header.
pub const shutdown_trace = @import("shutdown_trace.zig");
pub const Tracker = struct {
const max_phases = 16;
const Phase = struct { label: []const u8, cumulative_ms: i64, phase_ms: i64 };
started: Io.Timestamp,
debug: bool,
phases: [max_phases]Phase = undefined,
phases_len: usize = 0,
last_ms: i64 = 0,
tracer: ?*trace.Tracer = null,
pub fn init(io: Io, debug: bool) Tracker {
return .{ .started = Io.Timestamp.now(io, .awake), .debug = debug };
}
pub fn mark(self: *Tracker, io: Io, label: []const u8) void {
const cumulative_ms: i64 = @intCast(@max(0, self.started.untilNow(io, .awake).toMilliseconds()));
const phase: Phase = .{
.label = label,
.cumulative_ms = cumulative_ms,
.phase_ms = @max(0, cumulative_ms - self.last_ms),
};
self.last_ms = cumulative_ms;
if (shouldPrint(self.debug, phase.phase_ms))
std.debug.print("[boot +{d}ms, phase {d}ms] {s}\n", .{ phase.cumulative_ms, phase.phase_ms, label });
if (self.tracer) |tracer| {
emit(tracer, phase);
} else if (self.phases_len < self.phases.len) {
self.phases[self.phases_len] = phase;
self.phases_len += 1;
}
}
pub fn attach(self: *Tracker, tracer: *trace.Tracer) void {
if (self.tracer != null) return;
self.tracer = tracer;
for (self.phases[0..self.phases_len]) |phase| emit(tracer, phase);
self.phases_len = 0;
}
/// Phase receipts always reach the trace; stderr is an explicit debug view.
pub fn shouldPrint(debug: bool, _: i64) bool {
return debug;
}
fn emit(tracer: *trace.Tracer, phase: Phase) void {
tracer.write(.{
.t = tracer.elapsedMs(),
.ev = "startup_phase",
.phase = phase.label,
.phase_ms = phase.phase_ms,
.startup_ms = phase.cumulative_ms,
});
}
};
test {
_ = shutdown_trace;
}
test "startup phases retain order and non-negative deltas before attach" {
var tracker = Tracker.init(std.testing.io, false);
tracker.mark(std.testing.io, "args");
tracker.mark(std.testing.io, "credentials");
try std.testing.expectEqual(@as(usize, 2), tracker.phases_len);
try std.testing.expectEqualStrings("args", tracker.phases[0].label);
try std.testing.expectEqualStrings("credentials", tracker.phases[1].label);
try std.testing.expect(tracker.phases[0].phase_ms >= 0);
try std.testing.expect(tracker.phases[1].cumulative_ms >= tracker.phases[0].cumulative_ms);
}
test "boot phase diagnostics require GRAFF_BOOT_DEBUG even for slow phases" {
try std.testing.expect(!Tracker.shouldPrint(false, 0));
try std.testing.expect(!Tracker.shouldPrint(false, 79));
try std.testing.expect(!Tracker.shouldPrint(false, 80));
try std.testing.expect(!Tracker.shouldPrint(false, 80_000));
try std.testing.expect(Tracker.shouldPrint(true, 0));
}