@oxygen-agent/cli 1.377.3 → 1.575.19

package/node_modules/@oxygen/formula/dist/formula-functions.js

@@ -0,0 +1,1100 @@
+import { OxygenError } from "@oxygen/shared/cli-result";
+import { isRecord } from "./coerce.js";
+import { normalizeDomain, normalizeEmail, normalizeLinkedinUrl, } from "./value-normalizers.js";
+export const MAX_FORMULA_REGEX_PATTERN_LENGTH = 256;
+export const MAX_FORMULA_REGEX_INPUT_LENGTH = 20_000;
+// ---------------------------------------------------------------------------
+// Shared coercion helpers (used by the registry AND the runner's operators)
+// ---------------------------------------------------------------------------
+export function formulaExpressionError(message, details) {
+    return new OxygenError("invalid_formula_expression", message, {
+        details,
+        exitCode: 1,
+    });
+}
+export function isBlankFormulaValue(value) {
+    if (value === null || value === undefined)
+        return true;
+    if (typeof value === "string")
+        return value.trim().length === 0;
+    if (Array.isArray(value))
+        return value.length === 0;
+    return false;
+}
+export function stringifyFormulaValue(value) {
+    if (value === null || value === undefined)
+        return "";
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "number" || typeof value === "boolean")
+        return String(value);
+    return JSON.stringify(value);
+}
+export function readFormulaNumber(value, operator) {
+    if (typeof value === "number" && Number.isFinite(value))
+        return value;
+    if (typeof value === "string" && value.trim() && Number.isFinite(Number(value))) {
+        return Number(value);
+    }
+    throw formulaExpressionError("Formula numeric operation requires numeric values.", {
+        operator,
+        value,
+    });
+}
+export function toFormulaBoolean(value) {
+    if (typeof value === "boolean")
+        return value;
+    if (typeof value === "number")
+        return value !== 0;
+    if (typeof value === "string") {
+        const normalized = value.trim().toLowerCase();
+        if (["true", "yes", "y", "1"].includes(normalized))
+            return true;
+        if (["false", "no", "n", "0", ""].includes(normalized))
+            return false;
+    }
+    return Boolean(value);
+}
+export function compareFormulaValues(left, right) {
+    if (typeof left === "number" || typeof right === "number") {
+        return readFormulaNumber(left, "comparison") - readFormulaNumber(right, "comparison");
+    }
+    return String(left ?? "").localeCompare(String(right ?? ""));
+}
+export function formulaValuesEqual(left, right) {
+    if ((typeof left === "number" || typeof right === "number")
+        && !isBlankFormulaValue(left)
+        && !isBlankFormulaValue(right)) {
+        return readFormulaNumber(left, "comparison") === readFormulaNumber(right, "comparison");
+    }
+    return left === right;
+}
+export function readFormulaJsonPath(value, rawPath) {
+    const path = rawPath.trim();
+    if (!path)
+        return value ?? null;
+    let current = value;
+    for (const rawSegment of path.split(".")) {
+        const segment = rawSegment.trim();
+        if (!segment) {
+            throw formulaExpressionError("JSON path contains an empty segment.", {
+                path: rawPath,
+            });
+        }
+        if (current === null || current === undefined)
+            return null;
+        if (Array.isArray(current) && /^\d+$/.test(segment)) {
+            current = current[Number(segment)] ?? null;
+            continue;
+        }
+        if (isRecord(current) && Object.hasOwn(current, segment)) {
+            current = current[segment];
+            continue;
+        }
+        return null;
+    }
+    return current ?? null;
+}
+export function checkFormulaFunctionArity(spec, received) {
+    const withinMin = received >= spec.minArgs;
+    const withinMax = spec.maxArgs === null || received <= spec.maxArgs;
+    if (withinMin && withinMax)
+        return;
+    throw formulaExpressionError("Formula function received the wrong number of arguments.", {
+        function: spec.name,
+        ...(spec.maxArgs === spec.minArgs ? { expected: spec.minArgs } : {}),
+        min_args: spec.minArgs,
+        max_args: spec.maxArgs,
+        received,
+    });
+}
+// ---------------------------------------------------------------------------
+// Local helpers
+// ---------------------------------------------------------------------------
+function asText(value) {
+    return value === null || value === undefined ? "" : stringifyFormulaValue(value);
+}
+function blankToNull(value, transform) {
+    return isBlankFormulaValue(value) ? null : transform(value);
+}
+function compileFormulaRegex(pattern, functionName, flags) {
+    if (typeof pattern !== "string" || !pattern) {
+        throw formulaExpressionError("Regular-expression functions require a non-empty string pattern.", {
+            function: functionName,
+        });
+    }
+    if (pattern.length > MAX_FORMULA_REGEX_PATTERN_LENGTH) {
+        throw formulaExpressionError("Regular-expression pattern is too long.", {
+            function: functionName,
+            max_length: MAX_FORMULA_REGEX_PATTERN_LENGTH,
+            received_length: pattern.length,
+        });
+    }
+    try {
+        return new RegExp(pattern, flags);
+    }
+    catch (error) {
+        throw formulaExpressionError("Invalid regular-expression pattern.", {
+            function: functionName,
+            pattern,
+            parse_error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+function readRegexInput(value, functionName) {
+    const text = asText(value);
+    if (text.length > MAX_FORMULA_REGEX_INPUT_LENGTH) {
+        throw formulaExpressionError("Regular-expression input is too long.", {
+            function: functionName,
+            max_length: MAX_FORMULA_REGEX_INPUT_LENGTH,
+            received_length: text.length,
+        });
+    }
+    return text;
+}
+function collectNumericArgs(args, functionName) {
+    const values = [];
+    for (const arg of args) {
+        if (Array.isArray(arg)) {
+            for (const element of arg) {
+                if (isBlankFormulaValue(element))
+                    continue;
+                values.push(readFormulaNumber(element, functionName));
+            }
+            continue;
+        }
+        if (isBlankFormulaValue(arg))
+            continue;
+        values.push(readFormulaNumber(arg, functionName));
+    }
+    return values;
+}
+const DATE_UNIT_MS = {
+    seconds: 1_000,
+    minutes: 60_000,
+    hours: 3_600_000,
+    days: 86_400_000,
+    weeks: 604_800_000,
+};
+export const FORMULA_DATE_UNITS = [
+    "seconds",
+    "minutes",
+    "hours",
+    "days",
+    "weeks",
+    "months",
+    "years",
+];
+function parseFormulaDate(value) {
+    if (isBlankFormulaValue(value))
+        return null;
+    if (value instanceof Date)
+        return Number.isNaN(value.getTime()) ? null : value;
+    if (typeof value === "number" && Number.isFinite(value)) {
+        const fromEpochMs = new Date(value);
+        return Number.isNaN(fromEpochMs.getTime()) ? null : fromEpochMs;
+    }
+    if (typeof value !== "string")
+        return null;
+    const trimmed = value.trim();
+    if (!trimmed)
+        return null;
+    if (/^-?\d+$/.test(trimmed)) {
+        const fromEpochMs = new Date(Number(trimmed));
+        return Number.isNaN(fromEpochMs.getTime()) ? null : fromEpochMs;
+    }
+    const dateOnly = /^(\d{4})-(\d{2})-(\d{2})$/.exec(trimmed);
+    const parsed = new Date(dateOnly ? `${trimmed}T00:00:00.000Z` : trimmed);
+    return Number.isNaN(parsed.getTime()) ? null : parsed;
+}
+function readDateUnit(value, functionName) {
+    const unit = typeof value === "string" ? value.trim().toLowerCase() : "";
+    const singularless = unit.endsWith("s") ? unit : `${unit}s`;
+    if (!FORMULA_DATE_UNITS.includes(singularless)) {
+        throw formulaExpressionError("Unsupported date unit.", {
+            function: functionName,
+            unit: value,
+            supported: [...FORMULA_DATE_UNITS],
+        });
+    }
+    return singularless;
+}
+function calendarMonthsBetween(later, earlier) {
+    const sign = later.getTime() >= earlier.getTime() ? 1 : -1;
+    const [a, b] = sign === 1 ? [later, earlier] : [earlier, later];
+    let months = (a.getUTCFullYear() - b.getUTCFullYear()) * 12 + (a.getUTCMonth() - b.getUTCMonth());
+    const aDayStamp = a.getUTCDate() * 1_000_000 + a.getUTCHours() * 10_000 + a.getUTCMinutes() * 100 + a.getUTCSeconds();
+    const bDayStamp = b.getUTCDate() * 1_000_000 + b.getUTCHours() * 10_000 + b.getUTCMinutes() * 100 + b.getUTCSeconds();
+    if (aDayStamp < bDayStamp)
+        months -= 1;
+    return sign * months;
+}
+function addCalendarMonths(date, months) {
+    const result = new Date(date.getTime());
+    const targetDay = result.getUTCDate();
+    result.setUTCDate(1);
+    result.setUTCMonth(result.getUTCMonth() + months);
+    const lastDayOfTargetMonth = new Date(Date.UTC(result.getUTCFullYear(), result.getUTCMonth() + 1, 0)).getUTCDate();
+    result.setUTCDate(Math.min(targetDay, lastDayOfTargetMonth));
+    return result;
+}
+function formatUtcDate(date, format) {
+    const pad = (value, width) => String(value).padStart(width, "0");
+    return format
+        .replace(/YYYY/g, pad(date.getUTCFullYear(), 4))
+        .replace(/MM/g, pad(date.getUTCMonth() + 1, 2))
+        .replace(/DD/g, pad(date.getUTCDate(), 2))
+        .replace(/HH/g, pad(date.getUTCHours(), 2))
+        .replace(/mm/g, pad(date.getUTCMinutes(), 2))
+        .replace(/ss/g, pad(date.getUTCSeconds(), 2));
+}
+// ---------------------------------------------------------------------------
+// Registry
+// ---------------------------------------------------------------------------
+function spec(entry) {
+    return entry;
+}
+const SPECS = [
+    // --- logic ---------------------------------------------------------------
+    spec({
+        name: "if",
+        category: "logic",
+        signature: "if(condition, then, else?)",
+        description: "Returns `then` when the condition is truthy, otherwise `else` (or null). The untaken branch is never evaluated, so guards like if(x = 0, 0, 100 / x) are safe.",
+        minArgs: 2,
+        maxArgs: 3,
+        lazy: true,
+        examples: [{ expression: "if(score >= 80, \"hot\", \"warm\")", result: "hot" }],
+        evaluateLazy: (thunks) => {
+            if (toFormulaBoolean(thunks[0]?.()))
+                return thunks[1]?.() ?? null;
+            return thunks[2] ? thunks[2]() : null;
+        },
+    }),
+    spec({
+        name: "switch",
+        category: "logic",
+        signature: "switch(value, case1, result1, ..., default?)",
+        description: "Compares `value` against each case in order and returns the matching result; a trailing odd argument is the default. Unmatched without a default returns null. Results are evaluated lazily.",
+        minArgs: 3,
+        maxArgs: null,
+        lazy: true,
+        examples: [{ expression: "switch(tier, \"a\", 100, \"b\", 50, 10)", result: 50 }],
+        evaluateLazy: (thunks) => {
+            const value = thunks[0]?.();
+            const hasDefault = (thunks.length - 1) % 2 === 1;
+            const lastPairIndex = hasDefault ? thunks.length - 2 : thunks.length - 1;
+            for (let index = 1; index + 1 <= lastPairIndex; index += 2) {
+                const caseThunk = thunks[index];
+                const resultThunk = thunks[index + 1];
+                if (!caseThunk || !resultThunk)
+                    break;
+                if (formulaValuesEqual(value, caseThunk()))
+                    return resultThunk();
+            }
+            const defaultThunk = thunks[thunks.length - 1];
+            return hasDefault && defaultThunk ? defaultThunk() : null;
+        },
+    }),
+    spec({
+        name: "and",
+        category: "logic",
+        signature: "and(a, b, ...)",
+        description: "True when every argument is truthy; stops evaluating at the first falsy argument. Function form of the `and` operator.",
+        minArgs: 1,
+        maxArgs: null,
+        lazy: true,
+        examples: [{ expression: "and(is_blank(email) = false, score > 50)", result: true }],
+        evaluateLazy: (thunks) => {
+            for (const thunk of thunks) {
+                if (!toFormulaBoolean(thunk()))
+                    return false;
+            }
+            return true;
+        },
+    }),
+    spec({
+        name: "or",
+        category: "logic",
+        signature: "or(a, b, ...)",
+        description: "True when any argument is truthy; stops evaluating at the first truthy argument. Function form of the `or` operator.",
+        minArgs: 1,
+        maxArgs: null,
+        lazy: true,
+        examples: [{ expression: "or(contains(title, \"founder\"), contains(title, \"ceo\"))", result: true }],
+        evaluateLazy: (thunks) => {
+            for (const thunk of thunks) {
+                if (toFormulaBoolean(thunk()))
+                    return true;
+            }
+            return false;
+        },
+    }),
+    spec({
+        name: "bool",
+        category: "logic",
+        signature: "bool(value)",
+        description: "Casts a value to boolean: numbers by non-zero, strings by yes/no/true/false/1/0 words, blanks to false.",
+        minArgs: 1,
+        maxArgs: 1,
+        examples: [{ expression: "bool(\"yes\")", result: true }],
+        evaluate: (args) => toFormulaBoolean(args[0]),
+    }),
+    // --- string ---------------------------------------------------------------
+    spec({
+        name: "concat",
+        category: "string",
+        signature: "concat(a, b, ...)",
+        description: "Concatenates all arguments as text; blank arguments contribute nothing.",
+        minArgs: 0,
+        maxArgs: null,
+        examples: [{ expression: "concat(first_name, \" \", last_name)", result: "Ada Lovelace" }],
+        evaluate: (args) => args.map((arg) => (arg === null || arg === undefined ? "" : String(arg))).join(""),
+    }),
+    spec({
+        name: "lower",
+        category: "string",
+        signature: "lower(text)",
+        description: "Lowercases text.",
+        minArgs: 1,
+        maxArgs: 1,
+        examples: [{ expression: "lower(\"ACME\")", result: "acme" }],
+        evaluate: (args) => String(args[0] ?? "").toLowerCase(),
+    }),
+    spec({
+        name: "upper",
+        category: "string",
+        signature: "upper(text)",
+        description: "Uppercases text.",
+        minArgs: 1,
+        maxArgs: 1,
+        examples: [{ expression: "upper(\"acme\")", result: "ACME" }],
+        evaluate: (args) => String(args[0] ?? "").toUpperCase(),
+    }),
+    spec({
+        name: "trim",
+        category: "string",
+        signature: "trim(text)",
+        description: "Removes leading and trailing whitespace.",
+        minArgs: 1,
+        maxArgs: 1,
+        examples: [{ expression: "trim(\"  hi  \")", result: "hi" }],
+        evaluate: (args) => String(args[0] ?? "").trim(),
+    }),
+    spec({
+        name: "text",
+        category: "string",
+        signature: "text(value)",
+        description: "Casts any value to text; objects and arrays become JSON.",
+        minArgs: 1,
+        maxArgs: 1,
+        examples: [{ expression: "text(42)", result: "42" }],
+        evaluate: (args) => stringifyFormulaValue(args[0]),
+    }),
+    spec({
+        name: "split",
+        category: "string",
+        signature: "split(text, separator)",
+        description: "Splits text into an array of parts. Blank text yields an empty array.",
+        minArgs: 2,
+        maxArgs: 2,
+        examples: [{ expression: "split(\"a,b,c\", \",\")", result: ["a", "b", "c"] }],
+        evaluate: (args) => {
+            if (isBlankFormulaValue(args[0]))
+                return [];
+            const separator = asText(args[1]);
+            const input = asText(args[0]);
+            return separator ? input.split(separator) : [input];
+        },
+    }),
+    spec({
+        name: "join",
+        category: "string",
+        signature: "join(separator, a, b, ...)",
+        description: "Joins the non-blank arguments with the separator.",
+        minArgs: 1,
+        maxArgs: null,
+        examples: [{ expression: "join(\", \", city, country)", result: "Berlin, Germany" }],
+        evaluate: (args) => {
+            const [separator, ...values] = args;
+            return values
+                .filter((value) => !isBlankFormulaValue(value))
+                .map((value) => stringifyFormulaValue(value))
+                .join(asText(separator));
+        },
+    }),
+    spec({
+        name: "join_list",
+        category: "string",
+        signature: "join_list(array, separator?)",
+        description: "Joins the non-blank elements of an array with the separator (default \", \").",
+        minArgs: 1,
+        maxArgs: 2,
+        examples: [{ expression: "join_list(path(payload, \"tags\"), \" | \")", result: "b2b | saas" }],
+        evaluate: (args) => {
+            const separator = args.length > 1 ? asText(args[1]) : ", ";
+            if (isBlankFormulaValue(args[0]))
+                return "";
+            if (!Array.isArray(args[0]))
+                return stringifyFormulaValue(args[0]);
+            return args[0]
+                .filter((value) => !isBlankFormulaValue(value))
+                .map((value) => stringifyFormulaValue(value))
+                .join(separator);
+        },
+    }),
+    spec({
+        name: "replace",
+        category: "string",
+        signature: "replace(text, find, replacement)",
+        description: "Replaces every literal occurrence of `find` with `replacement`.",
+        minArgs: 3,
+        maxArgs: 3,
+        examples: [{ expression: "replace(\"a-b-c\", \"-\", \".\")", result: "a.b.c" }],
+        evaluate: (args) => {
+            const input = asText(args[0]);
+            const find = asText(args[1]);
+            if (!find)
+                return input;
+            return input.split(find).join(asText(args[2]));
+        },
+    }),
+    spec({
+        name: "regex_extract",
+        category: "string",
+        signature: "regex_extract(text, pattern, group?)",
+        description: "Returns the first regex match — capture group 1 when the pattern has groups (or the group index you pass), otherwise the whole match. No match returns null.",
+        minArgs: 2,
+        maxArgs: 3,
+        examples: [{ expression: "regex_extract(email, \"@(.+)$\")", result: "acme.com" }],
+        evaluate: (args) => {
+            const input = readRegexInput(args[0], "regex_extract");
+            if (!input)
+                return null;
+            const regex = compileFormulaRegex(args[1], "regex_extract", "");
+            const match = regex.exec(input);
+            if (!match)
+                return null;
+            if (args.length > 2) {
+                const group = readFormulaNumber(args[2], "regex_extract");
+                return match[group] ?? null;
+            }
+            return match.length > 1 ? match[1] ?? null : match[0] ?? null;
+        },
+    }),
+    spec({
+        name: "regex_match",
+        category: "string",
+        signature: "regex_match(text, pattern)",
+        description: "True when the text matches the regular expression.",
+        minArgs: 2,
+        maxArgs: 2,
+        examples: [{ expression: "regex_match(website, \"^https://\")", result: true }],
+        evaluate: (args) => {
+            const input = readRegexInput(args[0], "regex_match");
+            if (!input)
+                return false;
+            return compileFormulaRegex(args[1], "regex_match", "").test(input);
+        },
+    }),
+    spec({
+        name: "regex_replace",
+        category: "string",
+        signature: "regex_replace(text, pattern, replacement)",
+        description: "Replaces every regex match with the replacement ($1-style backreferences supported).",
+        minArgs: 3,
+        maxArgs: 3,
+        examples: [{ expression: "regex_replace(phone, \"[^0-9]\", \"\")", result: "14155550101" }],
+        evaluate: (args) => {
+            const input = readRegexInput(args[0], "regex_replace");
+            if (!input)
+                return "";
+            return input.replace(compileFormulaRegex(args[1], "regex_replace", "g"), asText(args[2]));
+        },
+    }),
+    spec({
+        name: "substring",
+        category: "string",
+        signature: "substring(text, start, length?)",
+        description: "Returns part of the text from a 0-based start index, optionally limited to `length` characters.",
+        minArgs: 2,
+        maxArgs: 3,
+        examples: [{ expression: "substring(\"oxygen\", 0, 2)", result: "ox" }],
+        evaluate: (args) => {
+            const input = asText(args[0]);
+            const start = Math.trunc(readFormulaNumber(args[1], "substring"));
+            if (args.length > 2) {
+                const length = Math.max(0, Math.trunc(readFormulaNumber(args[2], "substring")));
+                const from = start < 0 ? Math.max(0, input.length + start) : start;
+                return input.slice(from, from + length);
+            }
+            return input.slice(start);
+        },
+    }),
+    spec({
+        name: "left",
+        category: "string",
+        signature: "left(text, count)",
+        description: "Returns the first `count` characters.",
+        minArgs: 2,
+        maxArgs: 2,
+        examples: [{ expression: "left(\"oxygen\", 2)", result: "ox" }],
+        evaluate: (args) => asText(args[0]).slice(0, Math.max(0, Math.trunc(readFormulaNumber(args[1], "left")))),
+    }),
+    spec({
+        name: "right",
+        category: "string",
+        signature: "right(text, count)",
+        description: "Returns the last `count` characters.",
+        minArgs: 2,
+        maxArgs: 2,
+        examples: [{ expression: "right(\"oxygen\", 3)", result: "gen" }],
+        evaluate: (args) => {
+            const count = Math.max(0, Math.trunc(readFormulaNumber(args[1], "right")));
+            const input = asText(args[0]);
+            return count === 0 ? "" : input.slice(-count);
+        },
+    }),
+    spec({
+        name: "length",
+        category: "string",
+        signature: "length(value)",
+        description: "Length of a string in characters or an array in items; blank is 0.",
+        minArgs: 1,
+        maxArgs: 1,
+        examples: [{ expression: "length(company_name)", result: 4 }],
+        evaluate: (args) => {
+            if (isBlankFormulaValue(args[0]))
+                return 0;
+            if (Array.isArray(args[0]))
+                return args[0].length;
+            return asText(args[0]).length;
+        },
+    }),
+    spec({
+        name: "title_case",
+        category: "string",
+        signature: "title_case(text)",
+        description: "Capitalizes the first letter of every word and lowercases the rest.",
+        minArgs: 1,
+        maxArgs: 1,
+        examples: [{ expression: "title_case(\"acme CORP\")", result: "Acme Corp" }],
+        evaluate: (args) => asText(args[0]).replace(/([A-Za-z])([A-Za-z]*)/g, (_match, first, rest) => first.toUpperCase() + rest.toLowerCase()),
+    }),
+    spec({
+        name: "pad_start",
+        category: "string",
+        signature: "pad_start(text, length, pad?)",
+        description: "Pads the start of the text to the target length (default pad: space).",
+        minArgs: 2,
+        maxArgs: 3,
+        examples: [{ expression: "pad_start(\"7\", 3, \"0\")", result: "007" }],
+        evaluate: (args) => asText(args[0]).padStart(Math.max(0, Math.trunc(readFormulaNumber(args[1], "pad_start"))), args.length > 2 ? asText(args[2]) || " " : " "),
+    }),
+    spec({
+        name: "pad_end",
+        category: "string",
+        signature: "pad_end(text, length, pad?)",
+        description: "Pads the end of the text to the target length (default pad: space).",
+        minArgs: 2,
+        maxArgs: 3,
+        examples: [{ expression: "pad_end(\"7\", 3, \"0\")", result: "700" }],
+        evaluate: (args) => asText(args[0]).padEnd(Math.max(0, Math.trunc(readFormulaNumber(args[1], "pad_end"))), args.length > 2 ? asText(args[2]) || " " : " "),
+    }),
+    spec({
+        name: "starts_with",
+        category: "string",
+        signature: "starts_with(text, prefix)",
+        description: "True when the text starts with the prefix. Blank text or prefix is false.",
+        minArgs: 2,
+        maxArgs: 2,
+        examples: [{ expression: "starts_with(website, \"https\")", result: true }],
+        evaluate: (args) => {
+            if (isBlankFormulaValue(args[0]) || isBlankFormulaValue(args[1]))
+                return false;
+            return asText(args[0]).startsWith(asText(args[1]));
+        },
+    }),
+    spec({
+        name: "ends_with",
+        category: "string",
+        signature: "ends_with(text, suffix)",
+        description: "True when the text ends with the suffix. Blank text or suffix is false.",
+        minArgs: 2,
+        maxArgs: 2,
+        examples: [{ expression: "ends_with(email, \"@acme.com\")", result: true }],
+        evaluate: (args) => {
+            if (isBlankFormulaValue(args[0]) || isBlankFormulaValue(args[1]))
+                return false;
+            return asText(args[0]).endsWith(asText(args[1]));
+        },
+    }),
+    spec({
+        name: "contains",
+        category: "string",
+        signature: "contains(text, needle)",
+        description: "True when the text contains the needle (case-sensitive; wrap both in lower(...) for case-insensitive). Blank text or needle is false.",
+        minArgs: 2,
+        maxArgs: 2,
+        examples: [{ expression: "contains(lower(title), \"founder\")", result: true }],
+        evaluate: (args) => {
+            if (isBlankFormulaValue(args[0]) || isBlankFormulaValue(args[1]))
+                return false;
+            return asText(args[0]).includes(asText(args[1]));
+        },
+    }),
+    // --- number ----------------------------------------------------------------
+    spec({
+        name: "number",
+        category: "number",
+        signature: "number(value)",
+        description: "Casts a value to a number; blank becomes null; non-numeric text errors.",
+        minArgs: 1,
+        maxArgs: 1,
+        examples: [{ expression: "number(\"42\")", result: 42 }],
+        evaluate: (args) => (isBlankFormulaValue(args[0]) ? null : readFormulaNumber(args[0], "number")),
+    }),
+    spec({
+        name: "round",
+        category: "number",
+        signature: "round(value, digits?)",
+        description: "Rounds to the given number of decimal digits (default 0). Blank input is null.",
+        minArgs: 1,
+        maxArgs: 2,
+        examples: [{ expression: "round(3.14159, 2)", result: 3.14 }],
+        evaluate: (args) => blankToNull(args[0], (input) => {
+            const digits = args.length > 1 ? Math.trunc(readFormulaNumber(args[1], "round")) : 0;
+            const factor = 10 ** digits;
+            return Math.round(readFormulaNumber(input, "round") * factor) / factor;
+        }),
+    }),
+    spec({
+        name: "floor",
+        category: "number",
+        signature: "floor(value)",
+        description: "Rounds down to the nearest integer. Blank input is null.",
+        minArgs: 1,
+        maxArgs: 1,
+        examples: [{ expression: "floor(3.9)", result: 3 }],
+        evaluate: (args) => blankToNull(args[0], (input) => Math.floor(readFormulaNumber(input, "floor"))),
+    }),
+    spec({
+        name: "ceil",
+        category: "number",
+        signature: "ceil(value)",
+        description: "Rounds up to the nearest integer. Blank input is null.",
+        minArgs: 1,
+        maxArgs: 1,
+        examples: [{ expression: "ceil(3.1)", result: 4 }],
+        evaluate: (args) => blankToNull(args[0], (input) => Math.ceil(readFormulaNumber(input, "ceil"))),
+    }),
+    spec({
+        name: "abs",
+        category: "number",
+        signature: "abs(value)",
+        description: "Absolute value. Blank input is null.",
+        minArgs: 1,
+        maxArgs: 1,
+        examples: [{ expression: "abs(-5)", result: 5 }],
+        evaluate: (args) => blankToNull(args[0], (input) => Math.abs(readFormulaNumber(input, "abs"))),
+    }),
+    spec({
+        name: "min",
+        category: "number",
+        signature: "min(a, b, ...)",
+        description: "Smallest numeric argument; arrays are flattened one level; blanks are skipped. All-blank input is null.",
+        minArgs: 1,
+        maxArgs: null,
+        examples: [{ expression: "min(score_a, score_b)", result: 40 }],
+        evaluate: (args) => {
+            const values = collectNumericArgs(args, "min");
+            return values.length === 0 ? null : Math.min(...values);
+        },
+    }),
+    spec({
+        name: "max",
+        category: "number",
+        signature: "max(a, b, ...)",
+        description: "Largest numeric argument; arrays are flattened one level; blanks are skipped. All-blank input is null.",
+        minArgs: 1,
+        maxArgs: null,
+        examples: [{ expression: "max(score_a, score_b)", result: 90 }],
+        evaluate: (args) => {
+            const values = collectNumericArgs(args, "max");
+            return values.length === 0 ? null : Math.max(...values);
+        },
+    }),
+    spec({
+        name: "sum",
+        category: "number",
+        signature: "sum(a, b, ...)",
+        description: "Sum of the numeric arguments; arrays are flattened one level; blanks are skipped. All-blank input is 0.",
+        minArgs: 1,
+        maxArgs: null,
+        examples: [{ expression: "sum(path(payload, \"amounts\"))", result: 150 }],
+        evaluate: (args) => collectNumericArgs(args, "sum").reduce((total, value) => total + value, 0),
+    }),
+    spec({
+        name: "avg",
+        category: "number",
+        signature: "avg(a, b, ...)",
+        description: "Average of the numeric arguments; arrays are flattened one level; blanks are skipped. All-blank input is null.",
+        minArgs: 1,
+        maxArgs: null,
+        examples: [{ expression: "avg(q1, q2, q3)", result: 25 }],
+        evaluate: (args) => {
+            const values = collectNumericArgs(args, "avg");
+            if (values.length === 0)
+                return null;
+            return values.reduce((total, value) => total + value, 0) / values.length;
+        },
+    }),
+    // --- date -------------------------------------------------------------------
+    spec({
+        name: "now",
+        category: "date",
+        signature: "now()",
+        description: "The current timestamp as a UTC ISO-8601 string.",
+        minArgs: 0,
+        maxArgs: 0,
+        examples: [{ expression: "now()", result: "2026-07-13T12:00:00.000Z" }],
+        evaluate: () => new Date().toISOString(),
+    }),
+    spec({
+        name: "today",
+        category: "date",
+        signature: "today()",
+        description: "The current UTC date as YYYY-MM-DD.",
+        minArgs: 0,
+        maxArgs: 0,
+        examples: [{ expression: "today()", result: "2026-07-13" }],
+        evaluate: () => new Date().toISOString().slice(0, 10),
+    }),
+    spec({
+        name: "date_parse",
+        category: "date",
+        signature: "date_parse(value)",
+        description: "Parses an ISO-8601 string, YYYY-MM-DD date, or epoch-milliseconds number into a UTC ISO timestamp. Unparseable input returns null (dirty data flows instead of failing the run).",
+        minArgs: 1,
+        maxArgs: 1,
+        examples: [{ expression: "date_parse(\"2026-07-13\")", result: "2026-07-13T00:00:00.000Z" }],
+        evaluate: (args) => parseFormulaDate(args[0])?.toISOString() ?? null,
+    }),
+    spec({
+        name: "date_format",
+        category: "date",
+        signature: "date_format(date, format)",
+        description: "Formats a date in UTC using YYYY, MM, DD, HH, mm, ss tokens. Unparseable input returns null.",
+        minArgs: 2,
+        maxArgs: 2,
+        examples: [{ expression: "date_format(created_at, \"YYYY-MM-DD\")", result: "2026-07-13" }],
+        evaluate: (args) => {
+            const date = parseFormulaDate(args[0]);
+            return date ? formatUtcDate(date, asText(args[1])) : null;
+        },
+    }),
+    spec({
+        name: "date_diff",
+        category: "date",
+        signature: "date_diff(later, earlier, unit)",
+        description: "Whole units between two dates (later minus earlier; negative when reversed). Units: seconds, minutes, hours, days, weeks, months, years — months/years use calendar arithmetic. Unparseable input returns null.",
+        minArgs: 3,
+        maxArgs: 3,
+        examples: [{ expression: "date_diff(now(), last_reply_at, \"days\")", result: 12 }],
+        evaluate: (args) => {
+            const later = parseFormulaDate(args[0]);
+            const earlier = parseFormulaDate(args[1]);
+            if (!later || !earlier)
+                return null;
+            const unit = readDateUnit(args[2], "date_diff");
+            if (unit === "months")
+                return calendarMonthsBetween(later, earlier);
+            if (unit === "years")
+                return Math.trunc(calendarMonthsBetween(later, earlier) / 12);
+            const unitMs = DATE_UNIT_MS[unit];
+            if (!unitMs)
+                return null;
+            return Math.trunc((later.getTime() - earlier.getTime()) / unitMs);
+        },
+    }),
+    spec({
+        name: "date_add",
+        category: "date",
+        signature: "date_add(date, amount, unit)",
+        description: "Adds an amount of units to a date (negative subtracts) and returns a UTC ISO timestamp. Month/year additions clamp to the last day of the target month. Unparseable input returns null.",
+        minArgs: 3,
+        maxArgs: 3,
+        examples: [{ expression: "date_add(today(), 7, \"days\")", result: "2026-07-20T00:00:00.000Z" }],
+        evaluate: (args) => {
+            const date = parseFormulaDate(args[0]);
+            if (!date)
+                return null;
+            const amount = readFormulaNumber(args[1], "date_add");
+            const unit = readDateUnit(args[2], "date_add");
+            if (unit === "months")
+                return addCalendarMonths(date, Math.trunc(amount)).toISOString();
+            if (unit === "years")
+                return addCalendarMonths(date, Math.trunc(amount) * 12).toISOString();
+            const unitMs = DATE_UNIT_MS[unit];
+            if (!unitMs)
+                return null;
+            return new Date(date.getTime() + amount * unitMs).toISOString();
+        },
+    }),
+    // --- url / email --------------------------------------------------------------
+    spec({
+        name: "email_domain",
+        category: "url_email",
+        signature: "email_domain(email)",
+        description: "The canonical domain of an email address (lowercased, www/trailing dots stripped). Blank or @-less input returns null.",
+        minArgs: 1,
+        maxArgs: 1,
+        examples: [{ expression: "email_domain(\"Jo@Acme.com\")", result: "acme.com" }],
+        evaluate: (args) => {
+            if (isBlankFormulaValue(args[0]))
+                return null;
+            const input = asText(args[0]).trim();
+            const at = input.lastIndexOf("@");
+            if (at <= 0 || at === input.length - 1)
+                return null;
+            const domain = normalizeDomain(input.slice(at + 1));
+            return domain || null;
+        },
+    }),
+    spec({
+        name: "domain_of",
+        category: "url_email",
+        signature: "domain_of(url_or_domain)",
+        description: "Reduces a URL, hostname, or bare domain to its canonical form — identical normalization to CRM company-domain identity matching.",
+        minArgs: 1,
+        maxArgs: 1,
+        examples: [{ expression: "domain_of(\"https://www.Acme.com/about\")", result: "acme.com" }],
+        evaluate: (args) => {
+            if (isBlankFormulaValue(args[0]))
+                return null;
+            const domain = normalizeDomain(asText(args[0]));
+            return domain || null;
+        },
+    }),
+    spec({
+        name: "normalize_email",
+        category: "url_email",
+        signature: "normalize_email(email)",
+        description: "Canonical email form (trimmed, lowercased) — identical to CRM email identity matching.",
+        minArgs: 1,
+        maxArgs: 1,
+        examples: [{ expression: "normalize_email(\" Jo@Acme.COM \")", result: "jo@acme.com" }],
+        evaluate: (args) => blankToNull(args[0], (input) => normalizeEmail(asText(input))),
+    }),
+    spec({
+        name: "normalize_url",
+        category: "url_email",
+        signature: "normalize_url(url)",
+        description: "Canonical URL form: https scheme assumed when missing, lowercased host, trailing slashes stripped. Unparseable input returns the trimmed original.",
+        minArgs: 1,
+        maxArgs: 1,
+        examples: [{ expression: "normalize_url(\"WWW.Acme.com/pricing/\")", result: "https://www.acme.com/pricing" }],
+        evaluate: (args) => blankToNull(args[0], (input) => {
+            const raw = asText(input).trim();
+            try {
+                const parsed = new URL(raw.includes("://") ? raw : `https://${raw}`);
+                const path = parsed.pathname.replace(/\/+$/, "");
+                return `${parsed.protocol}//${parsed.hostname.toLowerCase()}${path}${parsed.search}`;
+            }
+            catch {
+                return raw;
+            }
+        }),
+    }),
+    spec({
+        name: "normalize_linkedin_url",
+        category: "url_email",
+        signature: "normalize_linkedin_url(url)",
+        description: "Canonical LinkedIn URL form (trimmed, lowercased, trailing slashes stripped) — identical to CRM LinkedIn identity matching.",
+        minArgs: 1,
+        maxArgs: 1,
+        examples: [{ expression: "normalize_linkedin_url(\"https://linkedin.com/in/Ada/\")", result: "https://linkedin.com/in/ada" }],
+        evaluate: (args) => blankToNull(args[0], (input) => normalizeLinkedinUrl(asText(input))),
+    }),
+    // --- array -----------------------------------------------------------------
+    spec({
+        name: "first",
+        category: "array",
+        signature: "first(array)",
+        description: "First element of an array, or null when empty/blank.",
+        minArgs: 1,
+        maxArgs: 1,
+        examples: [{ expression: "first(path(payload, \"emails\"))", result: "jo@acme.com" }],
+        evaluate: (args) => (Array.isArray(args[0]) ? args[0][0] ?? null : null),
+    }),
+    spec({
+        name: "last",
+        category: "array",
+        signature: "last(array)",
+        description: "Last element of an array, or null when empty/blank.",
+        minArgs: 1,
+        maxArgs: 1,
+        examples: [{ expression: "last(split(name, \" \"))", result: "Lovelace" }],
+        evaluate: (args) => (Array.isArray(args[0]) ? args[0][args[0].length - 1] ?? null : null),
+    }),
+    spec({
+        name: "count",
+        category: "array",
+        signature: "count(value)",
+        description: "Number of items in an array; 0 for blank; 1 for any other non-blank value.",
+        minArgs: 1,
+        maxArgs: 1,
+        examples: [{ expression: "count(path(payload, \"jobs\"))", result: 3 }],
+        evaluate: (args) => {
+            if (isBlankFormulaValue(args[0]))
+                return 0;
+            return Array.isArray(args[0]) ? args[0].length : 1;
+        },
+    }),
+    spec({
+        name: "pluck",
+        category: "array",
+        signature: "pluck(array, path)",
+        description: "Maps each array element through a dot-separated JSON path, dropping blank results.",
+        minArgs: 2,
+        maxArgs: 2,
+        examples: [{ expression: "pluck(path(payload, \"contacts\"), \"email\")", result: ["a@x.com", "b@y.com"] }],
+        evaluate: (args) => {
+            if (!Array.isArray(args[0]))
+                return [];
+            if (typeof args[1] !== "string") {
+                throw formulaExpressionError("pluck requires a string path argument.", { function: "pluck" });
+            }
+            const path = args[1];
+            return args[0]
+                .map((element) => readFormulaJsonPath(element, path))
+                .filter((value) => !isBlankFormulaValue(value));
+        },
+    }),
+    spec({
+        name: "unique",
+        category: "array",
+        signature: "unique(array)",
+        description: "Removes duplicate elements (deep equality), preserving first-seen order.",
+        minArgs: 1,
+        maxArgs: 1,
+        examples: [{ expression: "unique(split(\"a,b,a\", \",\"))", result: ["a", "b"] }],
+        evaluate: (args) => {
+            if (!Array.isArray(args[0]))
+                return [];
+            const seen = new Set();
+            const result = [];
+            for (const element of args[0]) {
+                const key = JSON.stringify(element) ?? "undefined";
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                result.push(element);
+            }
+            return result;
+        },
+    }),
+    // --- json ------------------------------------------------------------------
+    spec({
+        name: "path",
+        category: "json",
+        signature: "path(value, \"a.b.0\")",
+        description: "Reads a dot-separated path (object keys and array indexes) out of a JSON value; missing paths return null.",
+        minArgs: 2,
+        maxArgs: 2,
+        examples: [{ expression: "path(enrichment, \"company.size\")", result: "51-200" }],
+        evaluate: (args) => {
+            if (typeof args[1] !== "string") {
+                throw formulaExpressionError("path requires a string path argument.", {
+                    function: "path",
+                });
+            }
+            return readFormulaJsonPath(args[0], args[1]);
+        },
+    }),
+    // --- null handling -----------------------------------------------------------
+    spec({
+        name: "coalesce",
+        category: "null_handling",
+        signature: "coalesce(a, b, ...)",
+        description: "First non-blank argument, or null when all are blank.",
+        minArgs: 0,
+        maxArgs: null,
+        examples: [{ expression: "coalesce(work_email, personal_email)", result: "jo@acme.com" }],
+        evaluate: (args) => args.find((arg) => !isBlankFormulaValue(arg)) ?? null,
+    }),
+    spec({
+        name: "default",
+        category: "null_handling",
+        signature: "default(value, fallback)",
+        description: "The value when it is non-blank, otherwise the fallback.",
+        minArgs: 2,
+        maxArgs: 2,
+        examples: [{ expression: "default(title, \"(unknown)\")", result: "(unknown)" }],
+        evaluate: (args) => (isBlankFormulaValue(args[0]) ? args[1] ?? null : args[0]),
+    }),
+    spec({
+        name: "ifblank",
+        category: "null_handling",
+        signature: "ifblank(value, fallback)",
+        description: "Alias of default(value, fallback).",
+        minArgs: 2,
+        maxArgs: 2,
+        examples: [{ expression: "ifblank(phone, \"n/a\")", result: "n/a" }],
+        evaluate: (args) => (isBlankFormulaValue(args[0]) ? args[1] ?? null : args[0]),
+    }),
+    spec({
+        name: "is_blank",
+        category: "null_handling",
+        signature: "is_blank(value)",
+        description: "True when the value is null, empty text, or an empty array.",
+        minArgs: 1,
+        maxArgs: 1,
+        examples: [{ expression: "is_blank(email)", result: false }],
+        evaluate: (args) => isBlankFormulaValue(args[0]),
+    }),
+    // --- cross row ----------------------------------------------------------------
+    spec({
+        name: "novelty_score",
+        category: "cross_row",
+        signature: "novelty_score(column)",
+        description: "0..1 novelty of this row's value versus every other row's value in the same column (1 = unique). Requires a sync columns run so the column corpus can load; executed by the runner, not this registry.",
+        minArgs: 1,
+        maxArgs: 1,
+        examples: [{ expression: "novelty_score(opening_line)", result: 0.8731 }],
+        // No evaluate: the runner intercepts cross-row calls before registry dispatch.
+    }),
+];
+export const FORMULA_FUNCTION_REGISTRY = new Map(SPECS.map((entry) => [entry.name, entry]));
+export const FORMULA_FUNCTION_CATEGORIES = [
+    "logic",
+    "string",
+    "number",
+    "date",
+    "url_email",
+    "array",
+    "json",
+    "null_handling",
+    "cross_row",
+];
+export function listFormulaFunctions(category) {
+    return SPECS
+        .filter((entry) => !category || entry.category === category)
+        .map(({ name, category: entryCategory, signature, description, minArgs, maxArgs, examples }) => ({
+        name,
+        category: entryCategory,
+        signature,
+        description,
+        minArgs,
+        maxArgs,
+        examples,
+    }));
+}
+/** Operators the expression language supports, for the discovery surfaces. */
+export const FORMULA_OPERATORS = [
+    { operator: "+ - * / %", description: "Arithmetic (numbers or numeric strings)." },
+    { operator: "= == != <>", description: "Equality (numbers compare numerically)." },
+    { operator: "< <= > >=", description: "Comparison (numbers numerically, text lexicographically)." },
+    { operator: "and or not (&& || !)", description: "Boolean logic with short-circuit evaluation." },
+    { operator: "( )", description: "Grouping and function calls." },
+];