flocc 0.5.22 → 0.5.23

package/dist/flocc.es.js

@@ -817,7 +817,37 @@ var Operators;
     Operators["agent"] = "agent";
     Operators["environment"] = "environment";
     Operators["vector"] = "vector";
+    Operators["log"] = "log";
 })(Operators || (Operators = {}));
+var operatorInfo = {
+    add: { min: 2, max: 2 },
+    subtract: { min: 2, max: 2 },
+    multiply: { min: 2, max: 2 },
+    divide: { min: 2, max: 2 },
+    mod: { min: 2, max: 2 },
+    power: { min: 2, max: 2 },
+    get: { min: 1, max: 1 },
+    set: { min: 2, max: 2 },
+    enqueue: { min: 2, max: 2 },
+    local: { min: 1, max: 2 },
+    if: { min: 2, max: 3 },
+    and: { min: 2, max: 2 },
+    or: { min: 2, max: 2 },
+    gt: { min: 2, max: 2 },
+    gte: { min: 2, max: 2 },
+    lt: { min: 2, max: 2 },
+    lte: { min: 2, max: 2 },
+    eq: { min: 2, max: 2 },
+    map: { min: 2, max: 2 },
+    filter: { min: 2, max: 2 },
+    key: { min: 2, max: 2 },
+    method: { min: 2, max: Infinity },
+    agent: { min: 0, max: 0 },
+    environment: { min: 0, max: 0 },
+    vector: { min: 1, max: Infinity },
+    log: { min: 1, max: Infinity }
+};
+var ARITHMETIC_OPS = new Set(["add", "subtract", "multiply", "divide", "mod", "power"]);
 var add = function (a, b) { return a + b; };
 var subtract = function (a, b) { return a - b; };
 var multiply = function (a, b) { return a * b; };
@@ -841,6 +871,127 @@ var method = function (obj, name) {
         return null;
     return obj[name].apply(obj, args);
 };
