@calcit/procs 0.29.0-alpha.3 → 0.29.0-alpha.30

package/lib/calcit.procs.mjs

@@ -3,7 +3,7 @@ export const calcit_version = pkg.version;
 export const calcit_package_json = pkg;
 import { parse } from "@cirru/parser.ts";
 import { writeCirruCode } from "@cirru/writer.ts";
-import { CalcitSymbol, CalcitTag, CalcitRecur, castTag, newTag, refsRegistry, toString, getStringName, compareTagNames, _$n__$e_, hashFunction, } from "./calcit-data.mjs";
+import { CalcitSymbol, CalcitTag, CalcitRecur, castTag, newTag, refsRegistry, toString, format_calcit_number, getStringName, compareTagNames, _$n__$e_, hashFunction, } from "./calcit-data.mjs";
 import { CalcitRef, atom } from "./js-ref.mjs";
 import { CalcitStructValue } from "./js-struct-value.mjs";
 import { CalcitImpl } from "./js-impl.mjs";
@@ -508,7 +508,7 @@ export let defatom = (path, x) => {
     refsRegistry.set(path, v);
     return v;
 };
-export { atom } from "./js-ref.mjs";
+export { atom, ref } from "./js-ref.mjs";
 export let peekDefatom = (path) => {
     return refsRegistry.get(path);
 };
@@ -817,7 +817,7 @@ export let _$n_struct_$o_impl_traits = function (xs, ...traits) {
         throw new Error("&struct:impl-traits expected a struct value");
     const impls = traits.map((trait) => coerce_impl(trait, "&struct:impl-traits"));
     checkRequiredTraitImpls(xs.structRef.impls.concat(impls), "&struct:impl-traits");
-    const nextStruct = new CalcitStructDef(xs.name, xs.fields, xs.structRef.fieldTypes, xs.structRef.impls.concat(impls), xs.structRef.definitionRef);
+    const nextStruct = new CalcitStructDef(xs.name, xs.fields, xs.structRef.fieldTypes, xs.structRef.impls.concat(impls), xs.structRef.definitionRef, xs.structRef.fieldValidators);
     return new CalcitStructValue(xs.name, xs.fields, xs.values, nextStruct);
 };
 export let _$n_struct_def_$o_impl_traits = function (xs, ...traits) {
@@ -828,7 +828,7 @@ export let _$n_struct_def_$o_impl_traits = function (xs, ...traits) {
     const addedImpls = traits.map((trait) => coerce_impl(trait, "&struct-def:impl-traits"));
     const baseImpls = xs.impls ?? [];
     checkRequiredTraitImpls(baseImpls.concat(addedImpls), "&struct-def:impl-traits");
-    return new CalcitStructDef(xs.name, xs.fields, xs.fieldTypes, baseImpls.concat(addedImpls), xs.definitionRef);
+    return new CalcitStructDef(xs.name, xs.fields, xs.fieldTypes, baseImpls.concat(addedImpls), xs.definitionRef, xs.fieldValidators);
 };
 export let _$n_enum_def_$o_impl_traits = function (xs, ...traits) {
     if (traits.length < 1)
@@ -920,7 +920,7 @@ export let reset_$x_ = (a, v) => {
     });
     return v;
 };
