Add leveled logging that costs nothing until it is switched on

Instrumenting a function with a print means paying for the message on every
call, forever, so the instrumentation gets deleted instead of left in place.
This is the usual answer: a level, off by default, and a payload that is not
built while the level is off.

`(pragma! log-level <off|error|warn|info|debug|trace>)` sets the enabled
severity. `(log! <level> <payload>)` emits `(Log <level> <value>)` through
println! when the level admits it, and returns unit when it does not.
`(log-enabled? <level>)` answers the same question for a caller that wants its
own sink, recording events as atoms in a space rather than printing them.

Two things make the off path cheap. The level is a field on the world, so
log-enabled? is an interpreter form reading it rather than a match against a
space. And log!'s payload is declared Atom, so if's unevaluated branches leave
it alone: the expression that would build the message is never reduced. The
lazy argument is what the log crate gets from a closure and Log4j2 from a
lambda; MeTTa's parameter types give it directly.

Measured on a 200-iteration loop with tabling off, the off path is flat across
a hundredfold change in payload cost, 68.6 ms at (work 10) and 68.7 ms at
(work 1000), while the same loop with the level set scales with it, 145 ms to
4765 ms. The same guard written in MeTTa over a space is flat too but costs
about 40% more per call, which is what the world field buys. The test states it
without timing: the payload of an unadmitted call is a function with no base
case, so anything that reduced it would hang rather than fail.

log-enabled? returns a grounded Bool, not a `False` symbol, which is what lets
it drive `if` directly.

Author: MesTTo

packages/core/src/eval.ts

