xyntetik-runner: Instructions file for Codex

Runner Agent Rules

These rules are mandatory for every AI or LLM agent that changes this repository. Where a framework default, tool habit or generated plan conflicts with them, this document wins.

1. Deep modules

Keep public interfaces small and deliberate, with the complexity behind them.

• Module boundaries are intentional: CLI and server behaviour in main.c/server.c, inference flow in engine.c, model loading and forward in model.c, constrained output in jsonmode.c/schema.c (native tool grammars in schema_tools.c), platform details in compat.c, backends in cuda.c/metal.m.
• Do not expose internals to make a quick change easier.
• Lock behaviour through public interfaces: CLI output, HTTP endpoints, committed smoke scripts, or focused test binaries. Internals may change freely only while those tests protect the behaviour.

2. How to change code

Tracer bullets and test-driven development, one behaviour at a time:

1. Read the relevant code and docs first, and surface your assumptions.
2. Write one failing test or smoke for the smallest observable behaviour, through the public interface.
3. Implement the minimum code to pass it, touching the real layers rather than building horizontal scaffolding.
4. Run the relevant verification, then refactor only while green.
5. Check the README impact (rule 4), then repeat for the next behaviour.

Do not write all tests first and all code afterwards, mock internal collaborators without a boundary reason, assert on incidental details, or add speculative features.

3. Gates and evidence

A gate proves a system agrees with the instrument measuring it, not that the system is right.

• Every gate needs one absolute anchor: at least one assertion whose expected value comes from outside the system (a published constant, a hand-computed result, a specification, a reference implementation, a physical fact about the hardware). Two of our own builds agreeing proves only determinism. Where a gate cannot have an absolute anchor, say so where the gate lives.
• Random inputs are not equivalence. Every equivalence gate over a kernel or a rewritten path carries deterministic boundary inputs beside the random ones: codes at each extreme, the quantizer's top code, the zero block, the largest and smallest scales, lengths around each SIMD step and tail (tests/test_quants_simd.c is the pattern). Prefer the original kernel unless the rewrite is proven equivalent.
• Prove the rebuild. make compares whole-second mtimes. After restoring a mutated source, sleep 1, touch it and confirm a compile happened; in any A/B of two binaries from one tree, confirm they differ (a behavioural probe beats a hash) before trusting a number from them.