feat(stdlib): Jobs, Promises & opt-in Sync concurrency (#14)

A layered concurrency library, safe by default. The recommended tier is
Job.* / Promise.*: a Job is a future — Job.run(kind, arg) starts a
cooperative background compute that advances each Job.pump(budget) and
finishes after enough frames (heavy work spreads out instead of hitching),
or Job.defer + Job.fulfill/fail/cancel drives one by hand. Poll with
done/ok/failed/cancelled, read result/error, count outstanding work with
Job.pending. Promise.all/race combine handle lists into a group job resolved
on the main thread; Promise.count_done/all_done power a loading bar.

The advanced, opt-in Sync.* tier (mutex/atomic/channel + cpu_count) is the
"here be dragons" surface for engine-level message passing.

The whole thing is a deterministic cooperative scheduler: results are
collected on the main thread and a Job never touches the ECS world, so
lockstep and replays stay bit-exact — same jobs + same budget reproduce
byte-for-byte on every target, and a preemptive OS-thread backend can slot
behind this same API later. Ludic has no closures, so a Job carries a
compute kind + int arg (or a hand-driven defer) rather than fn()->…, and
Promise progress is polled rather than chained through then.

Written in Ludic and spliced on demand (like Regex/Dict/Numeric): a program
that never mentions Job.*/Promise.*/Sync.* compiles byte-identically and the
C-free bootstrap fixpoint is untouched. New: runtime/native/jobs.ludic,
emit_ns_call dispatch, parse-time splice, examples/library/jobs.ludic (31
self-asserting checks), 33 docs pages + inventory, changeset.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

selfhost/backend/emit_call.ludic

@@ -389,6 +389,49 @@ function emit_ns_call(ns: pointer, meth: pointer, e: Node) -> Val {
     if (meth == "clear")   { bare = "set_clear";   push(labels, "s") }
     if (meth == "members") { bare = "set_members"; push(labels, "s") }
   }
+  # Job.* / Promise.* / Sync.* -> the concurrency runtime (runtime/native/jobs.ludic,
+  # spliced on demand). Ordinary Ludic functions, so the generic call path keeps
+  # their return types (int / bool). The safe tier (Job/Promise) is a deterministic
+  # cooperative scheduler; Sync.* is the advanced, opt-in message-passing tier. #14.
+  if (ns == "Job") {
+    if (meth == "defer")     { bare = "job_defer" }
+    if (meth == "run")       { bare = "job_run";      push(labels, "kind"); push(labels, "arg") }
+    if (meth == "fulfill")   { bare = "job_fulfill";  push(labels, "handle"); push(labels, "value") }
+    if (meth == "fail")      { bare = "job_fail";     push(labels, "handle"); push(labels, "error") }
+    if (meth == "cancel")    { bare = "job_cancel";   push(labels, "handle") }
+    if (meth == "pump")      { bare = "job_pump";     push(labels, "budget") }
+    if (meth == "done")      { bare = "job_done";     push(labels, "handle") }
+    if (meth == "ok")        { bare = "job_ok";       push(labels, "handle") }
+    if (meth == "failed")    { bare = "job_failed";   push(labels, "handle") }
+    if (meth == "cancelled") { bare = "job_cancelled"; push(labels, "handle") }
+    if (meth == "result")    { bare = "job_result";   push(labels, "handle") }
+    if (meth == "error")     { bare = "job_error";    push(labels, "handle") }
+    if (meth == "pending")   { bare = "job_pending" }
+    if (meth == "free")      { bare = "job_free";     push(labels, "handle") }
+  }
+  if (ns == "Promise") {
+    if (meth == "all")        { bare = "prom_all";        push(labels, "handles") }
+    if (meth == "race")       { bare = "prom_race";       push(labels, "handles") }
+    if (meth == "count_done") { bare = "prom_count_done"; push(labels, "handles") }
+    if (meth == "all_done")   { bare = "prom_all_done";   push(labels, "handles") }
+  }
+  if (ns == "Sync") {
+    if (meth == "mutex")     { bare = "sync_mutex" }
+    if (meth == "lock")      { bare = "sync_lock";     push(labels, "mutex") }
+    if (meth == "unlock")    { bare = "sync_unlock";   push(labels, "mutex") }
+    if (meth == "try_lock")  { bare = "sync_try_lock"; push(labels, "mutex") }
+    if (meth == "atomic")    { bare = "sync_atomic" }
+    if (meth == "get")       { bare = "sync_get";      push(labels, "atomic") }
+    if (meth == "set")       { bare = "sync_set";      push(labels, "atomic"); push(labels, "value") }
+    if (meth == "add")       { bare = "sync_add";      push(labels, "atomic"); push(labels, "delta") }
+    if (meth == "cas")       { bare = "sync_cas";      push(labels, "atomic"); push(labels, "expect"); push(labels, "next") }
+    if (meth == "channel")   { bare = "sync_channel" }
+    if (meth == "send")      { bare = "sync_send";     push(labels, "channel"); push(labels, "value") }
+    if (meth == "recv")      { bare = "sync_recv";     push(labels, "channel") }
+    if (meth == "can_recv")  { bare = "sync_can_recv"; push(labels, "channel") }
+    if (meth == "len")       { bare = "sync_len";      push(labels, "channel") }
+    if (meth == "cpu_count") { bare = "sync_cpu_count" }
+  }
   # Huge.* / Angle.* / Percent.* -> the numeric runtime (runtime/native/numeric.ludic,
   # spliced on demand). Ordinary Ludic functions, so the generic call path keeps
   # their return types (Huge / fixed / int / bool).

selfhost/frontend/parse.ludic

@@ -178,6 +178,7 @@ function p_postfix() -> Node {
       if e.a.kind == E_ID and (e.a.s == "BigInt" or e.a.s == "Decimal") { g_uses_bignum = true }   # splice the bignum runtime on demand
       if e.a.kind == E_ID and (e.a.s == "Dict" or e.a.s == "Set") { g_uses_dict = true }   # splice the hash-table runtime on demand
       if e.a.kind == E_ID and (e.a.s == "Huge" or e.a.s == "Angle" or e.a.s == "Percent") { g_uses_numeric = true }   # splice the huge/angle/percent runtime on demand
+      if e.a.kind == E_ID and (e.a.s == "Job" or e.a.s == "Promise" or e.a.s == "Sync") { g_uses_jobs = true }   # splice the jobs/promise/sync runtime on demand
       if e.a.kind == E_ID and e.a.s == "Query" { g_uses_query = true }   # splice the ECS spatial-query runtime on demand
       if e.a.kind == E_ID and e.a.s == "Reflect" { g_uses_reflect = true }   # force-emit the reflection ABI (Reflect.* reads the world schema)
       if e.a.kind == E_ID and e.a.s == "Light" { g_uses_light = true }   # splice the 2D light-accumulation pass on demand
@@ -427,6 +428,7 @@ var g_uses_regex: bool = false    # a program mentioned Regex.* -> splice the re
 var g_uses_bignum: bool = false   # a program mentioned BigInt.*/Decimal.* -> splice the bignum runtime
 var g_uses_dict: bool = false     # a program mentioned Dict.*/Set.* -> splice the hash-table runtime
 var g_uses_numeric: bool = false  # a program mentioned Huge.*/Angle.*/Percent.* -> splice the numeric runtime
+var g_uses_jobs: bool = false     # a program mentioned Job.*/Promise.*/Sync.* -> splice the concurrency runtime
 var g_uses_query: bool = false    # a program mentioned Query.* -> splice the query runtime + reflection ABI
 var g_uses_reflect: bool = false  # a program mentioned Reflect.* -> force-emit the reflection ABI
 var g_uses_light: bool = false    # a program mentioned Light.* -> splice the 2D light pass
@@ -626,6 +628,14 @@ function maybe_splice_runtime() -> void {
     do_import("runtime/native/numeric.ludic")
     cur_dir = saved
   }
+  # any program that uses Job.*/Promise.*/Sync.* gets the concurrency runtime
+  # spliced in (it is self-contained — only compiler intrinsics — so a plain tool
+  # works too). A deterministic cooperative scheduler; see runtime/native/jobs.ludic.
+  if g_uses_jobs {
+    cur_dir = ""
+    do_import("runtime/native/jobs.ludic")
+    cur_dir = saved
+  }
   # any program that uses Query.* gets the ECS spatial-query helpers spliced in;
   # they read entity state through the reflection ABI (emit_decl force-emits it
   # for a Query program even when it declares no events).
@@ -743,6 +753,7 @@ function parse_program() -> void {
   g_uses_bignum = false
   g_uses_dict = false
   g_uses_numeric = false
+  g_uses_jobs = false
   g_uses_query = false
   g_uses_reflect = false
   g_uses_esys = false