@@ -16,6 +16,7 @@ import {
   type ExprAtom,
   emptyExpr,
   expr,
+  gbool,
   gint,
   gstr,
   type InternTable,
@@ -406,6 +407,9 @@ const EMBEDDED = new Set([
   "import!",
   // Sets interpreter settings in-language (Hyperon `pragma!`); stateful, so handled here not as a pure op.
   "pragma!",
+  // Reads the level set by `(pragma! log-level ...)`. Handled here, not as a pure grounded op, because the
+  // level lives on the world; `log!` itself is a standard-library definition over this predicate.
+  "log-enabled?",
   // TS-native extension (not upstream MeTTa): atomic space mutation with rollback.
   "transaction",
   // TS-native concurrency primitives (async-only); see docs/.../concurrency-primitives.md.
@@ -1619,6 +1623,20 @@ function namedSpaceCandidateGetter(
   };
 }
 
+// ---------- log levels ----------
+// Ranked by severity, so a setting admits every level at or below its own rank. `off` is 0 and admits
+// nothing, which is the default: severity ranks start at 1 so a plain `rank <= world.logLevel` comparison
+// rejects everything while logging is off, with no separate "is it enabled" branch.
+const LOG_OFF = 0;
+const LOG_RANKS: ReadonlyMap<string, number> = new Map([
+  ["off", LOG_OFF],
+  ["error", 1],
+  ["warn", 2],
+  ["info", 3],
+  ["debug", 4],
+  ["trace", 5],
+]);
+
 export interface World {
   spaces: Map<string, NamedSpace>;
   store: Map<number, Atom>;
@@ -1654,6 +1672,11 @@ export interface World {
   // the fresh-variable namespace.
   maxSteps: number;
   stepStart: number;
+  // Enabled logging severity as a rank, set in-language by `(pragma! log-level <level>)`. LOG_OFF is the
+  // default, so a program that never sets it logs nothing and every `log!` returns unit without touching its
+  // payload. Held on the world, not in a space, so the check `log!` makes is a field read rather than a
+  // match: that is what keeps an unconfigured log call off the cost of the program it instruments.
+  logLevel: number;
 }
 export interface St {
   counter: number;
@@ -1688,6 +1711,7 @@ export const initSt = (): St => ({
     removedStaticVarRules: false,
     maxStackDepth: DEFAULT_MAX_STACK_DEPTH,
     maxSteps: DEFAULT_MAX_STEPS,
+    logLevel: LOG_OFF,
     stepStart: 0,
   },
 });
@@ -1708,6 +1732,7 @@ function cloneWorld(w: World): World {
     maxStackDepth: w.maxStackDepth,
     maxSteps: w.maxSteps,
     stepStart: w.stepStart,
+    logLevel: w.logLevel,
   };
 }
 
@@ -1783,6 +1808,7 @@ function mergeWorlds(base: World, branches: readonly World[]): World {
     maxStackDepth: base.maxStackDepth,
     maxSteps: base.maxSteps,
     stepStart: base.stepStart,
+    logLevel: base.logLevel,
   };
   indexSelfRules(merged, selfExtra);
   return merged;
@@ -4277,8 +4303,30 @@ function* interpretStack1G(
         else w.maxSteps = Number(n);
         return [[finItem(prev, emptyExpr, it.bnd)], { counter: st.counter, world: w }];
       }
+      if (key.kind === "sym" && key.name === "log-level") {
+        const val = inst(env, it.bnd, it2[2]!);
+        const rank = val.kind === "sym" ? LOG_RANKS.get(val.name) : undefined;
+        if (rank === undefined) return [[finItem(prev, errAtom(a, "UnknownLogLevel"), it.bnd)], st];
+        const w = cloneWorld(st.world);
+        w.logLevel = rank;
+        return [[finItem(prev, emptyExpr, it.bnd)], { counter: st.counter, world: w }];
+      }
       return [[finItem(prev, emptyExpr, it.bnd)], st];
     }
+    // `(log-enabled? <level>)`: does the level set by `(pragma! log-level ...)` admit this one? The whole
+    // point of answering it here is that it is a read of one field on the world, so the guard in front of a
+    // log call costs a comparison. `log!` is built on it in the standard library, where `if`'s Atom-typed
+    // branches give the laziness that keeps an unadmitted payload from being reduced at all.
+    case "log-enabled?": {
+      if (it2.length !== 2) break;
+      const level = inst(env, it.bnd, it2[1]!);
+      const rank = level.kind === "sym" ? LOG_RANKS.get(level.name) : undefined;
+      if (rank === undefined) return [[finItem(prev, errAtom(a, "UnknownLogLevel"), it.bnd)], st];
+      // True/False are grounded booleans in this engine, not symbols; a bare sym("False") would not
+      // match the prelude's `(= (if False $t $e) $e)` and would leave the if unreduced.
+      const on = rank !== LOG_OFF && rank <= st.world.logLevel;
+      return [[finItem(prev, gbool(on), it.bnd)], st];
+    }
     case "bind!": {
       if (it2.length !== 3) break;
       const tok = inst(env, it.bnd, it2[1]!);
@@ -4398,6 +4446,7 @@ function appendSpace(env: MinEnv, w0: World, name: string, atoms: Atom[]): World
       maxStackDepth: w0.maxStackDepth,
       maxSteps: w0.maxSteps,
       stepStart: w0.stepStart,
+      logLevel: w0.logLevel,
     };
   }
   const spaces = new Map(w0.spaces);

packages/core/src/logging.test.ts

