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>

docs/language/job/_section.md

@@ -0,0 +1,7 @@
+---
+id: job
+title: Job
+order: 37
+---
+
+Background work that stays out of the frame. A <code>Job</code> is a future — a handle to a result that lands later. Kick one off with <code>Job.run</code> (a background compute that advances a little each <code>Job.pump</code> and finishes after enough frames, so heavy work never hitches) or <code>Job.defer</code> (a future you resolve yourself with <code>Job.fulfill</code> / <code>Job.fail</code>). Poll it with <code>done</code> / <code>ok</code> / <code>failed</code> / <code>cancelled</code>, read <code>result</code> / <code>error</code>, and always collect on the main thread — a Job must never touch the ECS world directly. The scheduler is deterministic and cooperative, so the same jobs and the same budget reproduce byte-for-byte, every run and every target. Arguments are positional. Spliced in only when a program mentions <code>Job.*</code>.

docs/language/job/job-cancel.md

@@ -0,0 +1,19 @@
+---
+id: job-cancel
+name: Job.cancel
+category: job
+kind: namespace-method
+tokens: Job.cancel
+sig: Job.cancel(handle) -> void
+tip: Cancel a job before it finishes.
+order: 4
+ns: Job
+member: cancel
+---
+
+Cancel a job before it finishes.
+
+```ludic
+let job = Job.defer()
+Job.cancel(job)
+```

docs/language/job/job-cancelled.md

@@ -0,0 +1,20 @@
+---
+id: job-cancelled
+name: Job.cancelled
+category: job
+kind: namespace-method
+tokens: Job.cancelled
+sig: Job.cancelled(handle) -> bool
+tip: Was the job cancelled?
+order: 9
+ns: Job
+member: cancelled
+---
+
+Was the job cancelled?
+
+```ludic
+let job = Job.defer()
+Job.cancel(job)
+let stopped = Job.cancelled(job)
+```

docs/language/job/job-defer.md

@@ -0,0 +1,19 @@
+---
+id: job-defer
+name: Job.defer
+category: job
+kind: namespace-method
+tokens: Job.defer
+sig: Job.defer() -> Job
+tip: A future you resolve yourself later.
+order: 0
+ns: Job
+member: defer
+---
+
+A future you resolve yourself later.
+
+```ludic
+let job = Job.defer()
+Job.fulfill(job, 42)
+```

docs/language/job/job-done.md

@@ -0,0 +1,20 @@
+---
+id: job-done
+name: Job.done
+category: job
+kind: namespace-method
+tokens: Job.done
+sig: Job.done(handle) -> bool
+tip: Has the job resolved (any outcome)?
+order: 6
+ns: Job
+member: done
+---
+
+Has the job resolved (any outcome)?
+
+```ludic
+let job = Job.defer()
+Job.fulfill(job, 1)
+let finished = Job.done(job)
+```

docs/language/job/job-error.md

@@ -0,0 +1,20 @@
+---
+id: job-error
+name: Job.error
+category: job
+kind: namespace-method
+tokens: Job.error
+sig: Job.error(handle) -> int
+tip: The error code of a failed job.
+order: 11
+ns: Job
+member: error
+---
+
+The error code of a failed job.
+
+```ludic
+let job = Job.defer()
+Job.fail(job, 500)
+let code = Job.error(job)
+```

docs/language/job/job-fail.md

@@ -0,0 +1,19 @@
+---
+id: job-fail
+name: Job.fail
+category: job
+kind: namespace-method
+tokens: Job.fail
+sig: Job.fail(handle, error) -> void
+tip: Resolve a pending job as failed.
+order: 3
+ns: Job
+member: fail
+---
+
+Resolve a pending job as failed.
+
+```ludic
+let job = Job.defer()
+Job.fail(job, 404)
+```

docs/language/job/job-failed.md

@@ -0,0 +1,20 @@
+---
+id: job-failed
+name: Job.failed
+category: job
+kind: namespace-method
+tokens: Job.failed
+sig: Job.failed(handle) -> bool
+tip: Did the job fail?
+order: 8
+ns: Job
+member: failed
+---
+
+Did the job fail?
+
+```ludic
+let job = Job.defer()
+Job.fail(job, 9)
+let bad = Job.failed(job)
+```

docs/language/job/job-free.md

@@ -0,0 +1,20 @@
+---
+id: job-free
+name: Job.free
+category: job
+kind: namespace-method
+tokens: Job.free
+sig: Job.free(handle) -> void
+tip: Release a job slot back to the pool.
+order: 13
+ns: Job
+member: free
+---
+
+Release a job slot back to the pool.
+
+```ludic
+let job = Job.defer()
+Job.fulfill(job, 1)
+Job.free(job)
+```

docs/language/job/job-fulfill.md

@@ -0,0 +1,19 @@
+---
+id: job-fulfill
+name: Job.fulfill
+category: job
+kind: namespace-method
+tokens: Job.fulfill
+sig: Job.fulfill(handle, value) -> void
+tip: Resolve a pending job with a value.
+order: 2
+ns: Job
+member: fulfill
+---
+
+Resolve a pending job with a value.
+
+```ludic
+let job = Job.defer()
+Job.fulfill(job, 7)
+```

docs/language/job/job-ok.md

@@ -0,0 +1,20 @@
+---
+id: job-ok
+name: Job.ok
+category: job
+kind: namespace-method
+tokens: Job.ok
+sig: Job.ok(handle) -> bool
+tip: Did the job succeed?
+order: 7
+ns: Job
+member: ok
+---
+
+Did the job succeed?
+
+```ludic
+let job = Job.defer()
+Job.fulfill(job, 1)
+let good = Job.ok(job)
+```

docs/language/job/job-pending.md

@@ -0,0 +1,18 @@
+---
+id: job-pending
+name: Job.pending
+category: job
+kind: namespace-method
+tokens: Job.pending
+sig: Job.pending() -> int
+tip: How many jobs are still unresolved.
+order: 12
+ns: Job
+member: pending
+---
+
+How many jobs are still unresolved.
+
+```ludic
+let left = Job.pending()   # a ready-made loading-screen counter
+```

docs/language/job/job-pump.md

@@ -0,0 +1,19 @@
+---
+id: job-pump
+name: Job.pump
+category: job
+kind: namespace-method
+tokens: Job.pump
+sig: Job.pump(budget) -> int
+tip: Advance background jobs; collect results.
+order: 5
+ns: Job
+member: pump
+---
+
+Advance background jobs; collect results.
+
+```ludic
+let job = Job.run(1, 1000)
+Job.pump(64)   # spend up to 64 steps this frame (0 = finish all)
+```

docs/language/job/job-result.md

@@ -0,0 +1,20 @@
+---
+id: job-result
+name: Job.result
+category: job
+kind: namespace-method
+tokens: Job.result
+sig: Job.result(handle) -> int
+tip: The success value of a done job.
+order: 10
+ns: Job
+member: result
+---
+
+The success value of a done job.
+
+```ludic
+let job = Job.defer()
+Job.fulfill(job, 42)
+let value = Job.result(job)
+```

docs/language/job/job-run.md

@@ -0,0 +1,19 @@
+---
+id: job-run
+name: Job.run
+category: job
+kind: namespace-method
+tokens: Job.run
+sig: Job.run(kind, arg) -> Job
+tip: Start a background compute job.
+order: 1
+ns: Job
+member: run
+---
+
+Start a background compute job.
+
+```ludic
+let job = Job.run(1, 100)   # 1 = sum 1..arg, 2 = fib, 3 = count primes
+Job.pump(0)
+```