-export let add_watch = (a, k, f) => {
+export let add_watch_$x_ = (a, k, f) => {
     if (!(a instanceof CalcitRef)) {
         throw new Error("Expected ref for add-watch!");
     }
@@ -930,14 +930,25 @@ export let add_watch = (a, k, f) => {
     if (!(typeof f === "function")) {
         throw new Error("Expected watcher function");
     }
+    for (const listenerKey of a.listeners.keys()) {
+        if (listenerKey instanceof CalcitTag && listenerKey.value === k.value) {
+            throw new Error(`add-watch! failed: listener with key \`${k.value}\` already existed`);
+        }
+    }
     a.listeners.set(k, f);
 };
 export let remove_watch = (a, k) => {
-    if (!a.listeners.delete(k)) {
-        throw new Error(`remove-watch failed: listener with key \`${k.value}\` not found`);
+    for (const listenerKey of a.listeners.keys()) {
+        if (listenerKey instanceof CalcitTag && listenerKey.value === k.value) {
+            a.listeners.delete(listenerKey);
+            return;
+        }
     }
+    throw new Error(`remove-watch failed: listener with key \`${k.value}\` not found`);
 };
-const MAX_RANGE_LENGTH = 4294967295;
+// Same eager range limit as native `MAX_RANGE_LEN` and WASM, 2^24 elements (#1852).
+const MAX_RANGE_LENGTH = 2 ** 24;
+const rangeTooLarge = () => new Error(`&list:range result is too large: more than ${MAX_RANGE_LENGTH} elements`);
 export let range = (n, m, step = 1) => {
     const base = m == null ? 0 : n;
     const bound = m == null ? n : m;
@@ -955,11 +966,13 @@ export let range = (n, m, step = 1) => {
         ? Math.ceil(Math.abs(base) / Math.abs(step) + Math.abs(bound) / Math.abs(step))
         : Math.ceil((bound - base) / step);
     if (!Number.isFinite(estimatedLength) || estimatedLength > MAX_RANGE_LENGTH) {
-        throw new Error("&list:range result is too large");
+        throw rangeTooLarge();
     }
     const result = [];
     if (step > 0) {
         for (let value = base; value < bound;) {
+            if (result.length >= MAX_RANGE_LENGTH)
+                throw rangeTooLarge();
             result.push(value);
             const next = value + step;
             if (next === value) {
@@ -970,6 +983,8 @@ export let range = (n, m, step = 1) => {
     }
     else {
         for (let value = base; value > bound;) {
+            if (result.length >= MAX_RANGE_LENGTH)
+                throw rangeTooLarge();
             result.push(value);
             const next = value + step;
             if (next === value) {
@@ -1149,11 +1164,12 @@ export let _$n_list_$o_slice = (xs, from, to) => {
     if (to == null) {
         to = size;
     }
-    else if (to <= from) {
-        return new CalcitSliceList([]);
+    // Bounds are integers with 0 <= from <= to <= size, as in native (docs/data/number.md).
+    if (!Number.isInteger(from) || !Number.isInteger(to) || from < 0 || from > to || to > size) {
+        throw new Error(`&list:slice expected integer bounds within 0..${size}, but received: ${from} ${to}`);
     }
-    else if (to > size) {
-        to = size;
+    if (from === to) {
+        return new CalcitSliceList([]);
     }
     return xs.slice(from, to);
 };
@@ -1200,10 +1216,11 @@ export let _$n__ = (a, b) => {
 export let _$n__SLSH_ = (a, b) => {
     return a / b;
 };
-/** Truncated remainder over safe integers, matching native and WASM; the result is never `-0`. */
+/** Truncated remainder over safe integers, matching native and WASM; the result is never `-0`.
+ * Operands in the error use the native number text (`inf`, expanded exponents) so messages match native. */
 export let _$n_number_$o_rem = (a, b) => {
     if (!Number.isSafeInteger(a) || !Number.isSafeInteger(b)) {
-        throw new Error(`&number:rem requires safe integers, but received: ${toString(a, false)} ${toString(b, false)}`);
+        throw new Error(`&number:rem requires safe integers, but received: ${format_calcit_number(a)} ${format_calcit_number(b)}`);
     }
     if (b === 0) {
         throw new Error("&number:rem divisor must not be zero");
@@ -1350,13 +1367,19 @@ export let cos = (n) => {
     return Math.cos(n);
 };
 export let pow = (n, m) => {
+    // IEEE 754 pow, which Math.pow breaks: pow(1, y) is 1 for any y, pow(-1, ±Infinity) is 1.
+    if (n === 1 || (n === -1 && (m === Infinity || m === -Infinity))) {
+        return 1;
+    }
     return Math.pow(n, m);
 };
 export let ceil = (n) => {
     return Math.ceil(n);
 };
 export let round = (n) => {
-    return Math.round(n);
+    // Ties round away from zero; `Math.round` alone rounds them toward +Infinity.
+    // Negating keeps `-0` for inputs such as -0.4.
+    return n < 0 ? -Math.round(-n) : Math.round(n);
 };
 export let _$n_number_$o_fract = (n) => {
     return n - Math.floor(n);
@@ -1418,7 +1441,12 @@ export let _$n_str_$o_replace = (x, y, z) => {
     return x.replace(new RegExp(literalPattern, "gu"), () => z);
 };
 export let split = (xs, x) => {
-    return new CalcitSliceList(xs.split(x));
+    // An empty delimiter splits by code point, matching native for astral characters.
+    if (x === "") {
+        return new CalcitSliceList(Array.from(xs));
+    }
+    // Drop empty pieces to match native and WASM: `split | |,` is an empty list.
+    return new CalcitSliceList(xs.split(x).filter((piece) => piece !== ""));
 };
 export let split_lines = (xs) => {
     return new CalcitSliceList(xs.split("\n"));
@@ -1504,6 +1532,10 @@ export let _$n_number_$o_format = (x, n) => {
     return x.toFixed(n);
 };
 export let _$n_number_$o_display_by = (x, n) => {
+    // a non-negative safe integer, printed exactly (docs/data/number.md)
+    if (typeof x !== "number" || !Number.isSafeInteger(x) || x < 0) {
+        throw new Error(`&number:display-by expected a non-negative safe integer, but received: ${x}`);
+    }
     switch (n) {
         case 2:
             return `0b${x.toString(2)}`;
@@ -1655,8 +1687,8 @@ export let to_lispy_string = (...args) => {
 export let printable = (...args) => {
     return args.map((x) => toString(x, false)).join(" ");
 };
-// time from app start
-export let cpu_time = () => {
+// monotonic milliseconds since app start
+export let monotonic_time_ms = () => {
     if (inNodeJs) {
         // uptime returns in seconds
         return process.uptime() * 1000;
@@ -1675,37 +1707,6 @@ export let quit_$x_ = (code) => {
         throw new Error(`quit!(${code})`);
     }
 };
-let format_calcit_number = (x) => {
-    // Match native f64 Display, which expands finite exponents into decimal notation.
-    if (Object.is(x, -0)) {
-        return "-0";
-    }
-    if (x === Infinity) {
-        return "inf";
-    }
-    if (x === -Infinity) {
-        return "-inf";
-    }
-    const text = x.toString();
-    const exponentIndex = text.indexOf("e");
-    if (exponentIndex < 0) {
-        return text;
-    }
-    const mantissa = text.slice(0, exponentIndex);
-    const exponent = Number(text.slice(exponentIndex + 1));
-    const sign = mantissa.startsWith("-") ? "-" : "";
-    const unsigned = sign ? mantissa.slice(1) : mantissa;
-    const decimalPoint = unsigned.indexOf(".");
-    const decimalIndex = (decimalPoint < 0 ? unsigned.length : decimalPoint) + exponent;
-    const digits = unsigned.replace(".", "");
-    if (decimalIndex <= 0) {
-        return `${sign}0.${"0".repeat(-decimalIndex)}${digits}`;
-    }
-    if (decimalIndex >= digits.length) {
-        return `${sign}${digits}${"0".repeat(decimalIndex - digits.length)}`;
-    }
-    return `${sign}${digits.slice(0, decimalIndex)}.${digits.slice(decimalIndex)}`;
-};
 export let turn_string = (x) => {
     if (x === null) {
         return "";
@@ -1941,6 +1942,64 @@ export let parse_cirru_edn = (code, options) => {
         throw new Error(`Expected EDN in a single node, got ${nodes.length}`);
     }
 };
+/** Validate existing data without the decoder's map conversion or Option lifting. */
+export function validate_data_shape(input, graph) {
+    if (graph.version !== 3)
+        throw new Error(`validate-data-shape expected ABI version 3, got ${graph.version}`);
+    const sameNominal = (actual, expected) => actual === expected || (actual != null && expected != null && expected.definitionRef != null &&
+        actual.definitionRef === expected.definitionRef && actual.name.value === expected.name.value &&
+        actual.fields.length === expected.fields.length && actual.fields.every((field, idx) => field.value === expected.fields[idx].value && _$n__$e_(actual.fieldTypes[idx], expected.fieldTypes[idx])));
+    const check = (value, nodeId, depth) => {
+        if (depth > 1024)
+            return false;
+        const node = graph.nodes[nodeId];
+        if (node == null)
+            return false;
+        switch (node.kind) {
+            case "dynamic": return true;
+            case "nil": return value === null;
+            case "unit": return value === undefined;
+            case "bool": return typeof value === "boolean";
+            case "number": return typeof value === "number";
+            case "numeric": return typeof value === "number" && _$n_number_$o_fits_$q_(value, newTag(node.target));
+            case "string": return typeof value === "string";
+            case "symbol": return value instanceof CalcitSymbol;
+            case "tag": return value instanceof CalcitTag;
+            case "buffer": return value instanceof Uint8Array;
+            case "cirru-quote": return value instanceof CalcitCirruQuote;
+            case "optional": return value === null || check(value, node.inner, depth + 1);
+            case "list": {
+                if (!(value instanceof CalcitList || value instanceof CalcitSliceList))
+                    return false;
+                for (const item of value.items())
+                    if (!check(item, node.inner, depth + 1))
+                        return false;
+                return true;
+            }
+            case "set": return value instanceof CalcitSet && value.values().every(item => check(item, node.inner, depth + 1));
+            case "map": return (value instanceof CalcitMap || value instanceof CalcitSliceMap) && value.pairs().every(([key, item]) => check(key, node.key, depth + 1) && check(item, node.value, depth + 1));
+            case "ref": return value instanceof CalcitRef && check(value.value, node.inner, depth + 1);
+            case "struct": return value instanceof CalcitStructValue && sameNominal(value.structRef, node.nominal) &&
+                value.values.length === node.fields.length && node.fields.every(([name, child], idx) => value.fields[idx]?.value === name && check(value.values[idx], child, depth + 1));
+            case "map-option":
+            case "enum": {
+                if (!(value instanceof CalcitEnumValue) || value.enumPrototype == null ||
+                    !sameNominal(value.enumPrototype.prototype.structRef, node.nominal.prototype.structRef) ||
+                    !_$n__$e_(value.enumPrototype.prototype, node.nominal.prototype) || !(value.tag instanceof CalcitTag))
+                    return false;
+                if (node.kind === "map-option") {
+                    return value.tag.value === "none" ? value.extra.length === 0 : value.tag.value === "some" &&
+                        value.extra.length === 1 && check(value.extra[0], node.inner, depth + 1);
+                }
+                const tag = value.tag.value;
+                const variant = node.variants.find(candidate => candidate.tag === tag);
+                return variant != null && value.extra.length === variant.payload.length &&
+                    variant.payload.every((child, idx) => check(value.extra[idx], child, depth + 1));
+            }
+        }
+    };
+    return check(input, graph.root, 0);
+}
 const typed_edn_kind = (value) => {
     if (value === null)
         return "nil";
@@ -1980,75 +2039,75 @@ const typed_edn_error = (path, message) => {
 const enum_prototype_name = (value) => {
     return value instanceof CalcitEnumDef ? value.name() : value.name.value;
 };
-const decode_typed_edn_node = (graph, nodeId, input, path, depth) => {
+const decode_typed_edn_node = (graph, nodeId, input, path, depth, fail = typed_edn_error) => {
     if (depth > 1024)
-        typed_edn_error(path, "decode nesting exceeds 1024");
+        fail(path, "decode nesting exceeds 1024");
     const node = graph.nodes[nodeId];
     if (node == null)
-        typed_edn_error(path, `invalid data shape node #${nodeId}`);
+        fail(path, `invalid data shape node #${nodeId}`);
     switch (node.kind) {
         case "nil":
             if (input === null)
                 return null;
-            return typed_edn_error(path, `expected Nil, got ${typed_edn_kind(input)}`);
+            return fail(path, `expected nil, got ${typed_edn_kind(input)}`);
         case "unit":
             if (input === undefined)
                 return input;
-            return typed_edn_error(path, `expected Unit, got ${typed_edn_kind(input)}`);
+            return fail(path, `expected &unit, got ${typed_edn_kind(input)}`);
         case "bool":
             if (typeof input === "boolean")
                 return input;
-            return typed_edn_error(path, `expected bool, got ${typed_edn_kind(input)}`);
+            return fail(path, `expected bool, got ${typed_edn_kind(input)}`);
         case "number":
             if (typeof input === "number")
                 return input;
-            return typed_edn_error(path, `expected number, got ${typed_edn_kind(input)}`);
+            return fail(path, `expected number, got ${typed_edn_kind(input)}`);
         case "numeric":
             if (typeof input !== "number")
-                return typed_edn_error(path, `expected ${node.target}, got ${typed_edn_kind(input)}`);
+                return fail(path, `expected ${node.target}, got ${typed_edn_kind(input)}`);
             if (_$n_number_$o_fits_$q_(input, newTag(node.target)))
                 return input;
-            return typed_edn_error(path, `number ${input} does not fit ${node.target}`);
+            return fail(path, `number ${input} does not fit ${node.target}`);
         case "string":
             if (typeof input === "string")
                 return input;
-            return typed_edn_error(path, `expected string, got ${typed_edn_kind(input)}`);
+            return fail(path, `expected string, got ${typed_edn_kind(input)}`);
         case "symbol":
             if (input instanceof CalcitSymbol)
                 return input;
-            return typed_edn_error(path, `expected symbol, got ${typed_edn_kind(input)}`);
+            return fail(path, `expected symbol, got ${typed_edn_kind(input)}`);
         case "tag":
             if (input instanceof CalcitTag)
                 return input;
-            return typed_edn_error(path, `expected tag, got ${typed_edn_kind(input)}`);
+            return fail(path, `expected tag, got ${typed_edn_kind(input)}`);
         case "buffer":
             if (input instanceof Uint8Array)
                 return input;
-            return typed_edn_error(path, `expected buffer, got ${typed_edn_kind(input)}`);
+            return fail(path, `expected buffer, got ${typed_edn_kind(input)}`);
         case "cirru-quote":
             if (input instanceof CalcitCirruQuote)
                 return input;
-            return typed_edn_error(path, `expected cirru-quote, got ${typed_edn_kind(input)}`);
+            return fail(path, `expected cirru-quote, got ${typed_edn_kind(input)}`);
         case "optional":
-            return input === null ? null : decode_typed_edn_node(graph, node.inner, input, path, depth + 1);
+            return input === null ? null : decode_typed_edn_node(graph, node.inner, input, path, depth + 1, fail);
         case "list": {
             if (!(input instanceof CalcitList || input instanceof CalcitSliceList)) {
-                return typed_edn_error(path, `expected list, got ${typed_edn_kind(input)}`);
+                return fail(path, `expected list, got ${typed_edn_kind(input)}`);
             }
-            const values = Array.from(input.items()).map((value, idx) => decode_typed_edn_node(graph, node.inner, value, `${path}[${idx}]`, depth + 1));
+            const values = Array.from(input.items()).map((value, idx) => decode_typed_edn_node(graph, node.inner, value, `${path}[${idx}]`, depth + 1, fail));
             return new CalcitSliceList(values);
         }
         case "set": {
             if (!(input instanceof CalcitSet || input instanceof TypedEdnSetView)) {
-                return typed_edn_error(path, `expected set, got ${typed_edn_kind(input)}`);
+                return fail(path, `expected set, got ${typed_edn_kind(input)}`);
             }
             const values = [];
             const inputValues = input instanceof TypedEdnSetView ? input.items : input.values();
             inputValues.forEach((value) => {
                 const itemPath = `${path}.item`;
-                const decoded = decode_typed_edn_node(graph, node.inner, value, itemPath, depth + 1);
+                const decoded = decode_typed_edn_node(graph, node.inner, value, itemPath, depth + 1, fail);
                 if (values.some((existing) => _$n__$e_(existing, decoded))) {
-                    typed_edn_error(itemPath, "duplicate decoded set value");
+                    fail(itemPath, "duplicate decoded set value");
                 }
                 values.push(decoded);
             });
@@ -2056,53 +2115,53 @@ const decode_typed_edn_node = (graph, nodeId, input, path, depth) => {
         }
         case "map": {
             if (!(input instanceof CalcitMap || input instanceof CalcitSliceMap)) {
-                return typed_edn_error(path, `expected map, got ${typed_edn_kind(input)}`);
+                return fail(path, `expected map, got ${typed_edn_kind(input)}`);
             }
             const entries = [];
             input.pairs().forEach(([key, value]) => {
                 const keyPath = `${path}.key`;
-                const decodedKey = decode_typed_edn_node(graph, node.key, key, keyPath, depth + 1);
+                const decodedKey = decode_typed_edn_node(graph, node.key, key, keyPath, depth + 1, fail);
                 for (let idx = 0; idx < entries.length; idx += 2) {
                     if (_$n__$e_(entries[idx], decodedKey)) {
-                        typed_edn_error(keyPath, "duplicate decoded map key");
+                        fail(keyPath, "duplicate decoded map key");
                     }
                 }
-                const decodedValue = decode_typed_edn_node(graph, node.value, value, `${path}.value`, depth + 1);
+                const decodedValue = decode_typed_edn_node(graph, node.value, value, `${path}.value`, depth + 1, fail);
                 entries.push(decodedKey, decodedValue);
             });
             return new CalcitSliceMap(entries);
         }
         case "ref":
             if (!(input instanceof CalcitRef))
-                return typed_edn_error(path, `expected atom, got ${typed_edn_kind(input)}`);
-            return atom(decode_typed_edn_node(graph, node.inner, input.value, `${path}.value`, depth + 1));
+                return fail(path, `expected atom, got ${typed_edn_kind(input)}`);
+            return atom(decode_typed_edn_node(graph, node.inner, input.value, `${path}.value`, depth + 1, fail));
         case "struct": {
             if (!(input instanceof CalcitStructValue)) {
-                return typed_edn_error(path, `expected struct :${node.nominal.name.value}, got ${typed_edn_kind(input)}`);
+                return fail(path, `expected struct :${node.nominal.name.value}, got ${typed_edn_kind(input)}`);
             }
             if (input.name.value !== node.nominal.name.value) {
-                return typed_edn_error(path, `expected struct :${node.nominal.name.value}, got struct :${input.name.value}`);
+                return fail(path, `expected struct :${node.nominal.name.value}, got struct :${input.name.value}`);
             }
             const expectedNames = node.fields.map(([name]) => name);
             const actualNames = input.fields.map((field) => field.value);
             const missing = expectedNames.filter((name) => !actualNames.includes(name)).sort();
             const unknown = actualNames.filter((name) => !expectedNames.includes(name)).sort();
             if (missing.length > 0 || unknown.length > 0 || expectedNames.length !== actualNames.length) {
-                return typed_edn_error(path, `struct :${node.nominal.name.value} fields mismatch; missing [${missing.join(", ")}], unknown [${unknown.join(", ")}]`);
+                return fail(path, `struct :${node.nominal.name.value} fields mismatch; missing [${missing.join(", ")}], unknown [${unknown.join(", ")}]`);
             }
             const decodedFields = new Map();
             node.fields.forEach(([name, fieldNode]) => {
                 const idx = actualNames.indexOf(name);
-                decodedFields.set(name, decode_typed_edn_node(graph, fieldNode, input.values[idx], `${path}.${name}`, depth + 1));
+                decodedFields.set(name, decode_typed_edn_node(graph, fieldNode, input.values[idx], `${path}.${name}`, depth + 1, fail));
             });
             // Re-align by name so values produced by older runtimes or external data
             // still adopt the current nominal declaration's canonical field layout.
             if (decodedFields.size !== node.nominal.fields.length) {
-                return typed_edn_error(path, `struct :${node.nominal.name.value} decoder fields do not match its nominal declaration`);
+                return fail(path, `struct :${node.nominal.name.value} decoder fields do not match its nominal declaration`);
             }
             const values = node.nominal.fields.map((field) => {
                 if (!decodedFields.has(field.value)) {
-                    return typed_edn_error(path, `struct :${node.nominal.name.value} is missing declared field :${field.value}`);
+                    return fail(path, `struct :${node.nominal.name.value} is missing declared field :${field.value}`);
                 }
                 return decodedFields.get(field.value);
             });
@@ -2110,28 +2169,28 @@ const decode_typed_edn_node = (graph, nodeId, input, path, depth) => {
         }
         case "enum": {
             if (!(input instanceof CalcitEnumValue) || input.enumPrototype == null) {
-                return typed_edn_error(path, `expected enum :${node.nominal.name()}, got ${typed_edn_kind(input)}`);
+                return fail(path, `expected enum :${node.nominal.name()}, got ${typed_edn_kind(input)}`);
             }
             const actualEnumName = enum_prototype_name(input.enumPrototype);
             if (actualEnumName !== node.nominal.name()) {
-                return typed_edn_error(path, `expected enum :${node.nominal.name()}, got enum :${actualEnumName}`);
+                return fail(path, `expected enum :${node.nominal.name()}, got enum :${actualEnumName}`);
             }
             if (!(input.tag instanceof CalcitTag)) {
-                return typed_edn_error(path, `enum :${node.nominal.name()} variant must be a tag`);
+                return fail(path, `enum :${node.nominal.name()} variant must be a tag`);
             }
             const inputTag = input.tag;
             const variant = node.variants.find((candidate) => candidate.tag === inputTag.value);
             if (variant == null) {
-                return typed_edn_error(path, `enum :${node.nominal.name()} has no variant :${inputTag.value}`);
+                return fail(path, `enum :${node.nominal.name()} has no variant :${inputTag.value}`);
             }
             if (variant.payload.length !== input.extra.length) {
-                return typed_edn_error(path, `enum :${node.nominal.name()} variant :${variant.tag} expects ${variant.payload.length} payload(s), got ${input.extra.length}`);
+                return fail(path, `enum :${node.nominal.name()} variant :${variant.tag} expects ${variant.payload.length} payload(s), got ${input.extra.length}`);
             }
-            const values = variant.payload.map((payloadNode, idx) => decode_typed_edn_node(graph, payloadNode, input.extra[idx], `${path}.payload[${idx}]`, depth + 1));
+            const values = variant.payload.map((payloadNode, idx) => decode_typed_edn_node(graph, payloadNode, input.extra[idx], `${path}.payload[${idx}]`, depth + 1, fail));
             return new CalcitEnumValue(newTag(variant.tag), values, node.nominal);
         }
         default:
-            return typed_edn_error(path, `invalid data shape node kind: ${node.kind}`);
+            return fail(path, `invalid data shape node kind: ${node.kind}`);
     }
 };
 export let parse_cirru_edn_as = (code, graph) => {
@@ -2282,7 +2341,7 @@ const decode_runtime_map_node = (graph, nodeId, input, path, depth) => {
             return new CalcitEnumValue(newTag(variant.tag), values, node.nominal);
         }
         default:
-            return decode_typed_edn_node(graph, nodeId, input, path, depth);
+            return decode_typed_edn_node(graph, nodeId, input, path, depth, map_decode_error);
     }
 };
 export let decode_map_as = (value, graph) => {
@@ -2808,6 +2867,19 @@ export function _$n_trait_call(traitDef, method, obj, ...args) {
     }
     throw new Error(`&trait-call: cannot find impl for trait ${traitDef.name.toString()} on ${toString(obj, true)}. Hint: use defimpl to create impls tagged by trait.`);
 }
+export let _$n_map_$o_fold_kv = (m, initial, reducer) => {
+    if (!(m instanceof CalcitMap || m instanceof CalcitSliceMap)) {
+        throw new Error("&map:fold-kv expected a Map");
+    }
+    if (typeof reducer !== "function") {
+        throw new Error("&map:fold-kv expected a callback function");
+    }
+    let accumulator = initial;
+    for (const [key, value] of m.pairs()) {
+        accumulator = reducer(accumulator, key, value);
+    }
+    return accumulator;
+};
 export let _$n_map_$o_to_list = (m) => {
     if (m instanceof CalcitMap || m instanceof CalcitSliceMap) {
         let ys = [];
@@ -2894,23 +2966,30 @@ export let _$n_map_$o_diff_triple = (a, b) => {
         throw new Error("&map:diff-triple expected 2 maps");
     }
 };
+// Bitwise operands are integers within i32 (docs/data/number.md); JS would otherwise wrap or truncate them.
+let bit_operand = (name, x) => {
+    if (typeof x !== "number" || !Number.isInteger(x) || x < -2147483648 || x > 2147483647) {
+        throw new Error(`&math:${name} operand expected an integer within i32, but got: ${x}`);
+    }
+    return x;
+};
 export let bit_shr = (base, step) => {
-    return base >> step;
+    return bit_operand("bit-shr", base) >> bit_operand("bit-shr", step);
 };
 export let bit_shl = (base, step) => {
-    return base << step;
+    return bit_operand("bit-shl", base) << bit_operand("bit-shl", step);
 };
 export let bit_and = (a, b) => {
-    return a & b;
+    return bit_operand("bit-and", a) & bit_operand("bit-and", b);
 };
 export let bit_or = (a, b) => {
-    return a | b;
+    return bit_operand("bit-or", a) | bit_operand("bit-or", b);
 };
 export let bit_xor = (a, b) => {
-    return a ^ b;
+    return bit_operand("bit-xor", a) ^ bit_operand("bit-xor", b);
 };
 export let bit_not = (a) => {
-    return ~a;
+    return ~bit_operand("bit-not", a);
 };
 export let _$n_list_$o_to_set = (xs) => {
     var result = [];
@@ -2933,11 +3012,41 @@ export let _$n_list_$o_distinct = (xs) => {
     }
     return new CalcitSliceList(result);
 };
+// Longest padded string, the V8 string length limit, so every backend fails at the same size.
+const MAX_PADDED_LEN = 536870888;
+// Padding for `&str:pad-left` / `&str:pad-right`, measured in Unicode scalars like `&str:count`
+// (not UTF-16 units, so astral characters are never split). NaN and negative lengths pad nothing,
+// and so does an empty pattern.
+const strPadding = (procName, s, size, pattern) => {
+    if (size > MAX_PADDED_LEN) {
+        throw new Error(`${procName} expected a finite length up to ${MAX_PADDED_LEN}, but received: ${format_calcit_number(size)}`);
+    }
+    if (!(size > 0) || pattern === "")
+        return "";
+    let missing = Math.floor(size);
+    for (const _scalar of s) {
+        missing -= 1;
+        if (missing <= 0)
+            return "";
+    }
+    let patternCount = 0;
+    for (const _scalar of pattern)
+        patternCount += 1;
+    let padding = pattern.repeat(Math.floor(missing / patternCount));
+    let rest = missing % patternCount;
+    for (const scalar of pattern) {
+        if (rest <= 0)
+            break;
+        padding += scalar;
+        rest -= 1;
+    }
+    return padding;
+};
 export let _$n_str_$o_pad_left = (s, size, pattern) => {
-    return s.padStart(size, pattern);
+    return strPadding("&str:pad-left", s, size, pattern) + s;
 };
 export let _$n_str_$o_pad_right = (s, size, pattern) => {
-    return s.padEnd(size, pattern);
+    return s + strPadding("&str:pad-right", s, size, pattern);
 };
 export let _$n_get_os = () => {
     return newTag("js-engine");
@@ -2993,8 +3102,12 @@ export let macroexpand_all = unavailableProc;
 export let _$n_get_calcit_running_mode = unavailableProc;
 export let _$n_get_def_doc = unavailableProc;
 export let _$n_get_def_schema = unavailableProc;
-export let _$n_ffi_response_resolve = unavailableProc;
-export let _$n_ffi_response_reject = unavailableProc;
-export let _$n_ffi_task_cancel = unavailableProc;
+// A missing native lifecycle capability must not look like a successful Unit.
+const unavailableNativeFfi = (operation) => {
+    throw new Error(`${operation}: native FFI capability is not available for calcit-js`);
+};
+export let _$n_ffi_response_resolve = (..._args) => unavailableNativeFfi("&ffi-response-resolve");
+export let _$n_ffi_response_reject = (..._args) => unavailableNativeFfi("&ffi-response-reject");
+export let _$n_ffi_task_cancel = (..._args) => unavailableNativeFfi("&ffi-task-cancel");
 // already handled in code emitter
 export let raise = unavailableProc;

package/lib/js-cirru.d.mts

@@ -12,7 +12,7 @@ export declare class CalcitCirruQuote {
     /** provide a simple text representation in Console or std out, with indentations */
     textForm(): string;
 }
-export declare let format_cirru: (data: CalcitCirruQuote | CalcitList, useInline: boolean) => string;
+export declare let format_cirru: (data: CalcitCirruQuote | CalcitList, useInline?: boolean) => string;
 export declare let format_cirru_one_liner: (data: CalcitCirruQuote | CalcitList) => string;
 /** better use string version of Cirru EDN in future */
 export declare let to_cirru_edn: (x: CalcitValue) => CirruEdnFormat;

package/lib/js-cirru.mjs

@@ -160,7 +160,12 @@ export class CalcitCirruQuote {
         }
     }
 }
-export let format_cirru = (data, useInline) => {
+export let format_cirru = function (data, useInline) {
+    if (arguments.length < 2)
+        useInline = false;
+    if (typeof useInline !== "boolean") {
+        throw new Error("format-cirru requires a boolean inline option");
+    }
     if (data instanceof CalcitCirruQuote) {
         return writeCirruCode(data.value, { useInline });
     }
@@ -563,7 +568,9 @@ export let extract_cirru_edn = (x, options) => {
 export let extract_cirru_edn_for_typed = (x, options) => {
     return extract_cirru_edn_inner(x, options, true);
 };
-export let format_cirru_edn = (data, useInline = true) => {
+export let format_cirru_edn = function (data, useInline) {
+    if (arguments.length < 2)
+        useInline = true;
     if (typeof useInline !== "boolean") {
         throw new Error("format-cirru-edn requires a boolean inline option");
     }

package/lib/js-primes.d.mts

@@ -12,4 +12,6 @@ import { CalcitCirruQuote } from "./js-cirru.mjs";
 import { CalcitTrait } from "./js-trait.mjs";
 export type CalcitValue = string | number | boolean | CalcitMap | CalcitSliceMap | CalcitList | CalcitSliceList | CalcitSet | CalcitTag | CalcitSymbol | CalcitRef | CalcitEnumValue | CalcitFn | CalcitRecur | CalcitStructValue | CalcitImpl | CalcitTrait | CalcitStructDef | CalcitEnumDef | CalcitCirruQuote | Uint8Array | undefined | null;
 export declare let isLiteral: (x: CalcitValue) => boolean;
+/** total order over numbers: `-0` equals `0`, NaN equals NaN and sorts after every number */
+export declare let compareNumbers: (x: number, y: number) => number;
 export declare let _$n_compare: (a: CalcitValue, b: CalcitValue) => number;