+/**
+ * Format a single value for step display. If isFirst is true and the value is
+ * a known operator string, render it bare (unquoted).
+ */
+function formatStepValue(val, isFirst) {
+    if (val === null || val === undefined)
+        return String(val);
+    if (typeof val === "number" || typeof val === "boolean")
+        return String(val);
+    if (typeof val === "string") {
+        if (isFirst && val in Operators)
+            return val;
+        return JSON.stringify(val);
+    }
+    if (val instanceof Array) {
+        if (val.length === 0)
+            return "[]";
+        var parts = val.map(function (s, i) { return formatStepValue(s, i === 0); });
+        return "(" + parts.join(" ") + ")";
+    }
+    if (typeof val === "object") {
+        try {
+            return JSON.stringify(val);
+        }
+        catch (_a) {
+            return String(val);
+        }
+    }
+    return String(val);
+}
+/**
+ * Format a step into a readable string representation for logging.
+ */
+function formatStep(step) {
+    return formatStepValue(step, false);
+}
+/**
+ * Format a value as an S-expression atom (no recursion into arrays).
+ */
+function formatAtom(val) {
+    if (val === null || val === undefined)
+        return "null";
+    if (typeof val === "number" || typeof val === "boolean")
+        return String(val);
+    if (typeof val === "string")
+        return JSON.stringify(val);
+    if (typeof val === "object" && !Array.isArray(val)) {
+        try {
+            return JSON.stringify(val);
+        }
+        catch (_a) {
+            return "[object]";
+        }
+    }
+    return String(val);
+}
+/**
+ * Format a value for S-expression display. The first element (operator) of
+ * a step is rendered as a bare identifier; other string values are quoted.
+ */
+function formatSexpValue(val, isOperator) {
+    if (isOperator && typeof val === "string")
+        return val;
+    return formatAtom(val);
+}
+/**
+ * Pretty-print a single step as an S-expression with width-based wrapping.
+ */
+function prettyFormatStep(step, indentUnit, maxLineWidth, currentIndent) {
+    if (!Array.isArray(step))
+        return formatAtom(step);
+    if (step.length === 0)
+        return "()";
+    // Try compact first
+    var compact = "(" + step.map(function (s, i) {
+        if (Array.isArray(s))
+            return prettyFormatStep(s, indentUnit, Infinity, "");
+        return formatSexpValue(s, i === 0);
+    }).join(" ") + ")";
+    if (currentIndent.length + compact.length <= maxLineWidth)
+        return compact;
+    // Wrap: operator on first line, each arg indented
+    var op = Array.isArray(step[0]) ? prettyFormatStep(step[0], indentUnit, maxLineWidth, currentIndent) : formatSexpValue(step[0], true);
+    var args = step.slice(1);
+    if (args.length === 0)
+        return "(" + op + ")";
+    var childIndent = currentIndent + indentUnit;
+    var formattedArgs = args.map(function (a) { return prettyFormatStep(a, indentUnit, maxLineWidth, childIndent); });
+    return "(" + op + "\n" + formattedArgs.map(function (a) { return childIndent + a; }).join("\n") + ")";
+}
+function validOperatorNames() {
+    return Object.keys(operatorInfo).join(", ");
+}
+function checkArity(op, argCount, strict) {
+    if (strict === void 0) { strict = false; }
+    var info = operatorInfo[op];
+    if (!info)
+        return null;
+    if (info.min === info.max) {
+        if (argCount < info.min) {
+            return "Rule: \"" + op + "\" expects " + info.min + " argument" + (info.min !== 1 ? "s" : "") + ", got " + argCount;
+        }
+        if (strict && argCount > info.max) {
+            return "Rule: \"" + op + "\" expects " + info.min + " argument" + (info.min !== 1 ? "s" : "") + ", got " + argCount;
+        }
+    }
+    else if (info.max === Infinity) {
+        if (argCount < info.min) {
+            return "Rule: \"" + op + "\" expects at least " + info.min + " argument" + (info.min !== 1 ? "s" : "") + ", got " + argCount;
+        }
+    }
+    else {
+        if (argCount < info.min) {
+            return "Rule: \"" + op + "\" expects " + info.min + "-" + info.max + " arguments, got " + argCount;
+        }
+        if (strict && argCount > info.max) {
+            return "Rule: \"" + op + "\" expects " + info.min + "-" + info.max + " arguments, got " + argCount;
+        }
+    }
+    return null;
+}
 /**
  * The `Rule` class is an experimental interface for adding behavior to {@linkcode Agent}s. A `Rule` object may be used in place of a `tick` function to be added as `Agent` behavior using `agent.set('tick', tickRule)`. As a trivial example, consider the following `Rule`, which increments the `Agent`'s `x` value with every time step:
  *
@@ -895,6 +1046,7 @@ var Rule = /** @class */ (function () {
      * |`"agent"`|`0`|No arguments; returns the `Agent`|
      * |`"environment"`|`0`|No arguments, returns the `Environment`|
      * |`"vector"`|`any`|Creates an n-dimensional {@linkcode Vector} from the supplied arguments|
+     * |`"log"`|`any`|Logs expression(s) and returns the last evaluated value|
      */
     function Rule(environment, steps) {
         var _this = this;
@@ -903,10 +1055,12 @@ var Rule = /** @class */ (function () {
         /** @hidden */
         this.locals = {};
         /**
-         * interpret single array step
-         * @since 0.3.0
-         * @hidden
+         * When true, evaluation traces are logged and captured.
          */
+        this.trace = false;
+        this.traceLog = [];
+        /** @hidden */
+        this._traceDepth = 0;
         this.evaluate = function (agent, step) {
             var first = step && step.length > 0 ? step[0] : null;
             if (first === undefined || first === null)
@@ -917,30 +1071,79 @@ var Rule = /** @class */ (function () {
                     return _this.evaluate(agent, step.slice(1));
                 return innerStep;
             }
-            if (first === "log") {
-                console.log("logging", step.slice(1), _this.evaluate(agent, step.slice(1)));
-                return null;
+            // Trace: check if this is a known operator call to trace
+            var shouldTrace = _this.trace && typeof first === "string" && first in Operators;
+            if (shouldTrace)
+                _this._traceDepth++;
+            var result = _this._evaluateOp(agent, step, first);
+            if (shouldTrace) {
+                _this._traceLogEntry(step, result);
+                _this._traceDepth--;
+            }
+            return result;
+        };
+        /** @hidden */
+        this._evaluateOp = function (agent, step, first) {
+            if (first === Operators.log) {
+                var args = step.slice(1);
+                if (args.length === 0) {
+                    console.warn("Rule: \"log\" expects at least 1 argument, got 0");
+                    return null;
+                }
+                var lastValue = null;
+                for (var i = 0; i < args.length; i++) {
+                    var expr = args[i];
+                    var evaluated = _this.evaluate(agent, [expr]);
+                    console.log("Rule log: " + formatStep(expr) + " \u2192 " + formatStep(evaluated));
+                    lastValue = evaluated;
+                }
+                return lastValue;
             }
             if (!(first in Operators) && step.length > 1) {
+                if (typeof first === "string") {
+                    console.warn("Rule: unknown operator \"" + first + "\". Valid operators: " + validOperatorNames());
+                }
                 return step;
             }
+            var argCount = step.length - 1;
+            // Arity check at runtime for known operators
+            if (typeof first === "string" && first in Operators) {
+                var arityMsg = checkArity(first, argCount);
+                if (arityMsg) {
+                    console.warn(arityMsg);
+                }
+            }
             var a = step.length > 1 ? [step[1]] : undefined;
             var b = step.length > 2 ? [step[2]] : undefined;
             var c = step.length > 3 ? [step[3]] : undefined;
-            if (first === Operators.add)
-                return add(_this.evaluate(agent, a), _this.evaluate(agent, b));
-            if (first === Operators.subtract)
-                return subtract(_this.evaluate(agent, a), _this.evaluate(agent, b));
-            if (first === Operators.multiply)
-                return multiply(_this.evaluate(agent, a), _this.evaluate(agent, b));
-            if (first === Operators.divide)
-                return divide(_this.evaluate(agent, a), _this.evaluate(agent, b));
-            if (first === Operators.mod)
-                return mod(_this.evaluate(agent, a), _this.evaluate(agent, b));
-            if (first === Operators.power)
-                return power(_this.evaluate(agent, a), _this.evaluate(agent, b));
-            if (first === Operators.get)
-                return get(agent, _this.evaluate(agent, a));
+            // Arithmetic operators with type checking
+            if (ARITHMETIC_OPS.has(first)) {
+                var va = _this.evaluate(agent, a);
+                var vb = _this.evaluate(agent, b);
+                if (typeof va !== "number" || typeof vb !== "number") {
+                    console.warn("Rule: \"" + first + "\" expects numeric arguments, got " + typeof va + " and " + typeof vb);
+                }
+                if (first === Operators.add)
+                    return add(va, vb);
+                if (first === Operators.subtract)
+                    return subtract(va, vb);
+                if (first === Operators.multiply)
+                    return multiply(va, vb);
+                if (first === Operators.divide)
+                    return divide(va, vb);
+                if (first === Operators.mod)
+                    return mod(va, vb);
+                if (first === Operators.power)
+                    return power(va, vb);
+            }
+            if (first === Operators.get) {
+                var keyName = _this.evaluate(agent, a);
+                var result = get(agent, keyName);
+                if (result === null || result === undefined) {
+                    console.warn("Rule: \"get\" returned null for key \"" + keyName + "\" \u2014 key may not exist on agent");
+                }
+                return result;
+            }
             if (first === Operators.set)
                 return set(agent, _this.evaluate(agent, a), _this.evaluate(agent, b));
             if (first === Operators.enqueue) {
@@ -1028,13 +1231,151 @@ var Rule = /** @class */ (function () {
         this.environment = environment;
         this.steps = steps;
     }
+    /**
+     * Format arbitrary steps as pretty-printed S-expressions.
+     */
+    Rule.formatSteps = function (steps, options) {
+        var indent = (options && options.indent) || "  ";
+        var maxLineWidth = (options && options.maxLineWidth) || 60;
+        // Check if it's multi-step (array of arrays)
+        var isMultiStep = steps.length > 0 && Array.isArray(steps[0]);
+        if (isMultiStep) {
+            return steps.map(function (s) { return prettyFormatStep(s, indent, maxLineWidth, ""); }).join("\n\n");
+        }
+        return prettyFormatStep(steps, indent, maxLineWidth, "");
+    };
+    /**
+     * Pretty-print the rule's step tree as S-expressions.
+     */
+    Rule.prototype.format = function (options) {
+        return Rule.formatSteps(this.steps, options);
+    };
+    /**
+     * Returns a formatted S-expression representation of the rule.
+     */
+    Rule.prototype.toString = function () {
+        return this.format();
+    };
+    /**
+     * Validate the rule's step tree and return an array of diagnostics.
+     * Does not throw — returns diagnostics for inspection.
+     * @since 0.6.0
+     */
+    Rule.prototype.validate = function () {
+        var diagnostics = [];
+        if (!this.steps || (Array.isArray(this.steps) && this.steps.length === 0)) {
+            diagnostics.push({
+                path: "root",
+                level: "warning",
+                message: "Empty steps array"
+            });
+            return diagnostics;
+        }
+        // Check if steps is a single step (first element is a string operator)
+        // or an array of steps (first element is an array)
+        var isMultiStep = Array.isArray(this.steps[0]);
+        if (isMultiStep) {
+            // Multiple top-level steps
+            for (var i = 0; i < this.steps.length; i++) {
+                var step = this.steps[i];
+                if (!Array.isArray(step)) {
+                    diagnostics.push({
+                        path: "[" + i + "]",
+                        level: "warning",
+                        message: "Step is a bare value (" + typeof step + ": " + JSON.stringify(step) + ") instead of an array"
+                    });
+                }
+                else {
+                    this._validateStep(step, "[" + i + "]", diagnostics);
+                }
+            }
+        }
+        else {
+            // Single step (the steps array IS the step)
+            this._validateStep(this.steps, "root", diagnostics);
+        }
+        return diagnostics;
+    };
+    /** @hidden */
+    Rule.prototype._validateStep = function (step, path, diagnostics) {
+        if (step.length === 0) {
+            diagnostics.push({
+                path: path,
+                level: "warning",
+                message: "Empty step array"
+            });
+            return;
+        }
+        var first = step[0];
+        // If first element is an array, it's a nested step sequence
+        if (Array.isArray(first)) {
+            this._validateStep(first, path + "[0]", diagnostics);
+            for (var i = 1; i < step.length; i++) {
+                if (Array.isArray(step[i])) {
+                    this._validateStep(step[i], path + ("[" + i + "]"), diagnostics);
+                }
+            }
+            return;
+        }
+        if (typeof first === "string") {
+            var argCount = step.length - 1;
+            // Check if operator is known
+            if (!(first in Operators)) {
+                if (step.length > 1) {
+                    diagnostics.push({
+                        path: path,
+                        level: "error",
+                        message: "Unknown operator \"" + first + "\". Valid operators: " + validOperatorNames()
+                    });
+                }
+                return;
+            }
+            // Check arity (strict: also warn on too many args)
+            var arityMsg = checkArity(first, argCount, true);
+            if (arityMsg) {
+                diagnostics.push({
+                    path: path,
+                    level: "error",
+                    message: arityMsg
+                });
+            }
+            // Recurse into sub-steps
+            for (var i = 1; i < step.length; i++) {
+                if (Array.isArray(step[i])) {
+                    this._validateStep(step[i], path + ("[" + i + "]"), diagnostics);
+                }
+            }
+        }
+    };
+    /**
+     * interpret single array step
+     * @since 0.3.0
+     * @hidden
+     */
+    /** @hidden */
+    Rule.prototype._traceLogEntry = function (step, result) {
+        var indent = "  ".repeat(this._traceDepth - 1);
+        var formatted = formatStep(step);
+        var resultFormatted = formatStep(result);
+        var line = "Rule trace: " + indent + formatted + " \u2192 " + resultFormatted;
+        console.log(line);
+        this.traceLog.push(line);
+    };
     /**
      * @since 0.3.0
      * @hidden
      */
     Rule.prototype.call = function (agent) {
+        if (this.trace) {
+            this.traceLog = [];
+            this._traceDepth = 0;
+        }
         return this.evaluate(agent, this.steps);
     };
+    /**
+     * Static operator info mapping operator names to their expected argument counts.
+     */
+    Rule.operatorInfo = operatorInfo;
     return Rule;
 }());
 
@@ -5526,6 +5867,6 @@ var Heatmap = /** @class */ (function (_super) {
 /**
  * The current version of the Flocc library.
  */
-var version = "0.5.22";
+var version = "0.5.23";
 
 export { ASCIIRenderer, Agent, CanvasRenderer, Colors, Environment, GridEnvironment, Heatmap, Histogram, KDTree, LineChartRenderer, Network, NumArray, Rule, TableRenderer, Terrain, version as VERSION, Vector, utils };

package/dist/flocc.js

@@ -823,7 +823,37 @@
         Operators["agent"] = "agent";
         Operators["environment"] = "environment";
         Operators["vector"] = "vector";
+        Operators["log"] = "log";
     })(Operators || (Operators = {}));
+    var operatorInfo = {
+        add: { min: 2, max: 2 },
+        subtract: { min: 2, max: 2 },
+        multiply: { min: 2, max: 2 },
+        divide: { min: 2, max: 2 },
+        mod: { min: 2, max: 2 },
+        power: { min: 2, max: 2 },
+        get: { min: 1, max: 1 },
+        set: { min: 2, max: 2 },
+        enqueue: { min: 2, max: 2 },
+        local: { min: 1, max: 2 },
+        if: { min: 2, max: 3 },
+        and: { min: 2, max: 2 },
+        or: { min: 2, max: 2 },
+        gt: { min: 2, max: 2 },
+        gte: { min: 2, max: 2 },
+        lt: { min: 2, max: 2 },
+        lte: { min: 2, max: 2 },
+        eq: { min: 2, max: 2 },
+        map: { min: 2, max: 2 },
+        filter: { min: 2, max: 2 },
+        key: { min: 2, max: 2 },
+        method: { min: 2, max: Infinity },
+        agent: { min: 0, max: 0 },
+        environment: { min: 0, max: 0 },
+        vector: { min: 1, max: Infinity },
+        log: { min: 1, max: Infinity }
+    };
+    var ARITHMETIC_OPS = new Set(["add", "subtract", "multiply", "divide", "mod", "power"]);
     var add = function (a, b) { return a + b; };
     var subtract = function (a, b) { return a - b; };
     var multiply = function (a, b) { return a * b; };
@@ -847,6 +877,127 @@
             return null;
         return obj[name].apply(obj, args);
     };
+    /**
+     * Format a single value for step display. If isFirst is true and the value is
+     * a known operator string, render it bare (unquoted).
+     */
+    function formatStepValue(val, isFirst) {
+        if (val === null || val === undefined)
+            return String(val);
+        if (typeof val === "number" || typeof val === "boolean")
+            return String(val);
+        if (typeof val === "string") {
+            if (isFirst && val in Operators)
+                return val;
+            return JSON.stringify(val);
+        }
+        if (val instanceof Array) {
+            if (val.length === 0)
+                return "[]";
+            var parts = val.map(function (s, i) { return formatStepValue(s, i === 0); });
+            return "(" + parts.join(" ") + ")";
+        }
+        if (typeof val === "object") {
+            try {
+                return JSON.stringify(val);
+            }
+            catch (_a) {
+                return String(val);
+            }
+        }
+        return String(val);
+    }
+    /**
+     * Format a step into a readable string representation for logging.
+     */
+    function formatStep(step) {
+        return formatStepValue(step, false);
+    }
+    /**
+     * Format a value as an S-expression atom (no recursion into arrays).
+     */
+    function formatAtom(val) {
+        if (val === null || val === undefined)
+            return "null";
+        if (typeof val === "number" || typeof val === "boolean")
+            return String(val);
+        if (typeof val === "string")
+            return JSON.stringify(val);
+        if (typeof val === "object" && !Array.isArray(val)) {
+            try {
+                return JSON.stringify(val);
+            }
+            catch (_a) {
+                return "[object]";
+            }
+        }
+        return String(val);
+    }
+    /**
+     * Format a value for S-expression display. The first element (operator) of
+     * a step is rendered as a bare identifier; other string values are quoted.
+     */
+    function formatSexpValue(val, isOperator) {
+        if (isOperator && typeof val === "string")
+            return val;
+        return formatAtom(val);
+    }
+    /**
+     * Pretty-print a single step as an S-expression with width-based wrapping.
+     */
+    function prettyFormatStep(step, indentUnit, maxLineWidth, currentIndent) {
+        if (!Array.isArray(step))
+            return formatAtom(step);
+        if (step.length === 0)
+            return "()";
+        // Try compact first
+        var compact = "(" + step.map(function (s, i) {
+            if (Array.isArray(s))
+                return prettyFormatStep(s, indentUnit, Infinity, "");
+            return formatSexpValue(s, i === 0);
+        }).join(" ") + ")";
+        if (currentIndent.length + compact.length <= maxLineWidth)
+            return compact;
+        // Wrap: operator on first line, each arg indented
+        var op = Array.isArray(step[0]) ? prettyFormatStep(step[0], indentUnit, maxLineWidth, currentIndent) : formatSexpValue(step[0], true);
+        var args = step.slice(1);
+        if (args.length === 0)
+            return "(" + op + ")";
+        var childIndent = currentIndent + indentUnit;
+        var formattedArgs = args.map(function (a) { return prettyFormatStep(a, indentUnit, maxLineWidth, childIndent); });
+        return "(" + op + "\n" + formattedArgs.map(function (a) { return childIndent + a; }).join("\n") + ")";
+    }
+    function validOperatorNames() {
+        return Object.keys(operatorInfo).join(", ");
+    }
+    function checkArity(op, argCount, strict) {
+        if (strict === void 0) { strict = false; }
+        var info = operatorInfo[op];
+        if (!info)
+            return null;
+        if (info.min === info.max) {
+            if (argCount < info.min) {
+                return "Rule: \"" + op + "\" expects " + info.min + " argument" + (info.min !== 1 ? "s" : "") + ", got " + argCount;
+            }
+            if (strict && argCount > info.max) {
+                return "Rule: \"" + op + "\" expects " + info.min + " argument" + (info.min !== 1 ? "s" : "") + ", got " + argCount;
+            }
+        }
+        else if (info.max === Infinity) {
+            if (argCount < info.min) {
+                return "Rule: \"" + op + "\" expects at least " + info.min + " argument" + (info.min !== 1 ? "s" : "") + ", got " + argCount;
+            }
+        }
+        else {
+            if (argCount < info.min) {
+                return "Rule: \"" + op + "\" expects " + info.min + "-" + info.max + " arguments, got " + argCount;
+            }
+            if (strict && argCount > info.max) {
+                return "Rule: \"" + op + "\" expects " + info.min + "-" + info.max + " arguments, got " + argCount;
+            }
+        }
+        return null;
+    }
     /**
      * The `Rule` class is an experimental interface for adding behavior to {@linkcode Agent}s. A `Rule` object may be used in place of a `tick` function to be added as `Agent` behavior using `agent.set('tick', tickRule)`. As a trivial example, consider the following `Rule`, which increments the `Agent`'s `x` value with every time step:
      *
@@ -901,6 +1052,7 @@
          * |`"agent"`|`0`|No arguments; returns the `Agent`|
          * |`"environment"`|`0`|No arguments, returns the `Environment`|
          * |`"vector"`|`any`|Creates an n-dimensional {@linkcode Vector} from the supplied arguments|
+         * |`"log"`|`any`|Logs expression(s) and returns the last evaluated value|
          */
         function Rule(environment, steps) {
             var _this = this;
@@ -909,10 +1061,12 @@
             /** @hidden */
             this.locals = {};
             /**
-             * interpret single array step
-             * @since 0.3.0
-             * @hidden
+             * When true, evaluation traces are logged and captured.
              */
+            this.trace = false;
+            this.traceLog = [];
+            /** @hidden */
+            this._traceDepth = 0;
             this.evaluate = function (agent, step) {
                 var first = step && step.length > 0 ? step[0] : null;
                 if (first === undefined || first === null)
@@ -923,30 +1077,79 @@
                         return _this.evaluate(agent, step.slice(1));
                     return innerStep;
                 }
-                if (first === "log") {
-                    console.log("logging", step.slice(1), _this.evaluate(agent, step.slice(1)));
-                    return null;
+                // Trace: check if this is a known operator call to trace
+                var shouldTrace = _this.trace && typeof first === "string" && first in Operators;
+                if (shouldTrace)
+                    _this._traceDepth++;
+                var result = _this._evaluateOp(agent, step, first);
+                if (shouldTrace) {
+                    _this._traceLogEntry(step, result);
+                    _this._traceDepth--;
+                }
+                return result;
+            };
+            /** @hidden */
+            this._evaluateOp = function (agent, step, first) {
+                if (first === Operators.log) {
+                    var args = step.slice(1);
+                    if (args.length === 0) {
+                        console.warn("Rule: \"log\" expects at least 1 argument, got 0");
+                        return null;
+                    }
+                    var lastValue = null;
+                    for (var i = 0; i < args.length; i++) {
+                        var expr = args[i];
+                        var evaluated = _this.evaluate(agent, [expr]);
+                        console.log("Rule log: " + formatStep(expr) + " \u2192 " + formatStep(evaluated));
+                        lastValue = evaluated;
+                    }
+                    return lastValue;
                 }
                 if (!(first in Operators) && step.length > 1) {
+                    if (typeof first === "string") {
+                        console.warn("Rule: unknown operator \"" + first + "\". Valid operators: " + validOperatorNames());
+                    }
                     return step;
                 }
+                var argCount = step.length - 1;
+                // Arity check at runtime for known operators
+                if (typeof first === "string" && first in Operators) {
+                    var arityMsg = checkArity(first, argCount);
+                    if (arityMsg) {
+                        console.warn(arityMsg);
+                    }
+                }
                 var a = step.length > 1 ? [step[1]] : undefined;
                 var b = step.length > 2 ? [step[2]] : undefined;
                 var c = step.length > 3 ? [step[3]] : undefined;
-                if (first === Operators.add)
-                    return add(_this.evaluate(agent, a), _this.evaluate(agent, b));
-                if (first === Operators.subtract)
-                    return subtract(_this.evaluate(agent, a), _this.evaluate(agent, b));
-                if (first === Operators.multiply)
-                    return multiply(_this.evaluate(agent, a), _this.evaluate(agent, b));
-                if (first === Operators.divide)
-                    return divide(_this.evaluate(agent, a), _this.evaluate(agent, b));
-                if (first === Operators.mod)
-                    return mod(_this.evaluate(agent, a), _this.evaluate(agent, b));
-                if (first === Operators.power)
-                    return power(_this.evaluate(agent, a), _this.evaluate(agent, b));
-                if (first === Operators.get)
-                    return get(agent, _this.evaluate(agent, a));
+                // Arithmetic operators with type checking
+                if (ARITHMETIC_OPS.has(first)) {
+                    var va = _this.evaluate(agent, a);
+                    var vb = _this.evaluate(agent, b);
+                    if (typeof va !== "number" || typeof vb !== "number") {
+                        console.warn("Rule: \"" + first + "\" expects numeric arguments, got " + typeof va + " and " + typeof vb);
+                    }
+                    if (first === Operators.add)
+                        return add(va, vb);
+                    if (first === Operators.subtract)
+                        return subtract(va, vb);
+                    if (first === Operators.multiply)
+                        return multiply(va, vb);
+                    if (first === Operators.divide)
+                        return divide(va, vb);
+                    if (first === Operators.mod)
+                        return mod(va, vb);
+                    if (first === Operators.power)
+                        return power(va, vb);
+                }
+                if (first === Operators.get) {
+                    var keyName = _this.evaluate(agent, a);
+                    var result = get(agent, keyName);
+                    if (result === null || result === undefined) {
+                        console.warn("Rule: \"get\" returned null for key \"" + keyName + "\" \u2014 key may not exist on agent");
+                    }
+                    return result;
+                }
                 if (first === Operators.set)
                     return set(agent, _this.evaluate(agent, a), _this.evaluate(agent, b));
                 if (first === Operators.enqueue) {
@@ -1034,13 +1237,151 @@
             this.environment = environment;
             this.steps = steps;
         }
+        /**
+         * Format arbitrary steps as pretty-printed S-expressions.
+         */
+        Rule.formatSteps = function (steps, options) {
+            var indent = (options && options.indent) || "  ";
+            var maxLineWidth = (options && options.maxLineWidth) || 60;
+            // Check if it's multi-step (array of arrays)
+            var isMultiStep = steps.length > 0 && Array.isArray(steps[0]);
+            if (isMultiStep) {
+                return steps.map(function (s) { return prettyFormatStep(s, indent, maxLineWidth, ""); }).join("\n\n");
+            }
+            return prettyFormatStep(steps, indent, maxLineWidth, "");
+        };
+        /**
+         * Pretty-print the rule's step tree as S-expressions.
+         */
+        Rule.prototype.format = function (options) {
+            return Rule.formatSteps(this.steps, options);
+        };
+        /**
+         * Returns a formatted S-expression representation of the rule.
+         */
+        Rule.prototype.toString = function () {
+            return this.format();
+        };
+        /**
+         * Validate the rule's step tree and return an array of diagnostics.
+         * Does not throw — returns diagnostics for inspection.
+         * @since 0.6.0
+         */
+        Rule.prototype.validate = function () {
+            var diagnostics = [];
+            if (!this.steps || (Array.isArray(this.steps) && this.steps.length === 0)) {
+                diagnostics.push({
+                    path: "root",
+                    level: "warning",
+                    message: "Empty steps array"
+                });
+                return diagnostics;
+            }
+            // Check if steps is a single step (first element is a string operator)
+            // or an array of steps (first element is an array)
+            var isMultiStep = Array.isArray(this.steps[0]);
+            if (isMultiStep) {
+                // Multiple top-level steps
+                for (var i = 0; i < this.steps.length; i++) {
+                    var step = this.steps[i];
+                    if (!Array.isArray(step)) {
+                        diagnostics.push({
+                            path: "[" + i + "]",
+                            level: "warning",
+                            message: "Step is a bare value (" + typeof step + ": " + JSON.stringify(step) + ") instead of an array"
+                        });
+                    }
+                    else {
+                        this._validateStep(step, "[" + i + "]", diagnostics);
+                    }
+                }
+            }
+            else {
+                // Single step (the steps array IS the step)
+                this._validateStep(this.steps, "root", diagnostics);
+            }
+            return diagnostics;
+        };
+        /** @hidden */
+        Rule.prototype._validateStep = function (step, path, diagnostics) {
+            if (step.length === 0) {
+                diagnostics.push({
+                    path: path,
+                    level: "warning",
+                    message: "Empty step array"
+                });
+                return;
+            }
+            var first = step[0];
+            // If first element is an array, it's a nested step sequence
+            if (Array.isArray(first)) {
+                this._validateStep(first, path + "[0]", diagnostics);
+                for (var i = 1; i < step.length; i++) {
+                    if (Array.isArray(step[i])) {
+                        this._validateStep(step[i], path + ("[" + i + "]"), diagnostics);
+                    }
+                }
+                return;
+            }
+            if (typeof first === "string") {
+                var argCount = step.length - 1;
+                // Check if operator is known
+                if (!(first in Operators)) {
+                    if (step.length > 1) {
+                        diagnostics.push({
+                            path: path,
+                            level: "error",
+                            message: "Unknown operator \"" + first + "\". Valid operators: " + validOperatorNames()
+                        });
+                    }
+                    return;
+                }
+                // Check arity (strict: also warn on too many args)
+                var arityMsg = checkArity(first, argCount, true);
+                if (arityMsg) {
+                    diagnostics.push({
+                        path: path,
+                        level: "error",
+                        message: arityMsg
+                    });
+                }
+                // Recurse into sub-steps
+                for (var i = 1; i < step.length; i++) {
+                    if (Array.isArray(step[i])) {
+                        this._validateStep(step[i], path + ("[" + i + "]"), diagnostics);
+                    }
+                }
+            }
+        };
+        /**
+         * interpret single array step
+         * @since 0.3.0
+         * @hidden
+         */
+        /** @hidden */
+        Rule.prototype._traceLogEntry = function (step, result) {
+            var indent = "  ".repeat(this._traceDepth - 1);
+            var formatted = formatStep(step);
+            var resultFormatted = formatStep(result);
+            var line = "Rule trace: " + indent + formatted + " \u2192 " + resultFormatted;
+            console.log(line);
+            this.traceLog.push(line);
+        };
         /**
          * @since 0.3.0
          * @hidden
          */
         Rule.prototype.call = function (agent) {
+            if (this.trace) {
+                this.traceLog = [];
+                this._traceDepth = 0;
+            }
             return this.evaluate(agent, this.steps);
         };
+        /**
+         * Static operator info mapping operator names to their expected argument counts.
+         */
+        Rule.operatorInfo = operatorInfo;
         return Rule;
     }());
 
@@ -5532,7 +5873,7 @@
     /**
      * The current version of the Flocc library.
      */
-    var version = "0.5.22";
+    var version = "0.5.23";
 
     exports.ASCIIRenderer = ASCIIRenderer;
     exports.Agent = Agent;

package/dist/helpers/Rule.d.ts

@@ -3,6 +3,23 @@ import { Agent } from "../agents/Agent";
 declare type StepToken = number | string | Step;
 interface Step extends Array<StepToken> {
 }
+interface RuleDiagnostic {
+    path: string;
+    level: "error" | "warning";
+    message: string;
+}
+interface RuleFormatOptions {
+    indent?: string;
+    maxLineWidth?: number;
+}
+/**
+ * Operator info: maps operator names to their expected argument counts.
+ * `min` and `max` define the valid range. If `max` is Infinity, the operator is variadic.
+ */
+interface OperatorArity {
+    min: number;
+    max: number;
+}
 /**
  * The `Rule` class is an experimental interface for adding behavior to {@linkcode Agent}s. A `Rule` object may be used in place of a `tick` function to be added as `Agent` behavior using `agent.set('tick', tickRule)`. As a trivial example, consider the following `Rule`, which increments the `Agent`'s `x` value with every time step:
  *
@@ -36,6 +53,23 @@ declare class Rule {
     locals: {
         [key: string]: any;
     };
+    /**
+     * When true, evaluation traces are logged and captured.
+     */
+    trace: boolean;
+    traceLog: string[];
+    /** @hidden */
+    private _traceDepth;
+    /**
+     * Static operator info mapping operator names to their expected argument counts.
+     */
+    static operatorInfo: {
+        [key: string]: OperatorArity;
+    };
+    /**
+     * Format arbitrary steps as pretty-printed S-expressions.
+     */
+    static formatSteps(steps: any[], options?: RuleFormatOptions): string;
     /**
      * A single step may be as simple as `["get", "x"]`. This returns the `Agent`'s `"x"` value to the outer step that contains it. So, for example, the step `["add", 1, ["get", "x"]]`, working from the inside out, retrieves the `"x"` value and then adds `1` to it. More complex steps function similarly, always traversing to the deepest nested step, evaluating it, and 'unwrapping' until all steps have been executed.
      *
@@ -67,18 +101,39 @@ declare class Rule {
      * |`"agent"`|`0`|No arguments; returns the `Agent`|
      * |`"environment"`|`0`|No arguments, returns the `Environment`|
      * |`"vector"`|`any`|Creates an n-dimensional {@linkcode Vector} from the supplied arguments|
+     * |`"log"`|`any`|Logs expression(s) and returns the last evaluated value|
      */
     constructor(environment: Environment, steps: Step[]);
+    /**
+     * Pretty-print the rule's step tree as S-expressions.
+     */
+    format(options?: RuleFormatOptions): string;
+    /**
+     * Returns a formatted S-expression representation of the rule.
+     */
+    toString(): string;
+    /**
+     * Validate the rule's step tree and return an array of diagnostics.
+     * Does not throw — returns diagnostics for inspection.
+     * @since 0.6.0
+     */
+    validate(): RuleDiagnostic[];
+    /** @hidden */
+    private _validateStep;
     /**
      * interpret single array step
      * @since 0.3.0
      * @hidden
      */
+    /** @hidden */
+    private _traceLogEntry;
     evaluate: (agent: Agent, step: any[]) => any;
+    /** @hidden */
+    private _evaluateOp;
     /**
      * @since 0.3.0
      * @hidden
      */
     call(agent: Agent): any;
 }
-export { Rule };
+export { Rule, RuleDiagnostic, RuleFormatOptions };

package/dist/main.d.ts

@@ -1,7 +1,7 @@
 export { Agent } from "./agents/Agent";
 export { Vector } from "./helpers/Vector";
 export { Network } from "./helpers/Network";
-export { Rule } from "./helpers/Rule";
+export { Rule, RuleDiagnostic, RuleFormatOptions } from "./helpers/Rule";
 export { KDTree } from "./helpers/KDTree";
 export { NumArray } from "./helpers/NumArray";
 export { Colors, Terrain } from "./helpers/Terrain";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flocc",
-  "version": "0.5.22",
+  "version": "0.5.23",
   "description": "Agent-based modeling in JavaScript in the browser or server.",
   "main": "dist/flocc.js",
   "module": "dist/flocc.es.js",