const std = @import("std"); pub const Policy = enum { finality_gated, append_only,}; pub const ToolTurnFloor = struct { turn_id: u64, start_byte: usize,}; /// Activity-independent finality boundaries for one prepared transcript flow./// `tool_turn_floors` is owned when populated and must be released with the/// allocator that created or cloned it.pub const Candidates = struct { mutation_pin_start: ?usize = null, assistant_tail_start: ?usize = null, tool_turn_floors: []const ToolTurnFloor = &.{}, pub fn deinit(self: *Candidates, alloc: std.mem.Allocator) void { if (self.tool_turn_floors.len > 0) alloc.free(self.tool_turn_floors); self.* = .{}; } pub fn clone(self: *const Candidates, alloc: std.mem.Allocator) !Candidates { return .{ .mutation_pin_start = self.mutation_pin_start, .assistant_tail_start = self.assistant_tail_start, .tool_turn_floors = if (self.tool_turn_floors.len == 0) &.{} else try alloc.dupe(ToolTurnFloor, self.tool_turn_floors), }; }}; pub const State = struct { policy: Policy = .finality_gated, assistant_tail_writable: bool = true, pub fn with_assistant_tail_writable(self: State, writable: bool) State { var next = self; next.assistant_tail_writable = writable; return next; } /// Returns the earliest byte that is not final, or null when the entire /// prepared flow may enter native terminal history. pub fn finality_floor( self: State, candidates: Candidates, finalized_tool_turn_watermark: u64, replaceable_start: ?usize, ) ?usize { if (self.policy == .append_only) return null; var floor = candidates.mutation_pin_start; for (candidates.tool_turn_floors) |turn_floor| { if (turn_floor.turn_id <= finalized_tool_turn_watermark) continue; floor = earlier(floor, turn_floor.start_byte); } if (replaceable_start) |start| floor = earlier(floor, start); if (self.assistant_tail_writable) { if (candidates.assistant_tail_start) |start| { floor = earlier(floor, start); } } return floor; }}; fn earlier(current: ?usize, candidate: usize) usize { return if (current) |value| @min(value, candidate) else candidate;} test "transcript release chooses the earliest mutable boundary" { const tool_turns = [_]ToolTurnFloor{ .{ .turn_id = 4, .start_byte = 48 }, .{ .turn_id = 6, .start_byte = 24 }, }; const candidates = Candidates{ .mutation_pin_start = 32, .assistant_tail_start = 16, .tool_turn_floors = &tool_turns, }; try std.testing.expectEqual( @as(?usize, 16), (State{}).finality_floor(candidates, 4, 40), );} test "transcript release ignores final producers and preserves append-only output" { const tool_turns = [_]ToolTurnFloor{ .{ .turn_id = 4, .start_byte = 8 }, }; const candidates = Candidates{ .assistant_tail_start = 12, .tool_turn_floors = &tool_turns, }; try std.testing.expectEqual( @as(?usize, null), (State{ .assistant_tail_writable = false }).finality_floor( candidates, 4, null, ), ); try std.testing.expectEqual( @as(?usize, null), (State{ .policy = .append_only }).finality_floor(candidates, 0, 3), );} test "assistant tail writability returns a new state" { const open = State{}; const closed = open.with_assistant_tail_writable(false); try std.testing.expect(open.assistant_tail_writable); try std.testing.expect(!closed.assistant_tail_writable); try std.testing.expect(closed.with_assistant_tail_writable(true).assistant_tail_writable);}
const std = @import("std");
pub const Policy = enum {
finality_gated,
append_only,
};
pub const ToolTurnFloor = struct {
turn_id: u64,
start_byte: usize,
};
/// Activity-independent finality boundaries for one prepared transcript flow.
/// `tool_turn_floors` is owned when populated and must be released with the
/// allocator that created or cloned it.
pub const Candidates = struct {
mutation_pin_start: ?usize = null,
assistant_tail_start: ?usize = null,
tool_turn_floors: []const ToolTurnFloor = &.{},
pub fn deinit(self: *Candidates, alloc: std.mem.Allocator) void {
if (self.tool_turn_floors.len > 0) alloc.free(self.tool_turn_floors);
self.* = .{};
}
pub fn clone(self: *const Candidates, alloc: std.mem.Allocator) !Candidates {
return .{
.mutation_pin_start = self.mutation_pin_start,
.assistant_tail_start = self.assistant_tail_start,
.tool_turn_floors = if (self.tool_turn_floors.len == 0)
&.{}
else
try alloc.dupe(ToolTurnFloor, self.tool_turn_floors),
};
}
};
pub const State = struct {
policy: Policy = .finality_gated,
assistant_tail_writable: bool = true,
pub fn with_assistant_tail_writable(self: State, writable: bool) State {
var next = self;
next.assistant_tail_writable = writable;
return next;
}
/// Returns the earliest byte that is not final, or null when the entire
/// prepared flow may enter native terminal history.
pub fn finality_floor(
self: State,
candidates: Candidates,
finalized_tool_turn_watermark: u64,
replaceable_start: ?usize,
) ?usize {
if (self.policy == .append_only) return null;
var floor = candidates.mutation_pin_start;
for (candidates.tool_turn_floors) |turn_floor| {
if (turn_floor.turn_id <= finalized_tool_turn_watermark) continue;
floor = earlier(floor, turn_floor.start_byte);
}
if (replaceable_start) |start| floor = earlier(floor, start);
if (self.assistant_tail_writable) {
if (candidates.assistant_tail_start) |start| {
floor = earlier(floor, start);
}
}
return floor;
}
};
fn earlier(current: ?usize, candidate: usize) usize {
return if (current) |value| @min(value, candidate) else candidate;
}
test "transcript release chooses the earliest mutable boundary" {
const tool_turns = [_]ToolTurnFloor{
.{ .turn_id = 4, .start_byte = 48 },
.{ .turn_id = 6, .start_byte = 24 },
};
const candidates = Candidates{
.mutation_pin_start = 32,
.assistant_tail_start = 16,
.tool_turn_floors = &tool_turns,
};
try std.testing.expectEqual(
@as(?usize, 16),
(State{}).finality_floor(candidates, 4, 40),
);
}
test "transcript release ignores final producers and preserves append-only output" {
const tool_turns = [_]ToolTurnFloor{
.{ .turn_id = 4, .start_byte = 8 },
};
const candidates = Candidates{
.assistant_tail_start = 12,
.tool_turn_floors = &tool_turns,
};
try std.testing.expectEqual(
@as(?usize, null),
(State{ .assistant_tail_writable = false }).finality_floor(
candidates,
4,
null,
),
);
try std.testing.expectEqual(
@as(?usize, null),
(State{ .policy = .append_only }).finality_floor(candidates, 0, 3),
);
}
test "assistant tail writability returns a new state" {
const open = State{};
const closed = open.with_assistant_tail_writable(false);
try std.testing.expect(open.assistant_tail_writable);
try std.testing.expect(!closed.assistant_tail_writable);
try std.testing.expect(closed.with_assistant_tail_writable(true).assistant_tail_writable);
}