feat(stdlib): add Log.* — levelled, structured logging (#15)

A Log.* namespace: five levels (trace/debug/info/warn/error), a runtime
threshold, and structured key=value fields, so games get something better than
scattered print calls and release builds can go quiet without touching call
sites.

  - Log.trace/debug/info/warn/error(msg, [k, v]...)  -> stderr, "[LEVEL] msg k=v"
  - Log.set_level(n)   show only level >= n (0 = all default, 5 silences all)
  - Log.level()        read the current threshold

Fields accept strings, ints, and longs (numbers formatted automatically); the
level tag is chosen at compile time so a filtered-out level costs only a
comparison. Writes to stderr, never touching the simulation — no effect on
determinism/replays. v1 is the console sink; rotating-file and in-engine overlay
sinks are noted as follow-ups.

- examples/library/logging.ludic: asserts the set_level/level threshold
  round-trip and that every level (with mixed-type fields) runs without faulting;
  the stderr gating itself was verified by hand (warn/error emit, lower levels
  suppressed). Wired into `x test` (now 53 passed).
- docs: a new Log section + per-symbol pages; inventory and coverage pass.
- seed regenerated; `x bootstrap-cfree` fixpoint holds.

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

docs/language/log/_section.md

@@ -0,0 +1,11 @@
+---
+id: log
+title: Log
+order: 6
+---
+
+Levelled, structured logging — the default way to answer "what is my game doing?" and "why did that break?", and a real step up from scattering <code>print</code> calls through your code. Each message carries a level, from <a href="log-trace"><code>trace</code></a> (most verbose) through <a href="log-debug"><code>debug</code></a>, <a href="log-info"><code>info</code></a>, and <a href="log-warn"><code>warn</code></a> to <a href="log-error"><code>error</code></a>, and a runtime threshold set with <a href="log-set_level"><code>Log.set_level</code></a> decides which ones actually appear — so a development build can be chatty and a release build quiet, without touching the call sites.
+
+Messages go to standard error, kept separate from a program's real stdout, tagged with their level. Beyond the message you can pass **structured fields** as trailing key/value pairs — <code>Log.warn("missing texture", "path", p, "id", n)</code> prints <code>[WARN] missing texture path=... id=...</code> — cheap to write and easy to grep. Numeric values (int, long) are formatted for you; the level tag is chosen at compile time, so a filtered-out level costs only a threshold comparison at runtime.
+
+Logging never touches the simulation — it writes to stderr and returns — so it has no effect on gameplay determinism or replays. This first version ships the console (stderr) sink; a rotating-file sink and an in-engine overlay sink are planned follow-ups.

docs/language/log/log-debug.md

@@ -0,0 +1,27 @@
+---
+id: log-debug
+name: Log.debug
+category: log
+kind: namespace-method
+tokens: Log.debug
+sig: Log.debug(msg, [key, value]...) -> void
+tip: Log at the debug level (1) — development detail.
+order: 2
+ns: Log
+member: debug
+---
+
+Logs <code>msg</code> at the **debug** level (1) — development-time detail that is useful while building a feature but noise in a shipped game. It prints on stderr as <code>[DEBUG] msg</code> with any structured <code>key=value</code> fields, when the <a href="log-set_level"><code>Log.set_level</code></a> threshold is 1 or lower. Reach for it to trace state transitions, loaded assets, or the values feeding a calculation you are not yet sure of.
+
+Parameters:
+- `msg` — the message string
+- `key, value...` — optional trailing pairs; values may be strings or numbers
+
+```ludic
+program Debug {
+  entry {
+    Log.set_level(1)
+    Log.debug("player state", "hp", 100, "phase", "combat")
+  }
+}
+```

docs/language/log/log-error.md

@@ -0,0 +1,26 @@
+---
+id: log-error
+name: Log.error
+category: log
+kind: namespace-method
+tokens: Log.error
+sig: Log.error(msg, [key, value]...) -> void
+tip: Log at the error level (4) — a failure.
+order: 5
+ns: Log
+member: error
+---
+
+Logs <code>msg</code> at the **error** level (4), the highest — a real failure the game could not handle cleanly: a save that would not write, a required asset that could not load. It prints on stderr as <code>[ERROR] msg</code> with any structured <code>key=value</code> fields, and shows at every threshold except one set above 4. Error is the level you almost always want visible, including in release builds.
+
+Parameters:
+- `msg` — the message string
+- `key, value...` — optional trailing pairs; values may be strings or numbers
+
+```ludic
+program Error {
+  entry {
+    Log.error("save failed", "path", "slot1.sav", "code", 5)
+  }
+}
+```

docs/language/log/log-info.md

@@ -0,0 +1,26 @@
+---
+id: log-info
+name: Log.info
+category: log
+kind: namespace-method
+tokens: Log.info
+sig: Log.info(msg, [key, value]...) -> void
+tip: Log at the info level (2) — normal operation.
+order: 3
+ns: Log
+member: info
+---
+
+Logs <code>msg</code> at the **info** level (2) — the normal-operation milestones you want to see in a running game: a level loaded, a match started, a save written. It prints on stderr as <code>[INFO] msg</code> with any structured <code>key=value</code> fields, when the <a href="log-set_level"><code>Log.set_level</code></a> threshold is 2 or lower. Info is a sensible default level for a development build.
+
+Parameters:
+- `msg` — the message string
+- `key, value...` — optional trailing pairs; values may be strings or numbers
+
+```ludic
+program Info {
+  entry {
+    Log.info("level loaded", "name", "cavern", "entities", 42)
+  }
+}
+```

docs/language/log/log-level.md

@@ -0,0 +1,24 @@
+---
+id: log-level
+name: Log.level
+category: log
+kind: namespace-method
+tokens: Log.level
+sig: Log.level() -> int
+tip: The current logging threshold.
+order: 7
+ns: Log
+member: level
+---
+
+Returns the current logging threshold — the minimum level that <a href="log-set_level"><code>Log.set_level</code></a> last set (0 by default). Use it to branch on how verbose logging is: skip building an expensive debug string when it would be dropped anyway, or show an in-game indicator that verbose logging is on. The levels are <code>trace</code> 0 through <code>error</code> 4.
+
+```ludic
+program Level {
+  entry {
+    print(Log.level())        # 0
+    Log.set_level(2)
+    print(Log.level())        # 2
+  }
+}
+```

docs/language/log/log-set_level.md

@@ -0,0 +1,27 @@
+---
+id: log-set_level
+name: Log.set_level
+category: log
+kind: namespace-method
+tokens: Log.set_level
+sig: Log.set_level(n) -> void
+tip: Show only messages at level n or above (0 = all).
+order: 6
+ns: Log
+member: set_level
+---
+
+Sets the logging threshold: only messages whose level is <code>n</code> or higher are written; everything below is silently dropped. The levels are <code>trace</code> 0, <code>debug</code> 1, <code>info</code> 2, <code>warn</code> 3, <code>error</code> 4, so <code>set_level(3)</code> shows only warnings and errors, and the default of <code>0</code> shows everything. Set it once at startup — low in development, high (3, or 5 to silence all) for release — and every call site adjusts automatically. Read the current value back with <a href="log-level"><code>Log.level</code></a>.
+
+Parameters:
+- `n` — the minimum level to show (0–4; use 5 to silence every level)
+
+```ludic
+program Quiet {
+  entry {
+    Log.set_level(3)          # warnings and errors only
+    Log.info("startup")       # dropped
+    Log.warn("low memory")    # shown
+  }
+}
+```

docs/language/log/log-trace.md

@@ -0,0 +1,27 @@
+---
+id: log-trace
+name: Log.trace
+category: log
+kind: namespace-method
+tokens: Log.trace
+sig: Log.trace(msg, [key, value]...) -> void
+tip: Log at the trace level (0) — the most verbose.
+order: 1
+ns: Log
+member: trace
+---
+
+Logs <code>msg</code> at the **trace** level (0), the most verbose — the fine-grained "I am here, this is the value" tracing you turn on only when hunting a specific problem. It appears on stderr as <code>[TRACE] msg</code>, followed by any structured <code>key=value</code> fields, but only when the threshold set by <a href="log-set_level"><code>Log.set_level</code></a> is 0. Because trace is usually filtered out, keep the calls wherever they help; a disabled level costs only a comparison.
+
+Parameters:
+- `msg` — the message string
+- `key, value...` — optional trailing pairs; values may be strings or numbers
+
+```ludic
+program Trace {
+  entry {
+    Log.set_level(0)
+    Log.trace("spawned entity", "id", 7, "at", "cave")
+  }
+}
+```

docs/language/log/log-warn.md

@@ -0,0 +1,26 @@
+---
+id: log-warn
+name: Log.warn
+category: log
+kind: namespace-method
+tokens: Log.warn
+sig: Log.warn(msg, [key, value]...) -> void
+tip: Log at the warn level (3) — something looks wrong.
+order: 4
+ns: Log
+member: warn
+---
+
+Logs <code>msg</code> at the **warn** level (3) — something is wrong but the game recovered: a missing asset fell back to a placeholder, a value was clamped, a deprecated path was taken. It prints on stderr as <code>[WARN] msg</code> with any structured <code>key=value</code> fields, when the <a href="log-set_level"><code>Log.set_level</code></a> threshold is 3 or lower. Warnings are a good level to keep on in release builds so player bug reports capture them.
+
+Parameters:
+- `msg` — the message string
+- `key, value...` — optional trailing pairs; values may be strings or numbers
+
+```ludic
+program Warn {
+  entry {
+    Log.warn("missing texture, using placeholder", "path", "rock.png")
+  }
+}
+```