Skip to content

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

Python
21.2 KB
Raw Blame
//! #381 + #383 — the itemized playbook: one durable, project-local ledger of
//! short imperative bullets that ride every brief.
//!
//! Two issues, one substrate, because they are the same bug seen from two
//! sides. #381: a user said "no navigation dots", the root compacted, and
//! fresh subagents — who were never told — put the dots back. #383: 120
//! subagent reports full of durable repo knowledge ("no mobile menu exists,
//! don't invent one") evaporated with the context that held them. In both
//! cases the harness HAD the fact and dropped it on the floor between the
//! place it was learned and the brief that needed it.
//!
//! ACE (Zhang et al., ICLR 2026) supplies the shape and the hard rule:
//!
//!   * ITEMIZED, not a blob. Iteratively asking a model to rewrite a
//!     prompt-sized artifact causes context collapse and brevity bias — the
//!     failure #383 quotes. Bullets with stable ids merge instead.
//!   * CURATION IS DETERMINISTIC CODE. Nothing in this file asks a model
//!     what the playbook should contain. add/retire are explicit ops, dedupe
//!     is an exact match on normalized text, and the caps are constants. A
//!     model may PROPOSE an item (the #383 reflector) and the user may state
//!     one (#381), but only this code decides what lands.
//!
//! ON-DISK FORMAT — `.graff/playbook.jsonl`, append-only JSONL, matching the
//! `.graff/trajectories` conventions (one self-describing JSON object per
//! line, written whole or not at all, never rewritten in place):
//!
//!   {"v":2,"op":"add","id":"pb-3f8c1d02","text":"…","source":"user",
//!    "scope":"project","provenance":"user:1754…","created_at":1754…}
//!   {"v":1,"op":"retire","id":"pb-3f8c1d02","t":1754…}
//!
//! A retire is a NEW RECORD (a tombstone), never an edit, so a concurrent
//! reader mid-append sees either the old state or the new one — never a torn
//! file. `parse` replays the log in order and lets the last op for an id win,
//! which also makes re-adding a retired item work for free.
//!
//! IDS ARE CONTENT-DERIVED: `pb-` + 32 bits of Wyhash over the NORMALIZED
//! text. That makes dedupe and identity the same operation — two phrasings
//! that normalize identically cannot both exist, and an id is stable across
//! sessions and machines, which is what lets a later change attribute
//! per-item fitness to it.
//!
//! ASSEMBLY READS THE FILE, NEVER CONVERSATION MEMORY. `blockNow`'s input is
//! the ledger on disk at the moment a brief is built. That single choice is
//! what makes compaction survival automatic rather than a feature: there is
//! no in-context copy for compaction to summarize away, and a brand-new
//! session in the same project starts with the same constraints.

const std = @import("std");
const Io = std.Io;
const Allocator = std.mem.Allocator;
const util = @import("util.zig");
const trace = @import("trace.zig");

pub const dir = ".graff";
pub const path = ".graff/playbook.jsonl";

/// Whole-ledger read cap. A playbook is bullets, not a corpus; past this the
/// file is something else and injecting it would be the bug, not the fix.
pub const max_file_bytes = 512 * 1024;
/// Longest single item, in bytes, kept on disk and injected.
pub const max_text = 240;
/// #383 curator ceiling on stored LEARNED items. v1 refuses past it with a
/// note rather than evicting: eviction needs per-item fitness to be safe, and
/// that attribution is deliberately follow-up scope.
pub const max_learned = 100;

/// Injection caps. User items outrank learned ones on every axis — more of
/// them, more bytes, and always printed first — because a user constraint is
/// a rule and a learned bullet is a hint.
pub const user_block_items = 30;
pub const user_block_bytes = 2048;
pub const learned_block_items = 12;
pub const learned_block_bytes = 1024;

pub const user_header = "HARD CONSTRAINTS (user, project scope, do not violate):";
pub const legacy_header = "LEGACY UNSCOPED CONSTRAINTS (active pending user review with /never):";
pub const learned_header = "PLAYBOOK (learned, advisory):";

pub const Scope = enum {
    project,
    legacy_unscoped,

    pub fn parse(source: Source, raw: ?[]const u8) Scope {
        if (raw) |s| if (std.mem.eql(u8, s, "project")) return .project;
        return if (source == .user) .legacy_unscoped else .project;
    }
};

