zig-abstractions

# Zig Abstractions ## Operating Mode Use this skill to keep Zig APIs concrete until abstraction earns its cost. First verify the project version: ```bash zig version test -f build.zig.zon && sed -n '1,120p' build.zig.zon ``` Default to the repo-pinned Zig version. As of 2026-05-13, upstream stable is Zig `0.16.0`, but Orca-style repos may still target `0.15.2`; mark 0.16-only patterns as migration notes. ## Decision Rule Prefer concrete structs and functions first. Add an abstraction only when at least one is true: - There are two or more real call sites with the same stable contract. - Tests need to substitute behavior at a boundary that cannot be tested cleanly otherwise. - The abstraction removes meaningful duplication without hiding allocation, errors, ownership, or control flow. - The public API is more stable with a small explicit contract than with leaking internal implementation types. If a proposed abstraction mainly creates names like `Manager`, `Context`, `Value`, `Data`, or `utils`, simplify it. ## Comptime Generics - Use `comptime T: type` for type-parametric algorithms and type factories. - Keep constraints close to use sites with `@hasDecl`, `@hasField`, `@typeInfo`, and clear `@compileError` messages. - Prefer a small generic helper over a trait framework when the helper has one job. - Avoid exporting broad comptime-heavy APIs unless compile-time configuration is the product value. - Test at least two concrete type instantiations when behavior depends on type shape. Zig generics are compile-time duck typing: the actual contract is the operations the generic code performs. Document non-obvious expected declarations in comments or tests. ## Errors And Optionals - Use `?T` for absence and `E!T` for failure. - Use explicit error sets at public boundaries when callers, function pointers, or stable tests need predictable contracts. - Use inferred error sets internally when they reduce boilerplate and do not leak into public API. - Prefer `try`, `if (opt) |value|`, `orelse`, and `catch |err| switch` over sentinel values and unchecked unwraps. - Keep error names domain-specific enough for callers to act on them. ## Tagged Unions - Use `union(enum)` for closed variants: commands, policy decisions, parser results, state machines, and protocol messages. - Require exhaustive `switch` handling when adding variants. - Store payload ownership explicitly. A union variant carrying an owned slice still needs a clear deinit path. - Avoid stringly typed variants when schema/API stability matters. ## Interfaces And Vtables - Prefer comptime generics when implementation can be selected statically and call sites are few. - Use explicit structs with function pointers only when runtime polymorphism is necessary. - Keep vtable-like contracts small. Include userdata/lifetime/allocator ownership in the type, not in hidden global state. - Avoid mixing dynamic dispatch and hidden allocation in the same boundary. - In Zig `0.16.0`, `std.Io` is the standard-library direction for interface-style I/O. Do not backport `std.Io` examples into `0.15.x` code unless the task is a migration. ## Allocation And Ownership - Make allocator parameters explicit at the boundary that may allocate. - Prefer caller-owned buffers for hot paths, parsers, and security-sensitive code. - Document returned memory as owned or borrowed. - Keep allocation out of abstractions whose names imply pure formatting, validation, classification, or lookup. - Make deinit responsibilities testable. ## API Boundary Checklist - Public types are small, named for the domain, and do not expose avoidable stdlib version churn. - Generic parameters are minimal and have obvious purpose. - Allocation, I/O, time, randomness, filesystem, and process dependencies are explicit. - Error sets are stable where callers need to switch on them. - Ownership of slices, handles, iterators, and parsed data is visible from function names, docs, or tests. - The abstraction can be tested without duplicating implementation details. ## Verification For each new abstraction, add tests for: - One normal concrete implementation. - One alternate implementation or type shape if the abstraction claims generality. - One invalid input, invalid shape, or error-path case. - One ownership or lifetime boundary when allocation is involved. Then run the repo lane: ```bash zig build test --summary all ``` ## 0.15 to 0.16 Drift - `std.Io` introduces official interface-style I/O patterns in `0.16.0`. - `GenericReader`, `AnyReader`, and `FixedBufferStream` were removed in the 0.16 I/O migration. - `@Type` was replaced by specific type-creating builtins; broad type-reification abstractions need review. - Container APIs continue moving toward unmanaged forms; do not hide allocator ownership behind compatibility wrappers without tests. ## Source Refresh Refresh primary sources before version-sensitive guidance: - `https://ziglang.org/documentation/0.15.2/` - `https://ziglang.org/documentation/0.16.0/` - `https://ziglang.org/download/0.16.0/release-notes.html` - `https://ziglang.org/learn/overview/`