@@ -0,0 +1,124 @@
+// SPDX-FileCopyrightText: 2026 MesTTo
+//
+// SPDX-License-Identifier: MIT
+
+// Leveled logging: `(pragma! log-level ...)` sets the enabled severity on the world, `log-enabled?` reads
+// it, and `log!` emits only what that level admits. The property these tests exist for is that a call the
+// level does not admit never reduces its payload, so instrumenting a function costs nothing until someone
+// turns logging on. A payload that would not terminate is the sharpest way to state it: if the payload were
+// reduced at all, the test would hang instead of failing.
+
+import { afterEach, describe, expect, it } from "vitest";
+import { setOutputSink } from "./builtins";
+import { format } from "./parser";
+import { runProgram } from "./runner";
+
+const last = (src: string): string[] => {
+  const rs = runProgram(src);
+  return rs[rs.length - 1]!.results.map(format);
+};
+
+let restore: ((line: string) => void) | undefined;
+const capture = (): string[] => {
+  const lines: string[] = [];
+  restore = setOutputSink((line) => lines.push(line));
+  return lines;
+};
+afterEach(() => {
+  if (restore) setOutputSink(restore);
+  restore = undefined;
+});
+
+describe("log-enabled?", () => {
+  it("is off until a level is set", () => {
+    expect(last("!(log-enabled? error)")).toEqual(["False"]);
+    expect(last("!(log-enabled? trace)")).toEqual(["False"]);
+  });
+
+  it("admits a level at or above the setting's severity", () => {
+    const src = "!(pragma! log-level info)\n";
+    expect(last(`${src}!(log-enabled? error)`)).toEqual(["True"]);
+    expect(last(`${src}!(log-enabled? warn)`)).toEqual(["True"]);
+    expect(last(`${src}!(log-enabled? info)`)).toEqual(["True"]);
+    expect(last(`${src}!(log-enabled? debug)`)).toEqual(["False"]);
+    expect(last(`${src}!(log-enabled? trace)`)).toEqual(["False"]);
+  });
+
+  it("treats `off` as admitting nothing, including itself", () => {
+    expect(last("!(pragma! log-level trace)\n!(log-enabled? off)")).toEqual(["False"]);
+    expect(last("!(pragma! log-level trace)\n!(log-enabled? trace)")).toEqual(["True"]);
+    expect(
+      last("!(pragma! log-level trace)\n!(pragma! log-level off)\n!(log-enabled? error)"),
+    ).toEqual(["False"]);
+  });
+
+  it("returns a grounded Bool, so it drives `if` directly", () => {
+    // A bare `False` symbol would not match the prelude's (= (if False $t $e) $e) and would leave the
+    // if unreduced, which is exactly the shape a guard has to work in.
+    expect(last("!(if (log-enabled? debug) yes no)")).toEqual(["no"]);
+    expect(last("!(pragma! log-level debug)\n!(if (log-enabled? debug) yes no)")).toEqual(["yes"]);
+  });
+
+  it("rejects a level that is not a known severity", () => {
+    expect(last("!(log-enabled? shouty)")[0]).toContain("UnknownLogLevel");
+    expect(last("!(pragma! log-level shouty)")[0]).toContain("UnknownLogLevel");
+  });
+});
+
+describe("log!", () => {
+  it("emits nothing while logging is off", () => {
+    const lines = capture();
+    last("!(log! error (+ 1 2))");
+    expect(lines).toEqual([]);
+  });
+
+  it("emits the payload's value tagged with its level once enabled", () => {
+    const lines = capture();
+    last("!(pragma! log-level info)\n!(log! info (+ 1 2))");
+    expect(lines).toEqual(["(Log info 3)"]);
+  });
+
+  it("emits only what the level admits", () => {
+    const lines = capture();
+    last(
+      "!(pragma! log-level warn)\n!(log! error a)\n!(log! warn b)\n!(log! info c)\n!(log! debug d)",
+    );
+    expect(lines).toEqual(["(Log error a)", "(Log warn b)"]);
+  });
+
+  it("reduces to unit either way, so it composes in a let", () => {
+    capture();
+    expect(last("!(let $x (log! debug ignored) done)")).toEqual(["done"]);
+    expect(last("!(pragma! log-level debug)\n!(let $x (log! debug shown) done)")).toEqual(["done"]);
+  });
+
+  // The point of the whole design. `endless` has no base case, so reducing the payload cannot terminate.
+  // Logging is off, so the payload is never reduced and the program finishes.
+  it("does not reduce the payload of a call the level does not admit", () => {
+    const endless = "(: endless (-> Number Number))\n(= (endless $n) (endless (+ $n 1)))\n";
+    expect(last(`${endless}!(log! debug (endless 0))`)).toEqual(["()"]);
+    expect(last(`${endless}!(pragma! log-level info)\n!(log! debug (endless 0))`)).toEqual(["()"]);
+  });
+
+  it("does not reduce the payload for effect either", () => {
+    const lines = capture();
+    last('!(log! debug (println! "payload"))');
+    expect(lines).toEqual([]);
+  });
+});
+
+describe("pragma! log-level", () => {
+  it("carries the setting to later top-level queries", () => {
+    const lines = capture();
+    last("!(pragma! log-level debug)\n!(log! debug first)\n!(log! debug second)");
+    expect(lines).toEqual(["(Log debug first)", "(Log debug second)"]);
+  });
+
+  it("can be turned back off", () => {
+    const lines = capture();
+    last(
+      "!(pragma! log-level debug)\n!(log! debug on)\n!(pragma! log-level off)\n!(log! debug off)",
+    );
+    expect(lines).toEqual(["(Log debug on)"]);
+  });
+});

