the Zig work surface
the semantic failure family
and
the cross-cutting engineering contract
The skill is a router first and an expert reference system second.
A green build is not enough when the change trusts proof material, returns
borrowed data, mutates several owners, verifies hostile input, changes generated
or repository artifacts, relies on stale proof, or introduces work that can
grow, wait, retry, recurse, allocate, or fan out without an explicit bound.
Version and artifact-state pin
Assume Zig 0.16.0 only when the repository or user does not specify another
version.
Before version-sensitive work:
zig version
git rev-parse --show-toplevel
git rev-parse HEAD
git status --short
If the installed version differs from the claimed target, report:
VERSION_MISMATCH
Do not claim that commands validate a different Zig version. Record the
repository root, branch/head, dirty state, worktree, target, optimize mode, and
relevant build options before material proof.
The route binds artifact state, task surfaces, materiality, active families,
owner, counterexample, repair boundary, forbidden shortcuts, required proof,
family contracts, and the pre-edit mutation decision.
For material implementation or review, apply these priorities in order:
1. safety and semantic correctness
2. predictable performance and bounded resource use
3. developer experience and maintainability
These constraints are not a seventh semantic family. Apply them to every
selected route:
all work that can grow, wait, retry, allocate, recurse, or fan out
its numeric or structural bound and terminal failure
independent assertion pairs for safety-relevant invariants
programmer-error versus operating-error treatment
control-flow and function-growth decisions
a network/disk/memory/CPU sketch or a concrete non-applicability reason
narrow exceptions and their rationale
New or growing functions target at most 70 physical lines; changed lines target
at most 100 Unicode code points. Existing debt may shrink incrementally but
must not grow silently.
General Zig CLIs may allocate after startup when aggregate memory is bounded,
ownership is explicit, and allocation failure is handled. Long-lived services
and hot data planes should prefer startup allocation, fixed-capacity pools, and
bounded admission.
Semantic family 1 — claim binding
Trigger for fingerprints, receipts, certificates, proofs, evidence, refs,
cursors, manifests, checkpoints, replay records, attestations, and pass/fail
APIs.
Ask:
What exact authoritative bytes or facts does this claim bind?
What can a caller omit, substitute, reorder, zero, or forge while still passing?
Require the authoritative owner, canonical encoding, complete bound-field
inventory, caller-controlled or unbound fields, public/strongest-predicate
parity, and adversarial mutations of every claimed field.
Do not accept caller-supplied fingerprints as proof of caller-supplied objects.
Escaping runtime-owned slices must be duplicated into the returned owner or
carry or transfer the backing owner.
Never return data backed by temporary input, a soon-deinitialized arena or
report, moved staging state, a reallocating container, or a refreshable snapshot
without an explicit epoch.
Trigger when a fallible state transition performs any observable mutation
before later allocation, clone, append, persistence, publication, ownership
transfer, or event emission can fail.
Ask:
Can any later operation fail after the first observable mutation?
If so, is every owner and external effect restored exactly?
Prefer:
prepare all fallible data
-> commit one non-fallible state transition
-> publish effects after commit
Otherwise require rollback covering every owner and effect. Proof must compare
full observable pre-state and post-state at deterministic failure indices.
errdefer that frees memory but leaves ledgers, events, counters, refs,
journals, or state owners changed is not atomicity.
Trigger for parsers, decoders, binary formats, protocols, WASM, archives,
inspectors, validators, and passed() or verify() APIs.
Prove separately:
parser totality:
arbitrary bytes do not trap; lengths, counts, and varints terminate and stay bounded
semantic completeness:
the public predicate checks the exact promised property, actual values,
lower and upper bounds, final state or stack shape, and every relevant entity
Use fuzz or differential parsing and a semantic mutation matrix containing
malformed plus valid-but-semantically-invalid inputs.
The public predicate downstream code consumes must equal the strongest relevant
internal predicate.
Then inspect repository-specific contracts and run aggregate lint and build
proof. Do not hardcode one repository's registry filename as universal doctrine.
Final proof binds command and cwd, repository/head/dirty fingerprint, Zig
version, target/mode/options, dependencies/forks, generated artifacts,
cache/sandbox routing, time, and result.
Invalidators include edits or zig fmt, regeneration, commit/amend/rebase/merge,
worktree/head change, dependency/fork change, target/mode/option change, or
command change.
Run the repository's focused and aggregate proof commands directly. Record the
exact command, working directory, artifact state, Zig version, options, and
result in the final report. Focused proof may diagnose; closure proof must match
the final context.
A Zig stdlib or test-runner PermissionDenied in a review sandbox is an
environment verdict. Rerun the same command with a writable global cache.
First-pass workflow
Pin Zig version and artifact state.
Inspect build.zig, build.zig.zon, build steps, tests, lint, and repository guidance.
Classify Axis A and Axis B.
Emit ZSR-v1 for material work.
Name owner, counterexample, repair boundary, bounds, assertion pairs, forbidden shortcuts, and proof.
Run only the scans and playbooks required by active surfaces and families.
Make the smallest owner-correct, bounded change.
Run focused proof and negative-space tests.
Run repository-closure scans when artifacts changed.
Treat operations as hazardous when correctness depends on invariants not fully
enforced by the type checker, runtime safety, build mode, or ABI.
Examples:
@setRuntimeSafety(false)
unreachable or catch unreachable
undefined
raw pointer or integer casts
many-item and C pointers
extern or packed layout
FFI, asm, MMIO, volatile
atomics and lock-free paths
unchecked, wrapping, or saturating arithmetic
SIMD or vector fast paths
allocator and lifetime boundaries
Use repository lint first. For stable Zig 0.16.x third-party linting, use the
repository-pinned compatible zlinter release and curated rules rather than an
indiscriminate all-rules default.
Cache and sandbox
Inventory before deletion.
Treat:
.zig-cache or zig-cache disposable local build cache
zig-out generated output and install prefix
zig-pkg dependency working state; inspect modifications and forks
global cache shared infrastructure
Default destructive cache operations to dry-run and refuse while active Zig
builds are detected.
In review or subagent sandboxes, rerun cache permission failures with a writable
global cache before making a code verdict.