pub const Source = enum {
    /// #381: a rejection the user stated. Never model-editable, hard-injected.
    user,
    /// #383: an insight distilled from a scored run. Advisory, capped, and
    /// printed after every user item.
    learned,

    pub fn parse(s: []const u8) Source {
        return if (std.mem.eql(u8, s, "learned")) .learned else .user;
    }
};

pub const Item = struct {
    id: []const u8,
    text: []const u8,
    source: Source,
    /// New user records are explicit project policy. Missing scope marks a
    /// legacy v1 record for review instead of silently confirming permanence.
    scope: Scope = .project,
    /// What minted it: `user:<unix ms>` for a typed/observed rejection,
    /// `run:<trajectory run id>` for a distilled one.
    provenance: []const u8 = "",
    created_at: i64 = 0,
};

/// Why an `add` did or did not land. A refusal is reported, never silent:
/// the model and the user both need to know a constraint was NOT recorded.
pub const Add = struct {
    ok: bool = false,
    id: []const u8 = "",
    /// Human/model-facing explanation; "" on success.
    reason: []const u8 = "",
};

/// Word bytes for normalization: ASCII alphanumerics plus every non-ASCII
/// byte, so a UTF-8 word stays one token instead of shattering (the same rule
/// brief_diversity.isWordByte uses, and for the same reason).
fn isWordByte(c: u8) bool {
    return std.ascii.isAlphanumeric(c) or c >= 0x80;
}

/// U+2000–U+206F (General Punctuation) encodes as E2 80 xx / E2 81 xx, and
/// that block is where a model or a paste actually gets its punctuation: em
/// and en dashes, curly quotes, the ellipsis, the bullet. They are dropped
/// like their ASCII cousins — otherwise `no dots — really` and `no dots
/// really` would be two separate constraints forever. Every OTHER non-ASCII
/// byte stays a word byte, so a non-Latin constraint is not shredded.
fn isPunctSeq(text: []const u8, i: usize) bool {
    return i + 2 < text.len and text[i] == 0xE2 and (text[i + 1] == 0x80 or text[i + 1] == 0x81);
}

/// Lowercase, drop punctuation, collapse runs of everything else to one
/// space. This is the whole dedupe key: "No emojis in code comments!" and
/// "no emojis in code comments" are the same constraint stated twice, and a
/// ledger that held both would inject the same rule twice forever.
pub fn normalize(out: []u8, text: []const u8) []const u8 {
    var n: usize = 0;
    var pending_space = false;
    var i: usize = 0;
    while (i < text.len) {
        if (isPunctSeq(text, i)) {
            pending_space = true;
            i += 3;
            continue;
        }
        const c = text[i];
        i += 1;
        if (!isWordByte(c)) {
            pending_space = true;
            continue;
        }
        if (n > 0 and pending_space and n < out.len) {
            out[n] = ' ';
            n += 1;
        }
        pending_space = false;
        if (n == out.len) break;
        out[n] = std.ascii.toLower(c);
        n += 1;
    }
    return out[0..n];
}

/// `pb-` + 32 bits of Wyhash over the normalized text (11 bytes).
pub fn idFor(out: *[11]u8, text: []const u8) []const u8 {
    var nbuf: [max_text]u8 = undefined;
    const h = std.hash.Wyhash.hash(0x381383, normalize(&nbuf, text));
    return std.fmt.bufPrint(out, "pb-{x:0>8}", .{@as(u32, @truncate(h))}) catch out[0..0];
}

fn strOf(o: std.json.ObjectMap, key: []const u8) ?[]const u8 {
    const v = o.get(key) orelse return null;
    return if (v == .string) v.string else null;
}

