szn

Bug 529 — over-broad @hasField claim in AGENTS.md

529. The dual-toolchain port’s own documentation rule was false

Severity: LOW (correctness) Status: ✅ FIXED Files: AGENTS.md, src/client/connect.zig:30, src/server/socket.zig:60, src/server/socket.zig:93, src/server/server.zig:3826

Problem

The commit that added Zig 0.17 support also added a two-rule policy to AGENTS.md, whose second rule read:

Comptime @hasField gates live only in build.zig; runtime-visible shims live only in src/compat.zig. Never scatter @hasField checks through the rest of the source.

The second clause is fine; the first is an absolute claim that the tree contradicts. Four @hasField sites exist outside build.zig:

Site Guard
src/client/connect.zig:30 @hasField(c.sockaddr.un, "len")
src/server/socket.zig:60 @hasField(c.sockaddr.un, "len")
src/server/socket.zig:93 @hasField(c.sockaddr.un, "len")
src/server/server.zig:3826 @hasField(std.c.sockaddr.un, "len")

These are OS-ABI gates (the sockaddr_un length field is named differently on Linux vs the BSDs), not Zig-version gates. So the code is correct and the new rule was over-broad — the failure mode of a rule written to describe one change without surveying the existing tree.

This matters because AGENTS.md is the house style document an agent or contributor is told to follow; a rule that is visibly violated on four lines teaches readers to ignore the rules.

Resolution

Reworded to scope the claim to version gates and to name the platform gates explicitly so a future reader does not “fix” them:

Confine version branches. Zig-version gates live only in build.zig (comptime @hasField); runtime-visible shims live only in src/compat.zig. Never scatter version checks through the rest of the source. (The @hasField(c.sockaddr.un, "len") checks in client/connect.zig, server/socket.zig and server/server.zig are pre-existing OS-ABI gates, not version gates — leave them where they are.)

Bugs #507 (“AGENTS.md and architecture.md assert ‘No global state’ while eleven mutable module globals exist”) and #189 (“Protocol structs are not packed despite AGENTS.md claiming so”) are the same class: a normative document drifting from the tree it describes. Bug #508 was a stale README claim.