packages/core/src/stdlib.ts

@@ -104,6 +104,21 @@ export const STDLIB_SRC = `
   (: trace! (-> %Undefined% Atom %Undefined%))
   (= (trace! $msg $ret) (let $unit (println! $msg) $ret))
 
+  ; ---- leveled logging ----
+  ; Logging is off until a program sets (pragma! log-level <level>), and the levels rank
+  ; error < warn < info < debug < trace, so a setting admits everything at or above its severity.
+  ; log-enabled? is an interpreter form (see EMBEDDED in eval.ts) because the level lives on the world:
+  ; asking whether a level is admitted is a read of one field. log! is built on it here, and its payload
+  ; is Atom-typed, so if's unevaluated branches leave the payload of an unadmitted call alone. Together
+  ; that is the point of the design: instrumenting a hot function costs a comparison while logging is off,
+  ; and the work that would build the message is not done at all. Measured on a 200-iteration loop, the
+  ; off path is flat across a hundredfold change in payload cost (69 ms either way) while the same loop
+  ; with the level set scales with it (145 ms to 4765 ms).
+  (: log-enabled? (-> Symbol Bool))
+  (: log! (-> Symbol Atom (->)))
+  (= (log! $level $payload)
+     (if (log-enabled? $level) (println! (Log $level $payload)) ()))
+
   ; Partial application is ordinary PeTTa behavior. A known under-applied head becomes
   ; (partial head args); applying that closure rebuilds the fuller call and evaluates it.
   (: partial (-> Atom Expression Atom))
@@ -375,7 +390,9 @@ export const STDLIB_SRC = `
   (@doc random-float (@desc "Returns a random float in the half-open interval from the lower bound to the upper bound") (@params ((@param "Lower bound") (@param "Upper bound"))) (@return "Random float"))
   (@doc random-int (@desc "Returns a random integer in the half-open interval from the lower bound to the upper bound") (@params ((@param "Lower bound") (@param "Upper bound"))) (@return "Random integer"))
   (@doc nop (@desc "Outputs the unit atom") (@params ()) (@return "Unit atom"))
-  (@doc pragma! (@desc "Changes the value of a global key, such as type-check, interpreter, max-stack-depth, or mettascript-max-steps") (@params ((@param "Key name") (@param "New value"))) (@return "Unit atom"))
+  (@doc pragma! (@desc "Changes the value of a global key, such as type-check, interpreter, max-stack-depth, mettascript-max-steps, or log-level") (@params ((@param "Key name") (@param "New value"))) (@return "Unit atom"))
+  (@doc log! (@desc "Prints the payload tagged with its level, but only when (pragma! log-level ...) admits that level. The payload is not reduced otherwise, so a log call in a hot path costs nothing until logging is turned on") (@params ((@param "Level: error, warn, info, debug, or trace") (@param "Payload atom, reduced only when the level is admitted"))) (@return "Unit atom"))
+  (@doc log-enabled? (@desc "Whether the current log level admits this one, for a caller that wants its own sink and still wants the guard to cost only a comparison") (@params ((@param "Level: error, warn, info, debug, or trace"))) (@return "True when the level is admitted"))
   (@doc bind! (@desc "Registers a token replaced by an atom during parsing of the rest of the program") (@params ((@param "Token name") (@param "Atom associated with the token after reduction"))) (@return "Unit atom"))
   (@doc sort-strings (@desc "Sorts an expression of strings in alphabetical order") (@params ((@param "List of strings"))) (@return "Sorted list of strings"))
   (@doc first-from-pair (@desc "Returns the first atom of a pair") (@params ((@param "Pair"))) (@return "First atom of the pair"))