/// Replay the append-only log into the live item set, oldest first. Malformed
/// lines are skipped rather than fatal — a half-written tail from a killed
/// process must cost at most its own record.
pub fn parse(arena: Allocator, data: []const u8) []const Item {
    var list: std.ArrayList(Item) = .empty;
    var lines = std.mem.splitScalar(u8, data, '\n');
    while (lines.next()) |raw| {
        const line = std.mem.trim(u8, raw, " \t\r");
        if (line.len == 0) continue;
        const v = std.json.parseFromSliceLeaky(std.json.Value, arena, line, .{}) catch continue;
        if (v != .object) continue;
        const id = strOf(v.object, "id") orelse continue;
        var at: ?usize = null;
        for (list.items, 0..) |item, i| if (std.mem.eql(u8, item.id, id)) {
            at = i;
            break;
        };
        if (std.mem.eql(u8, strOf(v.object, "op") orelse "add", "retire")) {
            if (at) |i| _ = list.orderedRemove(i);
            continue;
        }
        const text = strOf(v.object, "text") orelse continue;
        const created = v.object.get("created_at");
        const source = Source.parse(strOf(v.object, "source") orelse "user");
        const item: Item = .{
            .id = id,
            .text = text,
            .source = source,
            .scope = Scope.parse(source, strOf(v.object, "scope")),
            .provenance = strOf(v.object, "provenance") orelse "",
            .created_at = if (created) |c| (if (c == .integer) c.integer else 0) else 0,
        };
        if (at) |i| list.items[i] = item else list.append(arena, item) catch break;
    }
    return list.items;
}

/// The live ledger for the current working directory. An absent or unreadable
/// file is an empty playbook, never an error: every caller is on a path that
/// must keep working without one.
pub fn load(io: Io, arena: Allocator) []const Item {
    const data = Io.Dir.cwd().readFileAlloc(io, path, arena, .limited(max_file_bytes)) catch return &.{};
    return parse(arena, data);
}

pub fn countOf(items: []const Item, source: Source) usize {
    var n: usize = 0;
    for (items) |item| n += @intFromBool(item.source == source);
    return n;
}

pub fn find(items: []const Item, id: []const u8) ?Item {
    for (items) |item| if (std.mem.eql(u8, item.id, id)) return item;
    return null;
}

/// Unique live item whose normalized text contains `query`, or whose text
/// is contained in `query`. Ambiguous / too-short queries return null so a
/// caller can ask for an id instead of retiring the wrong rule (#638).
pub fn findByUniqueText(items: []const Item, query: []const u8) ?Item {
    var qbuf: [max_text]u8 = undefined;
    const q = normalize(&qbuf, query);
    if (q.len < 4) return null;
    var found: ?Item = null;
    for (items) |item| {
        var ibuf: [max_text]u8 = undefined;
        const it = normalize(&ibuf, item.text);
        if (it.len == 0) continue;
        if (std.mem.indexOf(u8, it, q) == null and std.mem.indexOf(u8, q, it) == null) continue;
        if (found != null) return null;
        found = item;
    }
    return found;
}

/// Append one already-serialized record. Positional write at the current end
/// of file so a whole line lands at once (serve_events.EventLog's shape).
fn appendLine(io: Io, line: []const u8) bool {
    Io.Dir.cwd().createDirPath(io, dir) catch {};
    const f = Io.Dir.cwd().createFile(io, path, .{ .truncate = false }) catch return false;
    defer f.close(io);
    const st = f.stat(io) catch return false;
    f.writePositionalAll(io, line, st.size) catch return false;
    return true;
}

fn appendAdd(io: Io, arena: Allocator, id: []const u8, text: []const u8, source: Source, provenance: []const u8) Add {
    var aw: Io.Writer.Allocating = .init(arena);
    var s: std.json.Stringify = .{ .writer = &aw.writer };
    s.write(.{
        .v = @as(u8, 2),
        .op = "add",
        .id = id,
        .text = text,
        .source = @tagName(source),
        .scope = @tagName(Scope.project),
        .provenance = provenance,
        .created_at = util.unixMs(io),
    }) catch return .{ .id = id, .reason = "could not serialize the record" };
    aw.writer.writeByte('\n') catch return .{ .id = id, .reason = "could not serialize the record" };
    if (!appendLine(io, aw.writer.buffered())) return .{ .id = id, .reason = "could not write " ++ path };
    return .{ .ok = true, .id = id };
}

