| name | funpack-determinism |
| description | The funpack determinism contract, fixed-point numerics, the compiler's structural quality gates, @stub/@todo typed holes, and which funpack-mcp tool drives each compile/test/index-query op. Use to understand why a build fails (a gate), how to stay deterministic, how Fixed-point math behaves, how to develop incrementally with typed holes, and which MCP tool to call to compile, test, or query the index. Triggers on "fixed-point", "Fixed/Q32.32", "determinism", "why won't it compile", "quality gate", "effect closure", "exhaustive match", "@stub", "@todo", "--release", "build the project", "run the tests", "compile to check", "query the index". |
funpack determinism, gates & holes
funpack's compiler is a quality gate: structural problems are errors, not warnings, with
fixed budgets and no per-site waiver. This is what makes the write → check → fix loop converge. This
skill covers the rules an author lives under. The ops that drive the loop (compile, test, query the
index) are MCP tools — see the Driving the loop section below.
The determinism contract
Two tiers:
- Build determinism — same source → bit-identical artifact.
- Simulation determinism — same inputs + seed → bit-identical frame N on every machine.
It's load-bearing at runtime (lockstep/peer-to-peer multiplayer, shared recordings) and in the dev
loop (exact replay-repro and testing). The three sources of per-tick variance are all fixed or
threaded, so input is the only nondeterminism in user code:
- Input arrives as the read-only
Input resource — a per-tick action snapshot recorded for
replay. Logic queries semantic actions, never devices (see funpack-engine-api).
- RNG is the
Rng resource, threaded: a function taking an Rng must return the advanced
one (-> (value, next_rng)); it is never silently advanced. Consume a draw with a tuple destructure
— let (value, next) = rng.range(lo, hi) — and thread next into the next draw; sequential draws
chain flat, so a multi-draw generator stays well under the depth gate.
- Time is the
Time resource — logical time on a fixed timestep; there is no wall clock in sim.
A tick is a fold over the flattened pipeline, so a replay re-folds bit-identically.
Do not model a per-thing stage as a simultaneous map
The fold is instance-granular: a per-thing behavior runs over its instances in stable Id
order, and a later instance (higher Id) observes earlier same-step instances' blackboard writes
through a direct View — the columns evolve within the step. So a per-thing stage is an
Id-ordered fold over instances, never a simultaneous map over a pre-tick snapshot. Modeling
it as the latter — handing every instance the same frozen snapshot — diverges from the live
schedule, yet a hand-rolled simultaneous twin passes a green suite, giving false confidence on the
replay-fidelity property this contract exists to protect. Drive every assertion through the real
Id-ordered fold (per-instance name.step(...) with each return folded forward), not a
snapshot-map.
Id-order bias is real: because the lower Id acts first, a reflection-symmetric matchup is
not neutral — it is decided by spawn Id order. Treat a symmetric setup as Id-order-biased, and
fix the expected outcome to whichever instance has the lower Id.
A query is a live read, not a per-tick snapshot
A query reads the world at its call point — its all[T] is the same evolving working table a
direct View[T] read sees. It is not cached within a tick: call the same query twice in one tick
and, if writes landed between the calls, the second call reflects them. So View[T], all[T], and
query are one read rule — all evolving, all reading the working table — never three different
visibilities. Do not assume a query yields a stable snapshot frozen for the whole tick; if you need one
value held constant across the tick, compute it once and thread it, rather than re-querying and
expecting the first answer back.
What an author must do / avoid
| Do | Avoid |
|---|
Use Fixed (42.5) for all sim numbers; lift Int → Fixed with to_fixed(n) | A bare f-literal in sim code — a compile error |
Keep Float strictly behind the render/audio seam | Any Float on a type that flows into a blackboard or signal — a compile error (the warranty gate) |
| Read time/rng/input only via the injected resources | Ambient IO/clock/RNG — unrepresentable (no such primitives are in scope) |
Thread Rng (return it advanced) | Assuming + reorders — Fixed + is not reorder-invariant under saturation |
Trust fold is left-to-right | Reading a setting from a behavior — settings are structurally kept out of the sim, so replays can't diverge |
Use the engine Quat (auto-renormalizing) | Holding a Mat4 in sim — it is engine-only, not constructible in sim code |
Fixed-point numerics
Fixed is a signed 64-bit Q32.32 (32 integer, 32 fractional bits) — the single non-configurable
format. Range ≈ ±2.1×10⁹, precision ≈ 2.3×10⁻¹⁰. Multiply uses a 128-bit intermediate; both
multiply and divide round toward zero — one rule, every machine.
Literals are type-directed: 42 is Int; 42.5 is Fixed (the sim default); 42.5f is
Float (render/audio only — a bare f in sim is a compile error). A Fixed literal not exactly
representable (0.1) is rounded to the nearest Fixed at compile time, deterministically.
Arithmetic is total — saturate, never wrap, never trap:
- Overflow past
Fixed.MAX/Fixed.MIN saturates to the rail (same for Int).
x / 0 is defined: saturates by the sign of x (+x → MAX, −x → MIN, 0/0 → 0); x % 0 → 0.- When detecting a zero divisor is the point, use
checked_div/checked_rem → Option, forcing a
match.
- No implicit
Int → Fixed — mixing goes through explicit to_fixed.
Transcendentals are computed in integer arithmetic — polynomial/lookup/CORDIC over the Fixed
representation, no float/libm in the path, so sin/cos/etc. are bit-identical everywhere.
Vectors: Vec2/Vec3 are Fixed data: Num; the Num kind confers + - * and equality and
nothing more — it does not confer /. dot/cross/length/normalize/distance are named
functions, never operators. Rotation is a unit Quat (Quat.mul renormalizes).
fold is strictly left-to-right — never tree-reduced or parallelized; a right-fold of the same
list can differ at the rails.
Golden values you can rely on (from the numerics example):
0.5 * 0.5 == 0.25 1.0 / 4.0 == 0.25 to_fixed(2) == 2.0
1.0 / 0.0 == Fixed.MAX -1.0 / 0.0 == Fixed.MIN 0.0 / 0.0 == 0.0 5.0 % 0.0 == 0.0
checked_div(6.0, 2.0) == Option::Some(3.0) checked_div(1.0, 0.0) == Option::None
trunc(1.5)==1 trunc(-1.5)==-1 floor(-1.5)==-2 round(1.5)==2
clamp(5.0,0.0,3.0)==3.0 lerp(0.0,10.0,0.5)==5.0 length(Vec2{x:3.0,y:4.0})==5.0
sin(0.0)==0.0 cos(0.0)==1.0 a.slerp(b,0.0)==a a.slerp(b,1.0)==b
fold([1.0,-1.0], Fixed.MAX, +) == Fixed.MAX - 1.0 # left-to-right under saturation
The structural quality gates (errors, not warnings)
A build fails on any of these — they drive the write → check → fix loop. They also run on hot-reload
(last-good code keeps running; you get fix-criteria diagnostics).
| Gate | Triggers when | Fix |
|---|
| Cyclomatic complexity ≤ 10 | a too-branchy function | decompose |
| Nesting depth ≤ 3 | deep if/match pyramids | extract / flatten |
| Function size ≤ 40 statements | one giant function | split |
| Parameters ≤ 5 | a wide signature | group into a data |
| Duplication | re-implementing an existing helper | reuse it (pre-empt with the warden_find MCP tool) |
Exhaustive match | an Option/Result/enum not fully covered | cover every arm |
| Effect closure | emitting a signal nothing consumes (or dropping an IO result) | add the consuming stage downstream |
| Behavior node check | a step whose params/return are illegal for its slot | conform the signature (see funpack-game-model) |
--release hole-ban | any @stub / debug directive in a release build | fill the hole before shipping |
| No ambient mutation | mutating outside mut data | route through mut data |
@gtag registry | an unregistered tag | add it to tags.fcfg |
@doc temporal-token ban | "now"/"was"/"todo"/"fix" inside @doc | state what it is |
| No free comments | a // comment in .fun/.fcfg | use @doc/@todo/@stub |
| No ambient IO | hidden IO | return a command / take a resource |
@todo expiry | a @todo past its window | resolve the debt or close the task |
| Malformed project tree | a layout violation | conform to funpack_configs/ + src/ |
These budgets are fixed compiler constants — there is no holes = allow or per-site waiver. The
only sanctioned escape for incomplete (never complex) code is the typed hole.
@stub / @todo — incremental development
fn drag() -> Fixed @stub(Fixed) // typecheck-only hole
fn launch_speed(boost: Fixed) -> Fixed @stub(Fixed, boost + 6.0) // hole with a dev fallback that runs
@todo("rebalance drops", T-0042) // dated debt; window mandatory
@stub(T) — a typed hole in body/expression position. Callers typecheck against T, so you
build top-down: write a signature, let consumers compile, fill the body later. Compiles in dev;
reaching a bare hole in dev fails closed (a defined no-value outcome). A compile error under
--release — you cannot ship a hole.@stub(T, fallback) — the fallback is a funpack expression that typechecks against T in the
declaration's own parameter scope and runs in dev, so the game stays playable while the hole
stands. Index-tracked and release-banned exactly like the bare form.@todo("msg", window) — the only legal temporal note. Windows: a task ref T-0042
(recommended), an ISO date 2026-09-01, a relative duration 30d, or a build count 50builds.
Past the window it's a compile error.- Debug directives
@break/@log/@watch/@trace are dev-only, release-forbidden, and
task-registered like @stub. @log(self.head) is the typed replacement for print (queryable
NDJSON).
The workflow: stub the signature → callers compile → add a fallback to keep playing → mark deferred
work with @todo(…, T-NNNN) → query open holes/debt with the warden_holes / warden_debt MCP
tools → fill every hole before a release build (the ban is the forcing function).
Driving the loop — the MCP tools
The compile / test / query ops are MCP tools the funpack MCP server (funpack mcp) provides, not
CLI invocations you shell out. The intent → tool map is in ../../references/mcp-tools.md; the verbs you
reach for here:
- Compile:
build (emit the artifact + .funpack/index.ndjson), check (the same verdict, no
product written), export (the optimized release build, hole-banned), fmt (format / check
formatting). A release build is the hole-ban mode — it rejects any @stub or debug directive.
- Test:
test runs every test "…" { assert … } block and returns a structured pass/fail
summary (counts + each failing test's name and detail).
- Look up the spec / engine API: search the funpack docs with the
docs_search MCP tool (then
docs_get on a hit's anchor) rather than relying on memorized prose.
warden_* — query your own project index
Warden is not a separate binary, process, or clock — the warden_* MCP tools are pure
projections over the .funpack/index.ndjson the build tool emits, and they never write source
(the agent edits source; a recompile re-derives the projection). Use them for reuse-before-write
and acceptance checks:
| Tool | Reports |
|---|
warden_find | a pre-hoc reuse check — does a helper already exist? (run before writing one) |
warden_holes | every open @stub declaration |
warden_debt | every @todo with its message + window |
warden_probes | every outstanding debug probe (@break/@log/…) |
warden_graph | the dependency/call graph projection |
warden_tags | declarations by @gtag (e.g. all behaviors tagged combat) |
warden_pipeline | the flattened pipeline projection |
A task's completion is proven by recompile — a named test passes, a @gtag query returns the
expected cardinality, a structural gate clears — not self-attested.
funpack is under active design — a real compile (the build / test tools) is the tie-breaker.
