Koda runtime — source of truth

ratified

Rule

The canonical Koda runtime — the one that ships in every koder binary — is emitted at compile time by:

engines/lang/koda/self-hosted/lib/compiler_backend.kd
  ::emit_runtime_part2

Edits to runtime semantics (allocator, GC, syscall wrappers, runtime helpers _rt_*) MUST happen there.

Clarification (koda#810, 2026-06-07): ::emit_runtime_part2 is shorthand for "the runtime emitted by compiler_backend.kd". The emission actually spans emit_runtime (def ~line 10356 — holds the Time.* syscall sites, the GC timing sites, _rt_env_get, and most _rt_* helpers) and emit_runtime_part2. Edit whichever of the two physically contains the code; both are in compiler_backend.kd and both are the build path. The hard rule is the Anti-pattern below — never edit runtime-design-R.asm (research-only).

Anti-pattern (do not do)

Editing engines/lang/koda/docs/research/runtime-design-R.asm to fix a production bug does nothing. That file is not in the build path; it is a historical reference. Past contributors hit this trap (#724 fix landed there but never shipped — reclassified N/A 2026-05-09). The header on the file warns explicitly.

Why two artifacts exist

  • Production runtime (Design P, in compiler_backend.kd::emit_runtime_part2):
    • Old gen: fixed mmap'd 2GB region. Process exits rc=137 on

      exhaustion.

    • Minor GC: mark only, no promote (young objects stay in place;

      new allocations route to old gen via _minor_gc_done flag).

    • Reason: simple, safe (no stale-pointer-after-relocation risk),

      fits in emit_runtime's ~2200 asm_emit budget.

  • Research runtime (Design R, in docs/research/runtime-design-R.asm):
    • Old gen: extensible via sys_brk.
    • Minor GC: full mark + promote + forwarding pointers.
    • Reason: scales beyond 2GB; future-proof for kodec workloads.
    • Why archived: conservative stack scanning cannot safely update

      native stack pointers after object relocation; promote was disabled in production for this reason.

737 chose Option A: canonize Design P, retire Design R, defer

extensible-heap work to #753 when 2GB cap actually bites.

Future change

If the production 2GB cap becomes a concrete blocker for shipped workloads, ticket #753 opens the extensible-heap question. The work happens at the canonical site (compiler_backend.kd::emit_runtime_part2), not in the research file. The research file may be consulted as reference for Design R shape but must not be resurrected as a build artifact — that brings back the dual-source trap this policy exists to prevent.

Audit (mechanical)

Any AI session opening engines/lang/koda/self-hosted/lib/runtime.asm hits a doesn't exist error today (the file was moved 2026-05-09). Any AI session opening engines/lang/koda/docs/research/runtime-design-R.asm sees the file header warning before any code. These are the two enforcement mechanisms.

A future /k-housekeep audit phase could additionally:

  • Refuse to commit edits to docs/research/runtime-design-R.asm

    unless a doc-only change is explicitly opted in (e.g., header expansion).

  • Warn on any new file matching runtime*.asm outside of

    docs/research/ (catch attempts to re-fork).

(Not required today — the policy + file move + header are sufficient for the current scale.)