/// The one way an item is created. DETERMINISTIC: trim whitespace, cap,
/// normalize, derive the id, reconcile exact matches, enforce the learned
/// ceiling, append. No model is consulted and nothing existing is rewritten.
pub fn add(io: Io, arena: Allocator, text_in: []const u8, source: Source, provenance: []const u8) Add {
    const trimmed = std.mem.trim(u8, text_in, " \t\r\n");
    const text = util.utf8Prefix(trimmed, max_text);
    var nbuf: [max_text]u8 = undefined;
    if (normalize(&nbuf, text).len == 0) return .{ .reason = "empty constraint text" };
    var idbuf: [11]u8 = undefined;
    const id = arena.dupe(u8, idFor(&idbuf, text)) catch return .{ .reason = "out of memory" };
    const items = load(io, arena);
    if (find(items, id)) |existing| {
        if (!std.mem.eql(u8, existing.text, text)) return .{
            .id = id,
            .reason = "normalized id collision with different exact text; existing record was not changed",
        };
        if (source == .user and (existing.source != .user or existing.scope != .project))
            return appendAdd(io, arena, id, text, .user, provenance);
        if (existing.source == source and existing.scope == .project)
            return .{ .id = id, .reason = "already recorded (same exact text, source, and scope)" };
        return .{ .id = id, .reason = "already recorded as a user project constraint" };
    }
    if (source == .learned and countOf(items, .learned) >= max_learned)
        return .{ .id = id, .reason = "learned playbook is at its 100-item cap; retire some with /never rm <id> first" };
    return appendAdd(io, arena, id, text, source, provenance);
}

/// Why a `retire` did or did not land. A write failure is not "unknown id":
/// the item is still live and the caller must say so (#644).
pub const Retire = enum { ok, unknown, write_failed };

/// Tombstone `id`. `.unknown` when no live item carries it (no tombstone
/// written). `.write_failed` when the item exists but the ledger append
/// did not land — the constraint stays active.
pub fn retire(io: Io, arena: Allocator, id: []const u8) Retire {
    if (find(load(io, arena), id) == null) return .unknown;
    var aw: Io.Writer.Allocating = .init(arena);
    var s: std.json.Stringify = .{ .writer = &aw.writer };
    s.write(.{ .v = @as(u8, 1), .op = "retire", .id = id, .t = util.unixMs(io) }) catch return .write_failed;
    aw.writer.writeByte('\n') catch return .write_failed;
    return if (appendLine(io, aw.writer.buffered())) .ok else .write_failed;
}

fn writeSection(w: *Io.Writer, items: []const Item, source: Source, scope: ?Scope, header: []const u8, cap_items: usize, cap_bytes: usize) !bool {
    var shown: usize = 0;
    var used: usize = 0;
    var omitted: usize = 0;
    // Newest first: the most recent "no" is the one most likely to be about
    // the work in flight, and it must survive the cap.
    var i = items.len;
    while (i > 0) {
        i -= 1;
        const item = items[i];
        if (item.source != source) continue;
        if (scope) |wanted| if (item.scope != wanted) continue;
        if (shown >= cap_items or used + item.text.len + 3 > cap_bytes) {
            omitted += 1;
            continue;
        }
        if (shown == 0) try w.print("{s}\n", .{header});
        try w.print("- {s}\n", .{item.text});
        shown += 1;
        used += item.text.len + 3;
    }
    // An unstated truncation is a lie by omission: a worker told "these are
    // the constraints" must know when it was told only some of them.
    if (omitted > 0) try w.print("[{d} older item(s) omitted by the injection cap — the full ledger is {s}]\n", .{ omitted, path });
    return shown > 0;
}

/// The injection block for `items`, or "" when there is nothing to say.
/// Confirmed project rules lead; legacy unscoped records are visibly pending
/// review; learned advice remains last and advisory.
pub fn blockFrom(arena: Allocator, items: []const Item) []const u8 {
    if (items.len == 0) return "";
    var aw: Io.Writer.Allocating = .init(arena);
    if (writeSection(&aw.writer, items, .user, .project, user_header, user_block_items, user_block_bytes) catch return "")
        aw.writer.writeByte('\n') catch return "";
    if (writeSection(&aw.writer, items, .user, .legacy_unscoped, legacy_header, user_block_items, user_block_bytes) catch return "")
        aw.writer.writeByte('\n') catch return "";
    _ = writeSection(&aw.writer, items, .learned, null, learned_header, learned_block_items, learned_block_bytes) catch return "";
    const out = std.mem.trim(u8, aw.writer.buffered(), "\n");
    return if (out.len == 0) "" else out;
}

/// The block for the ledger as it exists on disk RIGHT NOW. This is the
/// function every injection site calls, and reading the file here rather
/// than caching a copy in the conversation is the whole compaction-survival
/// mechanism.
pub fn blockNow(io: Io, arena: Allocator) []const u8 {
    return blockFrom(arena, load(io, arena));
}

