Skip to content

graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs

Python
10.7 KB
Raw Blame
//! Private, verbatim pre-compaction history. No summaries and no network IO.
//! A checkpoint only reverses an exact prefix replacement; changed windows
//! fail closed. Root recovery owns transport/meter resets after installation.
const std = @import("std");
const builtin = @import("builtin");
const Io = std.Io;
const Value = std.json.Value;
const Agent = @import("agent.zig").Agent;
const Allocator = std.mem.Allocator;
const windows = @import("compaction_window.zig");

pub const max_checkpoint_bytes = 64 * 1024 * 1024;
const private_file: Io.File.Permissions = if (builtin.os.tag == .windows) .default_file else .fromMode(0o600);
const private_dir: Io.File.Permissions = if (builtin.os.tag == .windows) .default_dir else .fromMode(0o700);
const Payload = struct { before: []const Value, window: []const Value };
const Snapshot = struct {
    version: u32,
    blob_sha256: []const u8,
    history_sha256: []const u8,
    before: []const Value,
    window: []const Value,
};

pub fn safeSessionName(name: []const u8) bool {
    if (name.len == 0 or name.len > 160 or name[0] == '.') return false;
    for (name) |c| if (!std.ascii.isAlphanumeric(c) and c != '-' and c != '_' and c != '.') return false;
    return true;
}

fn hash(bytes: []const u8) [64]u8 {
    var digest: [32]u8 = undefined;
    std.crypto.hash.sha2.Sha256.hash(bytes, &digest, .{});
    return std.fmt.bytesToHex(digest, .lower);
}

fn valueHash(a: Allocator, value: anytype) ![64]u8 {
    const bytes = try std.json.Stringify.valueAlloc(a, value, .{});
    defer a.free(bytes);
    return hash(bytes);
}

fn openChild(io: Io, parent: Io.Dir, name: []const u8, create: bool) !Io.Dir {
    if (create) {
        parent.createDir(io, name, private_dir) catch |err| if (err != error.PathAlreadyExists) return err;
        try syncDirectory(io, parent);
    }
    // Walk one component at a time, never following a symlink, so even an
    // existing .graff/sessions tree cannot redirect a checkpoint outside cwd.
    return parent.openDir(io, name, .{ .follow_symlinks = false });
}

fn directory(io: Io, session: []const u8, create: bool) !Io.Dir {
    const graff = try openChild(io, .cwd(), ".graff", create);
    defer graff.close(io);
    const sessions = try openChild(io, graff, "sessions", create);
    defer sessions.close(io);
    const session_dir = try openChild(io, sessions, session, create);
    defer session_dir.close(io);
    return openChild(io, session_dir, "compaction", create);
}

/// Move ONLY the checkpoint subtree when the root session acquires its AI
/// title. No history/name mutation here. Existing destinations are never
/// replaced, even when empty or created concurrently. Fork/save-as needs a
/// separate copy policy: moving these checkpoints would strand the source.
pub fn rename(self: *Agent, old_name: []const u8, new_name: []const u8) !void {
    if (self.sub or old_name.len == 0) return;
    if (!safeSessionName(old_name) or !safeSessionName(new_name)) return error.UnsafeCheckpointSession;
    if (std.mem.eql(u8, old_name, new_name)) return;
    const graff = openChild(self.io, .cwd(), ".graff", false) catch |err| {
        if (err == error.FileNotFound) return;
        return err;
    };
    defer graff.close(self.io);
    const sessions = openChild(self.io, graff, "sessions", false) catch |err| {
        if (err == error.FileNotFound) return;
        return err;
    };
    defer sessions.close(self.io);
    const old_dir = openChild(self.io, sessions, old_name, false) catch |err| {
        if (err == error.FileNotFound) return;
        return err;
    };
    defer old_dir.close(self.io);
    const source = openChild(self.io, old_dir, "compaction", false) catch |err| {
        if (err == error.FileNotFound) return;
        return err;
    };
    defer source.close(self.io);
    const new_dir = try openChild(self.io, sessions, new_name, true);
    defer new_dir.close(self.io);
    try old_dir.renamePreserve("compaction", new_dir, "compaction", self.io);
    // If durability fails, retain the old name's mapping when rollback is
    // possible. Never overwrite a concurrently installed mapping on rollback.
    errdefer new_dir.renamePreserve("compaction", old_dir, "compaction", self.io) catch {};
    try syncDirectory(self.io, new_dir);
    try syncDirectory(self.io, old_dir);
}

fn readBounded(io: Io, dir: Io.Dir, a: Allocator, name: []const u8) ![]u8 {
    const file = try dir.openFile(io, name, .{ .follow_symlinks = false, .resolve_beneath = true });
    defer file.close(io);
    const stat = try file.stat(io);
    if (stat.kind != .file or stat.size > max_checkpoint_bytes) return error.InvalidCheckpointFile;
    if (builtin.os.tag != .windows and (stat.permissions.toMode() & 0o077) != 0) return error.InsecureCheckpointFile;
    const bytes = try a.alloc(u8, @intCast(stat.size));
    errdefer a.free(bytes);
    if (try file.readPositionalAll(io, bytes, 0) != bytes.len) return error.TruncatedCheckpoint;
    const after = try file.stat(io);
    if (after.kind != .file or after.size != stat.size) return error.CheckpointChanged;
    return bytes;
}

fn syncDirectory(io: Io, dir: Io.Dir) !void {
    if (builtin.os.tag == .windows) return;
    const file = try dir.openFile(io, ".", .{ .allow_directory = true, .follow_symlinks = false, .resolve_beneath = true });
    defer file.close(io);
    try file.sync(io);
}

