Koda runtime — source of truth

Rule

The *anonical*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.

Anti-pattern (do not do)

Editing engines/lang/koda/docs/research/runtime-design-R.asm to fix a production bug does *othing* 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 20260509). The header on the file warns explicitly.

Why two artifacts exist

• *roduction 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 stalepointerafter-relocation risk),

    fits in emit_runtime's ~2200 asm_emit budget.

• *esearch 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 *ust 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 *oesn't exist*error today (the file was moved 20260509). 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.)