graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
Python
//! Tests for the #381/#383 playbook substrate, its injection block, its
//! capture surfaces, and the #383 reflector's reply parsing. Reached through
//! the `test { _ = @import(...) }` hook at the bottom of playbook.zig.
//!
//! Everything that touches the ledger FILE goes through a real
//! createFile/read round trip in a scratch cwd rather than a hand-built
//! string: the whole claim of #381 is that a constraint survives a process
//! boundary, and a test that never serializes cannot show that.
const std = @import("std");
const Io = std.Io;
const playbook = @import("playbook.zig");
const reflect = @import("playbook_reflect.zig");
const glue = @import("playbook_glue.zig");
const prompts = @import("prompts.zig");
const Agent = @import("agent.zig").Agent;
/// Run `body` with the process cwd moved into a fresh scratch directory, so
/// the real `.graff/playbook.jsonl` path is exercised without touching the
/// repo checkout. Same fchdir approach agent_eval_tests.zig uses, and for the
/// same reason: the store takes no Dir parameter.
fn inScratch(comptime body: fn (Io, std.mem.Allocator) anyerror!void) !void {
if (@import("builtin").os.tag == .windows) return;
const saved_inject = playbook.g_root_inject;
defer playbook.g_root_inject = saved_inject;
const io = std.testing.io;
var tmp = std.testing.tmpDir(.{});
defer tmp.cleanup();
var orig = try Io.Dir.cwd().openDir(io, ".", .{});
defer orig.close(io);
defer _ = std.posix.system.fchdir(orig.handle);
if (std.posix.system.fchdir(tmp.dir.handle) != 0) return error.ChdirFailed;
var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
defer arena_state.deinit();
try body(io, arena_state.allocator());
}
test "normalize: the dedupe key ignores case, punctuation and whitespace runs" {
var a: [playbook.max_text]u8 = undefined;
var b: [playbook.max_text]u8 = undefined;
try std.testing.expectEqualStrings("no emojis in code comments", playbook.normalize(&a, " No EMOJIS, in code-comments!! "));
try std.testing.expectEqualStrings(playbook.normalize(&a, "No dots."), playbook.normalize(&b, "no dots"));
try std.testing.expectEqualStrings("", playbook.normalize(&a, " --- "));
// Non-ASCII stays intact rather than shattering into per-byte tokens.
try std.testing.expectEqualStrings("café ohne zucker", playbook.normalize(&a, "Café — ohne Zucker"));
}
test "idFor: content-derived, so identity and dedupe are the same operation" {
var x: [11]u8 = undefined;
var y: [11]u8 = undefined;
try std.testing.expectEqualStrings(playbook.idFor(&x, "no scroll hints"), playbook.idFor(&y, " No, Scroll Hints! "));
try std.testing.expect(!std.mem.eql(u8, playbook.idFor(&x, "no scroll hints"), playbook.idFor(&y, "no progress dots")));
try std.testing.expect(std.mem.startsWith(u8, playbook.idFor(&x, "anything at all"), "pb-"));
try std.testing.expectEqual(@as(usize, 11), playbook.idFor(&x, "anything at all").len);
}
test "store round trip: add/dedupe/retire through the real .graff/playbook.jsonl file format" {
try inScratch(struct {
fn body(io: Io, arena: std.mem.Allocator) !void {
try std.testing.expectEqual(@as(usize, 0), playbook.load(io, arena).len);
const first = playbook.add(io, arena, "never use emojis in code comments", .user, "user:1");
try std.testing.expect(first.ok);
const learned = playbook.add(io, arena, "prefer codedb outline before read on files over 300 lines", .learned, "run:abc123");
try std.testing.expect(learned.ok); // reflector callers strip list markers before storage
// Read back through the real serializer + parser, not a fixture.
const items = playbook.load(io, arena);
try std.testing.expectEqual(@as(usize, 2), items.len);
try std.testing.expectEqualStrings("never use emojis in code comments", items[0].text);
try std.testing.expectEqual(playbook.Source.user, items[0].source);
try std.testing.expectEqualStrings("user:1", items[0].provenance);
try std.testing.expect(items[0].created_at > 0);
try std.testing.expectEqualStrings("prefer codedb outline before read on files over 300 lines", items[1].text);
try std.testing.expectEqual(playbook.Source.learned, items[1].source);
try std.testing.expectEqualStrings("run:abc123", items[1].provenance);
// Normalization still derives identity, but a punctuation/case
// variant cannot claim its different exact text was persisted.
const collision = playbook.add(io, arena, "Never use emojis in CODE comments.", .user, "user:2");
try std.testing.expect(!collision.ok);
try std.testing.expectEqualStrings(first.id, collision.id);
try std.testing.expect(std.mem.indexOf(u8, collision.reason, "collision") != null);
try std.testing.expectEqual(@as(usize, 2), playbook.load(io, arena).len);
const dupe = playbook.add(io, arena, "never use emojis in code comments", .user, "user:2");
try std.testing.expect(!dupe.ok);
try std.testing.expect(std.mem.indexOf(u8, dupe.reason, "already recorded") != null);
// An empty/punctuation-only constraint is refused rather than
// stored as an item that injects a bare "- ".
try std.testing.expect(!playbook.add(io, arena, " *** ", .user, "user:3").ok);
// Retire is a TOMBSTONE: the add record stays on disk, and the
// file only ever grows.
const before = (try Io.Dir.cwd().readFileAlloc(io, playbook.path, arena, .limited(1 << 20))).len;
try std.testing.expectEqual(playbook.Retire.ok, playbook.retire(io, arena, first.id));
const after = try Io.Dir.cwd().readFileAlloc(io, playbook.path, arena, .limited(1 << 20));
try std.testing.expect(after.len > before);
try std.testing.expect(std.mem.indexOf(u8, after, "never use emojis in code comments") != null); // history intact
const live = playbook.load(io, arena);
try std.testing.expectEqual(@as(usize, 1), live.len);
try std.testing.expectEqual(playbook.Source.learned, live[0].source);
// Retiring an unknown id writes nothing and says so.
try std.testing.expectEqual(playbook.Retire.unknown, playbook.retire(io, arena, "pb-deadbeef"));
// Re-adding a retired item works: the later op wins.
try std.testing.expect(playbook.add(io, arena, "never use emojis in code comments", .user, "user:4").ok);
try std.testing.expectEqual(@as(usize, 2), playbook.load(io, arena).len);
}
}.body);
}
test "parse: a torn tail or a junk line costs at most its own record" {
var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
defer arena_state.deinit();
const arena = arena_state.allocator();
const items = playbook.parse(arena,
\\{"v":1,"op":"add","id":"pb-00000001","text":"first","source":"user"}
\\not json at all
\\{"v":1,"op":"add","id":"pb-00000002","text":"second","source":"learned"}
\\
\\{"v":1,"op":"add","id":"pb-000000
);
try std.testing.expectEqual(@as(usize, 2), items.len);
try std.testing.expectEqualStrings("first", items[0].text);
try std.testing.expectEqualStrings("second", items[1].text);
}
test "blockFrom: user before learned, both headed, and nothing at all when empty" {
var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
defer arena_state.deinit();
const arena = arena_state.allocator();
try std.testing.expectEqualStrings("", playbook.blockFrom(arena, &.{}));
const items = [_]playbook.Item{
.{ .id = "pb-1", .text = "learned first in file order", .source = .learned },
.{ .id = "pb-2", .text = "no navigation dots", .source = .user },
.{ .id = "pb-3", .text = "no scroll hints", .source = .user },
};
const block = playbook.blockFrom(arena, &items);
const user_at = std.mem.indexOf(u8, block, playbook.user_header).?;
const learned_at = std.mem.indexOf(u8, block, playbook.learned_header).?;
try std.testing.expect(user_at < learned_at); // user ALWAYS outranks learned
// Newest-first within a section: the most recent "no" leads.
try std.testing.expect(std.mem.indexOf(u8, block, "- no scroll hints").? < std.mem.indexOf(u8, block, "- no navigation dots").?);
try std.testing.expect(std.mem.indexOf(u8, block, "- learned first in file order") != null);
try std.testing.expect(std.mem.indexOf(u8, block, "omitted") == null); // nothing was cut
// A learned-only ledger must not print an empty HARD CONSTRAINTS header.
const learned_only = playbook.blockFrom(arena, items[0..1]);
try std.testing.expect(std.mem.indexOf(u8, learned_only, playbook.user_header) == null);
try std.testing.expect(std.mem.startsWith(u8, learned_only, playbook.learned_header));
}
test "blockFrom: the item cap truncates newest-first and SAYS it truncated" {
var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
defer arena_state.deinit();
const arena = arena_state.allocator();
const n = playbook.user_block_items + 5;
const items = try arena.alloc(playbook.Item, n);
for (items, 0..) |*item, i| item.* = .{
.id = "pb-x",
.text = std.fmt.allocPrint(arena, "constraint number {d}", .{i}) catch unreachable,
.source = .user,
};
const block = playbook.blockFrom(arena, items);
// Every bullet is preceded by a newline (the header's, or the previous
// bullet's), so this counts them exactly.
try std.testing.expectEqual(playbook.user_block_items, std.mem.count(u8, block, "\n- "));
// Silent truncation would be a lie: a worker told "these are the
// constraints" has to know when it was told only some of them.
try std.testing.expect(std.mem.indexOf(u8, block, "5 older item(s) omitted") != null);
try std.testing.expect(std.mem.indexOf(u8, block, playbook.path) != null);
// The newest survived and the oldest was the one cut.
try std.testing.expect(std.mem.indexOf(u8, block, "constraint number 34") != null);
try std.testing.expect(std.mem.indexOf(u8, block, "constraint number 0\n") == null);
}
test "blockFrom: the byte cap bounds the block even with one absurd item each" {
var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
defer arena_state.deinit();
const arena = arena_state.allocator();
const long = try arena.alloc(u8, playbook.max_text);
@memset(long, 'x');
const items = try arena.alloc(playbook.Item, 40);
for (items, 0..) |*item, i| item.* = .{ .id = "pb-x", .text = long, .source = if (i % 2 == 0) .user else .learned };
const block = playbook.blockFrom(arena, items);
try std.testing.expect(block.len < playbook.user_block_bytes + playbook.learned_block_bytes + 512);
}
test "rideBrief: identity on an empty ledger, block-prefixed once there is one" {
try inScratch(struct {
fn body(io: Io, arena: std.mem.Allocator) !void {
try std.testing.expectEqualStrings("do the thing", playbook.rideBrief(io, arena, "do the thing"));
try std.testing.expect(playbook.add(io, arena, "no navigation dots", .user, "user:1").ok);
const brief = playbook.rideBrief(io, arena, "do the thing");
try std.testing.expect(std.mem.startsWith(u8, brief, playbook.user_header));
try std.testing.expect(std.mem.indexOf(u8, brief, "- no navigation dots") != null);
try std.testing.expect(std.mem.endsWith(u8, brief, "do the thing"));
}
}.body);
}
test "composeRoot: gated off until armed, then appends the same block to the root's base" {
try inScratch(struct {
fn body(io: Io, arena: std.mem.Allocator) !void {
try std.testing.expect(playbook.add(io, arena, "no scroll hints", .user, "user:1").ok);
const composed = playbook.composeRoot(io, arena, "BASE");
try std.testing.expect(std.mem.startsWith(u8, composed, "BASE"));
try std.testing.expect(std.mem.indexOf(u8, composed, "- no scroll hints") != null);
}
}.body);
}
test "the learned cap refuses rather than evicting, and never touches user items" {
try inScratch(struct {
fn body(io: Io, arena: std.mem.Allocator) !void {
for (0..playbook.max_learned) |i| {
const text = try std.fmt.allocPrint(arena, "learned insight number {d}", .{i});
try std.testing.expect(playbook.add(io, arena, text, .learned, "run:x").ok);
}
const over = playbook.add(io, arena, "one insight too many", .learned, "run:x");
try std.testing.expect(!over.ok);
try std.testing.expect(std.mem.indexOf(u8, over.reason, "cap") != null);
// v1 refuses; it does NOT evict, because choosing a victim needs
// per-item fitness and that attribution is follow-up scope.
try std.testing.expectEqual(playbook.max_learned, playbook.countOf(playbook.load(io, arena), .learned));
// A user constraint still lands: the learned ceiling is not a
// ceiling on the user's own rules.
try std.testing.expect(playbook.add(io, arena, "never ship on a Friday", .user, "user:1").ok);
}
}.body);
}
test "reflector (#383): parses at most 3 bullets out of a canned reply, no live call" {
var out: [reflect.max_candidates][]const u8 = undefined;
const typical =
\\Here are the durable lessons from this run:
\\- the zig sources are capped at 600 lines; split before adding a module
\\* regenerate the SDKs after any tool-schema change or CI fails
\\1. run zig fmt on touched files before committing
\\- a fourth bullet that must not be taken
\\
\\Hope that helps!
;
const got = reflect.parseCandidates(&out, typical);
try std.testing.expectEqual(@as(usize, 3), got.len);
try std.testing.expectEqualStrings("the zig sources are capped at 600 lines; split before adding a module", got[0]);
try std.testing.expectEqualStrings("regenerate the SDKs after any tool-schema change or CI fails", got[1]);
try std.testing.expectEqualStrings("run zig fmt on touched files before committing", got[2]);
// Prose-only replies yield nothing: a preamble curated into the playbook
// would be injected into every future brief forever, so a false positive
// costs far more than a missed insight.
try std.testing.expectEqual(@as(usize, 0), reflect.parseCandidates(&out, "I could not find anything durable worth recording.").len);
try std.testing.expectEqual(@as(usize, 0), reflect.parseCandidates(&out, "none").len);
try std.testing.expectEqual(@as(usize, 0), reflect.parseCandidates(&out, "- none").len);
try std.testing.expectEqual(@as(usize, 0), reflect.parseCandidates(&out, "- ok").len); // too short to be an insight
try std.testing.expectEqual(@as(usize, 0), reflect.parseCandidates(&out, "").len);
// An oversized bullet is capped, not dropped.
var big: [playbook.max_text * 2]u8 = undefined;
@memset(&big, 'y');
big[0] = '-';
big[1] = ' ';
const capped = reflect.parseCandidates(&out, &big);
try std.testing.expectEqual(@as(usize, 1), capped.len);
try std.testing.expectEqual(playbook.max_text, capped[0].len);
}
test "reflector curation is deterministic: the same candidates twice add nothing the second time" {
try inScratch(struct {
fn body(io: Io, arena: std.mem.Allocator) !void {
var out: [reflect.max_candidates][]const u8 = undefined;
const reply = "- regenerate the SDKs after any tool-schema change\n- zig sources are capped at 600 lines";
for (0..2) |_| {
for (reflect.parseCandidates(&out, reply)) |text| _ = playbook.add(io, arena, text, .learned, "run:abc");
}
const items = playbook.load(io, arena);
try std.testing.expectEqual(@as(usize, 2), items.len);
for (items) |item| {
try std.testing.expectEqual(playbook.Source.learned, item.source);
try std.testing.expectEqualStrings("run:abc", item.provenance); // provenance is the minting run
}
}
}.body);
}
/// A root Agent with just enough wired up for the capture surfaces: real io
/// (they touch the ledger file), a captured writer, and undefined provider/
/// client, which neither surface goes near.
fn stubRoot(gpa: std.mem.Allocator, arena: std.mem.Allocator, out: *Io.Writer) Agent {
return .{
.gpa = gpa,
.arena = arena,
.io = std.testing.io,
.client = undefined,
.provider = undefined,
.messages = undefined,
.sub = false,
.label = "test",
.out = out,
.session_name = "", // #410: a scratch stub has no durable session, so setRootSystemPrompts stays a pure string funnel here
};
}
test "/never (#381): bare lists, text adds, rm retires — and a non-/never line falls through" {
try inScratch(struct {
fn body(io: Io, arena: std.mem.Allocator) !void {
var aw: Io.Writer.Allocating = .init(arena);
var root = stubRoot(std.testing.allocator, arena, &aw.writer);
// Unrelated lines are NOT claimed, including the prefix trap.
try std.testing.expect(!try glue.command(&root, arena, "/models", &aw.writer));
try std.testing.expect(!try glue.command(&root, arena, "/neverending story", &aw.writer));
try std.testing.expect(try glue.command(&root, arena, "/never", &aw.writer));
try std.testing.expect(std.mem.indexOf(u8, aw.writer.buffered(), "playbook empty") != null);
aw.clearRetainingCapacity();
try std.testing.expect(try glue.command(&root, arena, "/never no navigation dots or scroll hints", &aw.writer));
const added = aw.writer.buffered();
// Duped: the writer below is cleared and rewritten, and a slice
// into its retained buffer would silently become another message.
const id = try arena.dupe(u8, added[std.mem.indexOf(u8, added, "pb-").?..][0..11]);
const items = playbook.load(io, arena);
try std.testing.expectEqual(@as(usize, 1), items.len);
try std.testing.expectEqualStrings("no navigation dots or scroll hints", items[0].text);
try std.testing.expectEqual(playbook.Source.user, items[0].source);
try std.testing.expectEqual(playbook.Scope.project, items[0].scope);
try std.testing.expect(std.mem.startsWith(u8, items[0].provenance, "user:"));
// The alias is the same command, and it dedupes against the same ledger.
aw.clearRetainingCapacity();
try std.testing.expect(try glue.command(&root, arena, "/constraint No navigation dots, or scroll hints!", &aw.writer));
try std.testing.expect(std.mem.indexOf(u8, aw.writer.buffered(), "not recorded") != null);
try std.testing.expectEqual(@as(usize, 1), playbook.load(io, arena).len);
aw.clearRetainingCapacity();
try std.testing.expect(try glue.command(&root, arena, "/never", &aw.writer));
try std.testing.expect(std.mem.indexOf(u8, aw.writer.buffered(), "no navigation dots") != null);
try std.testing.expect(std.mem.indexOf(u8, aw.writer.buffered(), "scope=project") != null);
try std.testing.expect(std.mem.indexOf(u8, aw.writer.buffered(), "origin=user:") != null);
aw.clearRetainingCapacity();
try std.testing.expect(try glue.command(&root, arena, "/never rm pb-deadbeef", &aw.writer));
try std.testing.expect(std.mem.indexOf(u8, aw.writer.buffered(), "no live playbook item") != null);
aw.clearRetainingCapacity();
const rm = try std.fmt.allocPrint(arena, "/never rm {s}", .{id});
try std.testing.expect(try glue.command(&root, arena, rm, &aw.writer));
try std.testing.expect(std.mem.indexOf(u8, aw.writer.buffered(), "retired") != null);
try std.testing.expectEqual(@as(usize, 0), playbook.load(io, arena).len);
}
}.body);
}
test "/never rm matches unique text and applyUserOverride honors an explicit forget (#638)" {
try inScratch(struct {
fn body(io: Io, arena: std.mem.Allocator) !void {
var aw: Io.Writer.Allocating = .init(arena);
var root = stubRoot(std.testing.allocator, arena, &aw.writer);
try std.testing.expect(try glue.command(&root, arena, "/never no navigation dots or scroll hints", &aw.writer));
try std.testing.expectEqual(@as(usize, 1), playbook.load(io, arena).len);
aw.clearRetainingCapacity();
try std.testing.expect(try glue.command(&root, arena, "/never rm navigation dots", &aw.writer));
try std.testing.expect(std.mem.indexOf(u8, aw.writer.buffered(), "retired") != null);
try std.testing.expectEqual(@as(usize, 0), playbook.load(io, arena).len);
try std.testing.expect(try glue.command(&root, arena, "/never never use emojis in comments", &aw.writer));
try std.testing.expectEqual(@as(usize, 0), glue.applyUserOverride(&root, arena, "please add a comment"));
try std.testing.expectEqual(@as(usize, 1), playbook.load(io, arena).len);
try std.testing.expectEqual(@as(usize, 1), glue.applyUserOverride(&root, arena, "forget the standing rule: never use emojis in comments"));
try std.testing.expectEqual(@as(usize, 0), playbook.load(io, arena).len);
}
}.body);
}
test "/never rm without a needle does not add or retire (#644)" {
try inScratch(struct {
fn body(io: Io, arena: std.mem.Allocator) !void {
var aw: Io.Writer.Allocating = .init(arena);
var root = stubRoot(std.testing.allocator, arena, &aw.writer);
try std.testing.expect(try glue.command(&root, arena, "/never no navigation dots or scroll hints", &aw.writer));
try std.testing.expectEqual(@as(usize, 1), playbook.load(io, arena).len);
const id = try arena.dupe(u8, playbook.load(io, arena)[0].id);
aw.clearRetainingCapacity();
try std.testing.expect(try glue.command(&root, arena, "/never rm", &aw.writer));
const bare = aw.writer.buffered();
try std.testing.expect(std.mem.indexOf(u8, bare, "rm needs an id") != null);
try std.testing.expect(std.mem.indexOf(u8, bare, "retired") == null);
const after_bare = playbook.load(io, arena);
try std.testing.expectEqual(@as(usize, 1), after_bare.len);
try std.testing.expectEqualStrings(id, after_bare[0].id);
try std.testing.expectEqualStrings("no navigation dots or scroll hints", after_bare[0].text);
const disk = try Io.Dir.cwd().readFileAlloc(io, playbook.path, arena, .limited(1 << 20));
try std.testing.expect(std.mem.indexOf(u8, disk, "\"op\":\"retire\"") == null);
aw.clearRetainingCapacity();
try std.testing.expect(try glue.command(&root, arena, "/never remove", &aw.writer));
try std.testing.expectEqual(@as(usize, 1), playbook.load(io, arena).len);
try std.testing.expect(std.mem.indexOf(u8, aw.writer.buffered(), "recorded") == null);
aw.clearRetainingCapacity();
const tabbed = try std.fmt.allocPrint(arena, "/never rm\t{s}", .{id});
try std.testing.expect(try glue.command(&root, arena, tabbed, &aw.writer));
try std.testing.expect(std.mem.indexOf(u8, aw.writer.buffered(), "retired") != null);
try std.testing.expectEqual(@as(usize, 0), playbook.load(io, arena).len);
const after = try Io.Dir.cwd().readFileAlloc(io, playbook.path, arena, .limited(1 << 20));
try std.testing.expect(std.mem.indexOf(u8, after, "\"op\":\"retire\"") != null);
}
}.body);
}
test "/never rm emits a privacy-safe never_retire trace (#644)" {
try inScratch(struct {
fn body(io: Io, arena: std.mem.Allocator) !void {
var taw: Io.Writer.Allocating = .init(arena);
var tracer: @import("trace.zig").Tracer = .{
.io = io,
.gpa = std.testing.allocator,
.out = &taw.writer,
.start = Io.Timestamp.now(io, .awake),
.identity = .{ .run_id = "t", .pid = 1, .session_id = "s" },
};
var aw: Io.Writer.Allocating = .init(arena);
var root = stubRoot(std.testing.allocator, arena, &aw.writer);
root.tracer = &tracer;
try std.testing.expect(try glue.command(&root, arena, "/never no scroll hints", &aw.writer));
const id = try arena.dupe(u8, playbook.load(io, arena)[0].id);
taw.clearRetainingCapacity();
try std.testing.expect(try glue.command(&root, arena, "/never rm pb-deadbeef", &aw.writer));
const miss = taw.writer.buffered();
try std.testing.expect(std.mem.indexOf(u8, miss, "\"ev\":\"never_retire\"") != null);
try std.testing.expect(std.mem.indexOf(u8, miss, "\"ok\":false") != null);
try std.testing.expect(std.mem.indexOf(u8, miss, "scroll") == null);
taw.clearRetainingCapacity();
const rm = try std.fmt.allocPrint(arena, "/never rm {s}", .{id});
try std.testing.expect(try glue.command(&root, arena, rm, &aw.writer));
const hit = taw.writer.buffered();
try std.testing.expect(std.mem.indexOf(u8, hit, "\"ev\":\"never_retire\"") != null);
try std.testing.expect(std.mem.indexOf(u8, hit, id) != null);
try std.testing.expect(std.mem.indexOf(u8, hit, "\"ok\":true") != null);
try std.testing.expect(std.mem.indexOf(u8, hit, "scroll") == null);
try std.testing.expectEqual(@as(usize, 0), playbook.load(io, arena).len);
}
}.body);
}
test "note_constraint (#381): appends user items only, is idempotent, and can never retire one" {
try inScratch(struct {
fn body(io: Io, arena: std.mem.Allocator) !void {
var aw: Io.Writer.Allocating = .init(arena);
var root = stubRoot(std.testing.allocator, arena, &aw.writer);
root.named_work_task = "never use emojis in code comments";
const call = try std.json.parseFromSliceLeaky(std.json.Value, arena, "{\"text\":\"never use emojis in code comments\",\"scope\":\"project\"}", .{});
const first = glue.noteConstraint(&root, call);
try std.testing.expect(!first.is_error);
try std.testing.expect(std.mem.indexOf(u8, first.text, "recorded project constraint pb-") != null);
try std.testing.expect(std.mem.indexOf(u8, first.text, "Undo without knowing the id") != null);
const items = playbook.load(io, arena);
try std.testing.expectEqual(@as(usize, 1), items.len);
try std.testing.expectEqual(playbook.Source.user, items[0].source); // NEVER .learned
try std.testing.expectEqual(playbook.Scope.project, items[0].scope);
// A repeat is the desired end state, not a failure: reporting it as
// an error would push the model into retrying a correct ledger.
const again = glue.noteConstraint(&root, call);
try std.testing.expect(!again.is_error);
try std.testing.expectEqual(@as(usize, 1), playbook.load(io, arena).len);
// Simulate a stale prefix: duplicate calls must refresh in this turn.
root.sys_normal = "stale";
const reconciled = glue.noteConstraint(&root, call);
try std.testing.expect(!reconciled.is_error);
try std.testing.expect(std.mem.indexOf(u8, reconciled.text, "not secret-safety") != null);
for ([_][]const u8{ root.sys_normal, root.sys_strict, root.sys_ultra, root.sys_ultra_strict }) |variant|
try std.testing.expect(std.mem.indexOf(u8, variant, items[0].text) != null);
const brief = playbook.rideBrief(io, arena, "worker task");
try std.testing.expect(std.mem.indexOf(u8, brief, items[0].text) != null);
// Empty/blank text is refused rather than stored.
const blank = try std.json.parseFromSliceLeaky(std.json.Value, arena, "{\"text\":\" \",\"scope\":\"project\"}", .{});
try std.testing.expect(glue.noteConstraint(&root, blank).is_error);
const missing = try std.json.parseFromSliceLeaky(std.json.Value, arena, "{}", .{});
try std.testing.expect(glue.noteConstraint(&root, missing).is_error);
// Local or ambiguous scope and model-authored paraphrases fail
// closed before the project ledger changes.
const before_rejected = playbook.load(io, arena).len;
const local = try std.json.parseFromSliceLeaky(std.json.Value, arena, "{\"text\":\"never use emojis in code comments\",\"scope\":\"task\"}", .{});
try std.testing.expect(glue.noteConstraint(&root, local).is_error);
const paraphrase = try std.json.parseFromSliceLeaky(std.json.Value, arena, "{\"text\":\"never use emojis anywhere\",\"scope\":\"project\"}", .{});
try std.testing.expect(glue.noteConstraint(&root, paraphrase).is_error);
try std.testing.expectEqual(before_rejected, playbook.load(io, arena).len);
// The append-only contract, structurally: whatever the model puts
// in `text`, the ledger only ever grows and the item stays live.
// There is no argument shape that reaches retire from here.
for ([_][]const u8{ "{\"text\":\"retire pb-00000001\",\"scope\":\"project\"}", "{\"text\":\"rm all\",\"scope\":\"project\"}", "{\"op\":\"retire\",\"id\":\"pb-00000001\",\"text\":\"x\",\"scope\":\"project\"}" }) |raw| {
const before = playbook.load(io, arena).len;
_ = glue.noteConstraint(&root, try std.json.parseFromSliceLeaky(std.json.Value, arena, raw, .{}));
try std.testing.expect(playbook.load(io, arena).len >= before);
}
try std.testing.expect(playbook.find(playbook.load(io, arena), items[0].id) != null); // the original survived every one
}
}.body);
}
test "refreshRoot (#381): a constraint recorded mid-session reaches the ROOT's own prompt, all four variants" {
try inScratch(struct {
fn body(io: Io, arena: std.mem.Allocator) !void {
_ = io; // the ledger is reached through the agent's own io here
const saved = playbook.g_root_inject;
defer playbook.g_root_inject = saved;
var aw: Io.Writer.Allocating = .init(arena);
var root = stubRoot(std.testing.allocator, arena, &aw.writer);
try prompts.setRootSystemPrompts(&root, "ROOT-BASE", arena);
try std.testing.expectEqualStrings("ROOT-BASE", root.sys_base);
try std.testing.expect(std.mem.indexOf(u8, root.sys_normal, "\"recorded_user_constraints\":[]") != null); // empty ledger explicitly denies invented recordings
root.codex_prev_id = try std.testing.allocator.dupe(u8, "stale-server-instructions");
root.named_work_task = "no scroll hints";
const result = glue.noteConstraint(&root, try std.json.parseFromSliceLeaky(std.json.Value, arena, "{\"text\":\"no scroll hints\",\"scope\":\"project\"}", .{}));
try std.testing.expect(std.mem.indexOf(u8, result.text, "same turn") != null);
try std.testing.expect(root.codex_prev_id == null);
// noteConstraint refreshed it: no restart, no re-login, next request.
for ([_][]const u8{ root.sys_normal, root.sys_strict, root.sys_ultra, root.sys_ultra_strict }) |v| {
try std.testing.expect(std.mem.indexOf(u8, v, "ROOT-BASE") != null);
try std.testing.expect(std.mem.indexOf(u8, v, "- no scroll hints") != null);
}
// The BASE is remembered unpolluted, so the next refresh composes
// from it rather than stacking a second block onto the first.
try std.testing.expectEqualStrings("ROOT-BASE", root.sys_base);
root.named_work_task = "no progress dots";
_ = glue.noteConstraint(&root, try std.json.parseFromSliceLeaky(std.json.Value, arena, "{\"text\":\"no progress dots\",\"scope\":\"project\"}", .{}));
try std.testing.expectEqual(@as(usize, 1), std.mem.count(u8, root.sys_normal, playbook.user_header));
try std.testing.expectEqual(@as(usize, 1), std.mem.count(u8, root.sys_normal, "ROOT-BASE"));
try std.testing.expect(std.mem.indexOf(u8, root.sys_normal, "- no progress dots") != null);
// And a persona swap through the ordinary funnel keeps the block.
try prompts.setSystemPrompts(&root, "PERSONA-BASE", arena);
try std.testing.expect(std.mem.indexOf(u8, root.sys_normal, "PERSONA-BASE") != null);
try std.testing.expect(std.mem.indexOf(u8, root.sys_normal, "- no progress dots") != null);
}
}.body);
}
test "recorded constraint authority is structural, escaped, and excludes learned and retired items (#738)" {
try inScratch(struct {
fn body(io: Io, arena: std.mem.Allocator) !void {
const empty = playbook.composeRoot(io, arena, "BASE");
try std.testing.expect(std.mem.indexOf(u8, empty, "\"recorded_user_constraints\":[]") != null);
try std.testing.expect(playbook.add(io, arena, "advisory only", .learned, "run:1").ok);
const added = playbook.add(io, arena, "no \"trailers\"\nplease", .user, "user:1");
try std.testing.expect(added.ok);
const encoded = try playbook.recordedState(arena, playbook.load(io, arena));
const state = try std.json.parseFromSliceLeaky(std.json.Value, arena, encoded, .{});
const records = state.object.get("recorded_user_constraints").?.array.items;
try std.testing.expectEqual(@as(usize, 1), records.len);
try std.testing.expectEqualStrings(added.id, records[0].object.get("id").?.string);
try std.testing.expectEqualStrings("no \"trailers\"\nplease", records[0].object.get("text").?.string);
try std.testing.expectEqualStrings("project", records[0].object.get("scope").?.string);
try std.testing.expect(records[0].object.get("created_at").?.integer > 0);
try std.testing.expectEqualStrings("user:1", records[0].object.get("provenance").?.string);
try std.testing.expectEqual(playbook.Retire.ok, playbook.retire(io, arena, added.id));
try std.testing.expectEqualStrings("{\"recorded_user_constraints\":[]}", try playbook.recordedState(arena, playbook.load(io, arena)));
}
}.body);
}
test "idList: the kind:\"playbook\" row's id column is the join key for later attribution" {
var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
defer arena_state.deinit();
const arena = arena_state.allocator();
try std.testing.expectEqualStrings("", playbook.idList(arena, &.{}));
try std.testing.expectEqualStrings("pb-1,pb-2", playbook.idList(arena, &.{
.{ .id = "pb-1", .text = "a", .source = .user },
.{ .id = "pb-2", .text = "b", .source = .learned },
}));
}