fn filename(buf: []u8, digest: []const u8) ![]const u8 {
    return std.fmt.bufPrint(buf, "{s}.json", .{digest});
}

fn containsBlob(a: Allocator, items: []const Value, digest: []const u8) !bool {
    for (items) |item| {
        if (windows.latestBlob(&.{item}) == null) continue;
        const existing = try valueHash(a, item);
        if (std.mem.eql(u8, &existing, digest)) return true;
    }
    return false;
}

/// Call BEFORE replacing history. A duplicate blob is not sufficient evidence
/// of identical ancestry: the complete immutable payload must also agree.
/// Non-durable test/auxiliary agents and subagents have no root-session mapping.
pub fn preserve(self: *Agent, before: []const Value, window: []const Value) !void {
    if (self.sub or self.session_name.len == 0) return;
    if (!safeSessionName(self.session_name)) return error.UnsafeCheckpointSession;
    const k = windows.latestBlob(window) orelse return error.MissingCompactionItem;
    const digest = try valueHash(self.gpa, window[k]);
    if (try containsBlob(self.gpa, before, &digest)) return error.NonExpandingCheckpoint;
    const history_digest = try valueHash(self.gpa, Payload{ .before = before, .window = window });
    const bytes = try std.json.Stringify.valueAlloc(self.gpa, Snapshot{
        .version = 1,
        .blob_sha256 = &digest,
        .history_sha256 = &history_digest,
        .before = before,
        .window = window,
    }, .{});
    defer self.gpa.free(bytes);
    if (bytes.len > max_checkpoint_bytes) return error.CheckpointTooLarge;
    const dir = try directory(self.io, self.session_name, true);
    defer dir.close(self.io);
    var name_buf: [69]u8 = undefined;
    const name = try filename(&name_buf, &digest);
    var atomic = try dir.createFileAtomic(self.io, name, .{ .permissions = private_file, .replace = false });
    defer atomic.deinit(self.io);
    try atomic.file.writeStreamingAll(self.io, bytes);
    try atomic.file.sync(self.io);
    atomic.link(self.io) catch |err| switch (err) {
        error.PathAlreadyExists => {
            const existing = try readBounded(self.io, dir, self.gpa, name);
            defer self.gpa.free(existing);
            if (!std.mem.eql(u8, existing, bytes)) return error.ImmutableCheckpointConflict;
        },
        else => return err,
    };
    try syncDirectory(self.io, dir);
}

fn sameValues(a: Allocator, lhs: []const Value, rhs: []const Value) !bool {
    const left = try std.json.Stringify.valueAlloc(a, lhs, .{});
    defer a.free(left);
    const right = try std.json.Stringify.valueAlloc(a, rhs, .{});
    defer a.free(right);
    return std.mem.eql(u8, left, right);
}

/// Expands exactly the newest opaque item, preserving its entire later tail.
/// Missing, unsafe, corrupt or changed checkpoints never change live history.
/// Allocation failures propagate; callers may bound repeated ancestor restores.
/// Only messages/provenance change here; the root recovery coordinator must
/// closeCodexWs and reset meters, goal fingerprint and history_rewrites.
pub fn restore(self: *Agent) !bool {
    if (self.sub or self.session_name.len == 0 or !safeSessionName(self.session_name)) return false;
    const latest = windows.latestBlob(self.messages.items) orelse return false;
    const digest = try valueHash(self.gpa, self.messages.items[latest]);
    const dir = directory(self.io, self.session_name, false) catch return false;
    defer dir.close(self.io);
    var name_buf: [69]u8 = undefined;
    const name = try filename(&name_buf, &digest);
    const bytes = readBounded(self.io, dir, self.gpa, name) catch |err| {
        if (err == error.OutOfMemory) return err;
        return false;
    };
    defer self.gpa.free(bytes);
    var parsed = std.json.parseFromSlice(Snapshot, self.gpa, bytes, .{ .allocate = .alloc_always }) catch |err| {
        if (err == error.OutOfMemory) return err;
        return false;
    };
    defer parsed.deinit();
    const saved = parsed.value;
    if (saved.version != 1 or !std.mem.eql(u8, saved.blob_sha256, &digest)) return false;
    const blob = windows.latestBlob(saved.window) orelse return false;
    const saved_digest = try valueHash(self.gpa, saved.window[blob]);
    if (!std.mem.eql(u8, &saved_digest, &digest)) return false;
    const history_digest = try valueHash(self.gpa, Payload{ .before = saved.before, .window = saved.window });
    if (!std.mem.eql(u8, saved.history_sha256, &history_digest)) return false;
    if (try containsBlob(self.gpa, saved.before, &digest)) return false;
    // Canonical windows may retain items on BOTH sides of the blob. Match
    // the whole prefix, not merely the blob, and never guess about prepends.
    if (latest != blob or saved.window.len > self.messages.items.len) return false;
    if (!try sameValues(self.gpa, saved.window, self.messages.items[0..saved.window.len])) return false;

    // Stage every fallible allocation before installing. Parsed values belong
    // to the temporary parser arena; transfer via an owned session-arena copy.
    var staged = std.json.Array.init(self.gpa);
    defer staged.deinit();
    try staged.appendSlice(saved.before);
    try staged.appendSlice(self.messages.items[saved.window.len..]);
    const encoded = try std.json.Stringify.valueAlloc(self.gpa, staged.items, .{});
    defer self.gpa.free(encoded);
    const fresh = try std.json.parseFromSliceLeaky(Value, self.arena, encoded, .{ .allocate = .alloc_always });
    self.messages = fresh.array;
    self.compaction_window = .{};
    return true;
}