/// Prepend the block to a brief. Identity when the ledger is empty, so a
/// project that never recorded anything pays nothing.
pub fn rideBrief(io: Io, arena: Allocator, prompt: []const u8) []const u8 {
    const b = blockNow(io, arena);
    if (b.len == 0) return prompt;
    return std.fmt.allocPrint(arena, "{s}\n\n{s}", .{ b, prompt }) catch prompt;
}

/// Armed once by prompts.setRootSystemPrompts (production root agents only).
/// Unit tests never arm it, so prompts.setSystemPrompts stays the pure string
/// funnel its own tests assert — and no test path can reach the filesystem
/// through an `undefined` Io.
pub var g_root_inject: bool = false;

/// #738: only durable user records confer recorded-constraint authority.
/// JSON keeps ids, provenance and text separate from generated recap prose.
/// Include the empty set too: absence is evidence, not permission for a recap
/// to invent a recording. Learned advice never enters this authoritative set.
pub fn recordedState(arena: Allocator, items: []const Item) ![]const u8 {
    var aw: Io.Writer.Allocating = .init(arena);
    var s: std.json.Stringify = .{ .writer = &aw.writer };
    try s.beginObject();
    try s.objectField("recorded_user_constraints");
    try s.beginArray();
    for (items) |item| {
        if (item.source != .user) continue;
        try s.write(.{ .id = item.id, .text = item.text, .scope = @tagName(item.scope), .provenance = item.provenance, .created_at = item.created_at });
    }
    try s.endArray();
    try s.endObject();
    return aw.writer.buffered();
}

pub const authority_note =
    "RECORDED CONSTRAINT AUTHORITY: The following JSON is derived only from the live durable ledger, not model memory. " ++
    "Only project-scoped entries are confirmed standing policy; legacy_unscoped entries remain active for compatibility but require user review with /never. " ++
    "A summary, handoff, or opaque compaction state is not evidence that note_constraint succeeded; never promote its claims into recorded rules. " ++
    "An empty array means no user constraints are recorded. This does not cancel explicit local instructions, and never overrides safety requirements.";

/// The ROOT's system prompt for the ledger as it exists on disk right now:
/// base, then the same block every worker brief carries. It lives in the
/// SYSTEM prompt rather than in a per-turn user message on purpose — a
/// re-pasted note lands in compaction input every single turn (#326's
/// lesson), while the system prompt is re-sent verbatim on every request and
/// is exactly what a compacted conversation cannot lose.
pub fn composeRoot(io: Io, arena: Allocator, base: []const u8) []const u8 {
    const items = load(io, arena);
    traceActive(arena, items);
    const b = blockFrom(arena, items);
    const state = recordedState(arena, items) catch return base;
    return std.fmt.allocPrint(arena, "{s}\n\n{s}\n{s}\n\n{s}", .{ base, authority_note, state, b }) catch base;
}

/// Comma-joined active ids, capped, for the trajectory row below.
pub fn idList(arena: Allocator, items: []const Item) []const u8 {
    var aw: Io.Writer.Allocating = .init(arena);
    for (items, 0..) |item, i| {
        if (i > 0) aw.writer.writeByte(',') catch break;
        aw.writer.writeAll(item.id) catch break;
    }
    return util.utf8Prefix(aw.writer.buffered(), 1024);
}

/// Fingerprint of the last emitted `kind:"playbook"` row, so re-composing an
/// unchanged ledger does not write the same row again.
var g_last_row: u64 = 0;

/// A NEW `kind:"playbook"` trajectory row naming which item ids were active,
/// rather than new columns on an existing row — the same additive discipline
/// #382's `kind:"diversity"` row established, and what a later change joins
/// against to attribute per-item fitness. Best-effort; never fails a caller.
pub fn traceActive(arena: Allocator, items: []const Item) void {
    const tj = trace.g_traj orelse return;
    const ids = idList(arena, items);
    const fp = std.hash.Wyhash.hash(0x381383, ids);
    if (fp == g_last_row) return;
    g_last_row = fp;
    tj.node(.{
        .kind = "playbook",
        .items = items.len,
        .user_items = countOf(items, .user),
        .learned_items = countOf(items, .learned),
        .ids = ids,
        .t = tj.elapsedMs(),
    });
}

test {
    _ = @import("playbook_tests.zig");
    _ = @import("issue_789_constraint_tests.zig");
    _ = @import("playbook_pick.zig");
}