@vibesdotdev/tools 0.0.0-stage → 1.0.0-rc.3

package/dist/audit-ledger/parser.js

@@ -0,0 +1,243 @@
+/**
+ * Audit Ledger Parser
+ *
+ * Parses the claims-table format used by `docs/audits/** /LEDGER.md` files —
+ * see `docs/audits/tui-agentic/LEDGER.md` for the canonical example and
+ * `docs/proposals/tui-followon-program/README.md` for the status vocabulary
+ * (`UNVERIFIED` / `PARTIAL` / `CONFIRMED` / `REFUTED→FIXED(<commit>)`).
+ *
+ * Pure, no I/O — callers read the file and pass `path` + `content`. A ledger
+ * can hold several claims tables (P0/P1/P2 sections); every table whose
+ * header declares both a `Claim` and a `Status` column is parsed, in file
+ * order. Tables that don't declare those columns (e.g. a "Pass log" or a
+ * `PROGRAM.md`-style contract table) are left alone.
+ *
+ * Deliberately strict: a claims-table header without a valid separator row,
+ * a data row whose column count doesn't match the header, or a data row with
+ * an empty Claim/Status cell all refuse `INVALID_INPUT` `ledger-parse-invalid` rather than being
+ * silently skipped — a checker that can't trust its own parse must not
+ * report a false "fully confirmed".
+ *
+ * Also deliberately strict about *qualified* confirmations: a cell that starts
+ * "CONFIRMED"/"REFUTED→FIXED" but smuggles in a disqualifying caveat — outside OR
+ * inside its parenthetical evidence, e.g. "CONFIRMED (all layers) except the live
+ * smoke (blocked by local AI gate)" — is downgraded to `QUALIFIED`/`passes:false`
+ * rather than counted as done. See `QUALIFIER_WORDS` for the exact vocabulary and
+ * the hyphen-compound carve-out that keeps plain prose like "server-blocked upstream"
+ * passing.
+ */
+import { CapabilityError } from '@vibesdotdev/kernel';
+/** The refusal for a ledger the parser cannot trust: names the file and, when known, the line. */
+export function ledgerParseFailure(message, path, line) {
+    return new CapabilityError(`${path}${line ? `:${line}` : ''} — ${message}`, 'INVALID_INPUT', {
+        reason: 'ledger-parse-invalid',
+        retryable: false,
+        details: line === undefined ? { path } : { path, line }
+    });
+}
+const HEADER_ALIASES = {
+    id: new Set(['#']),
+    claim: new Set(['claim']),
+    status: new Set(['status']),
+    evidence: new Set(['evidence', 'evidence / next probe', 'evidence/next probe'])
+};
+const ARROW_RE = /→|->/;
+const SEPARATOR_CELL_RE = /^:?-{1,}:?$/;
+/**
+ * Disqualifying-qualifier vocabulary (case-insensitive). A status cell that otherwise
+ * reads as a terminal CONFIRMED/REFUTED→FIXED is still a FAIL if one of these words
+ * shows up anywhere in the cell — including inside its parenthetical evidence, which is
+ * exactly the smuggle vector ("CONFIRMED ... except the live smoke (blocked by ...)").
+ *
+ * Matching is word-boundary-aware but hyphen-sensitive on purpose: a qualifier fused
+ * into a hyphenated compound (`server-blocked`, `open-ended`) reads as ordinary
+ * technical prose describing *what*, not a disqualifying claim about *this status* — so
+ * it's deliberately excluded. A qualifier set off by whitespace or punctuation (`blocked
+ * by local AI gate`, `except the live smoke`, `/ open for UI`) is exactly the pattern
+ * this guard exists to catch.
+ */
+const QUALIFIER_WORDS = [
+    'except',
+    'blocked',
+    'pending',
+    'open',
+    'partial',
+    'todo',
+    'unverified',
+    'awaiting',
+    'remaining'
+];
+const QUALIFIER_RE = new RegExp(`(?<![A-Za-z-])(${QUALIFIER_WORDS.join('|')})(?![A-Za-z-])`, 'gi');
+/** Finds every disqualifying qualifier word in `raw`, lower-cased and deduped, in first-seen order. */
+function findQualifiers(raw) {
+    const found = [];
+    for (const match of raw.matchAll(QUALIFIER_RE)) {
+        const word = match[1].toLowerCase();
+        if (!found.includes(word))
+            found.push(word);
+    }
+    return found;
+}
+function normalizeHeaderCell(cell) {
+    return cell.trim().toLowerCase().replace(/\s+/g, ' ');
+}
+function isTableRow(line) {
+    const trimmed = line.trim();
+    return trimmed.startsWith('|') && trimmed.endsWith('|') && trimmed.length > 1;
+}
+/** Splits a markdown table row on `|`, ignoring pipes inside backtick-quoted spans. */
+function splitTableRow(rawLine) {
+    const trimmed = rawLine.trim();
+    const body = trimmed.slice(1, -1); // drop the leading/trailing '|'
+    const cells = [];
+    let current = '';
+    let inCode = false;
+    for (const ch of body) {
+        if (ch === '`') {
+            inCode = !inCode;
+            current += ch;
+            continue;
+        }
+        if (ch === '|' && !inCode) {
+            cells.push(current.trim());
+            current = '';
+            continue;
+        }
+        current += ch;
+    }
+    cells.push(current.trim());
+    return cells;
+}
+function isSeparatorRow(line, expectedColumns) {
+    if (!isTableRow(line))
+        return false;
+    const cells = splitTableRow(line);
+    if (cells.length !== expectedColumns)
+        return false;
+    return cells.every((cell) => SEPARATOR_CELL_RE.test(cell.trim()));
+}
+function baseStatusOf(last) {
+    if (/^CONFIRMED\b/i.test(last))
+        return { status: 'CONFIRMED', passes: true };
+    if (/^FIXED\s*\(/i.test(last))
+        return { status: 'REFUTED_FIXED', passes: true };
+    if (/^PARTIAL\b/i.test(last))
+        return { status: 'PARTIAL', passes: false };
+    if (/^UNVERIFIED\b/i.test(last))
+        return { status: 'UNVERIFIED', passes: false };
+    if (/^REFUTED\b/i.test(last))
+        return { status: 'REFUTED', passes: false };
+    return { status: 'UNKNOWN', passes: false };
+}
+function classifyStatus(raw) {
+    const trimmed = raw.trim();
+    const segments = trimmed
+        .split(ARROW_RE)
+        .map((segment) => segment.trim())
+        .filter(Boolean);
+    const fixCommits = [];
+    for (const segment of segments) {
+        const match = segment.match(/FIXED\s*\(([^)]*)\)/i);
+        if (match?.[1]) {
+            fixCommits.push(...match[1]
+                .split(',')
+                .map((commit) => commit.trim())
+                .filter(Boolean));
+        }
+    }
+    const last = segments[segments.length - 1] ?? '';
+    const base = baseStatusOf(last);
+    // A cell that otherwise reads as a clean terminal state (CONFIRMED / REFUTED→FIXED)
+    // is still disqualified if a qualifier word smuggles a caveat in anywhere in the
+    // cell — including its parenthetical evidence. Non-terminal statuses (PARTIAL,
+    // UNVERIFIED, REFUTED, UNKNOWN) are already failing on their own terms and keep
+    // their own status rather than being relabeled QUALIFIED.
+    if (base.passes) {
+        const qualifiers = findQualifiers(trimmed);
+        if (qualifiers.length > 0) {
+            return { status: 'QUALIFIED', passes: false, fixCommits, qualifiers };
+        }
+    }
+    return { ...base, fixCommits };
+}
+export function parseLedgerMarkdown(path, content) {
+    const lines = content.split(/\r?\n/);
+    const claims = [];
+    let tableCount = 0;
+    let currentSection;
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i] ?? '';
+        const headingMatch = line.match(/^#{1,6}\s+(.+?)\s*$/);
+        if (headingMatch?.[1]) {
+            currentSection = headingMatch[1];
+            i++;
+            continue;
+        }
+        if (!isTableRow(line)) {
+            i++;
+            continue;
+        }
+        // Candidate table header.
+        const headerLineNumber = i + 1;
+        const headerCells = splitTableRow(line);
+        const normalizedHeader = headerCells.map(normalizeHeaderCell);
+        const idIdx = normalizedHeader.findIndex((cell) => HEADER_ALIASES.id.has(cell));
+        const claimIdx = normalizedHeader.findIndex((cell) => HEADER_ALIASES.claim.has(cell));
+        const statusIdx = normalizedHeader.findIndex((cell) => HEADER_ALIASES.status.has(cell));
+        const evidenceIdx = normalizedHeader.findIndex((cell) => HEADER_ALIASES.evidence.has(cell));
+        const looksLikeClaimsTable = claimIdx !== -1 && statusIdx !== -1;
+        const separatorLine = lines[i + 1];
+        const hasValidSeparator = separatorLine !== undefined && isSeparatorRow(separatorLine, headerCells.length);
+        if (looksLikeClaimsTable && !hasValidSeparator) {
+            throw ledgerParseFailure('Claims table header (Claim + Status columns) is not followed by a valid separator row', path, headerLineNumber);
+        }
+        if (!looksLikeClaimsTable) {
+            // Some other table (pass log, program contract, etc.) — skip its rows
+            // without treating malformed structure there as an error; it isn't ours.
+            i++;
+            while (i < lines.length && isTableRow(lines[i] ?? ''))
+                i++;
+            continue;
+        }
+        tableCount++;
+        const columnCount = headerCells.length;
+        i += 2; // past header + separator
+        while (i < lines.length && isTableRow(lines[i] ?? '')) {
+            const rowLineNumber = i + 1;
+            const cells = splitTableRow(lines[i] ?? '');
+            if (cells.length !== columnCount) {
+                throw ledgerParseFailure(`Claims table row has ${cells.length} column(s), expected ${columnCount} (matching the header)`, path, rowLineNumber);
+            }
+            const statusRaw = cells[statusIdx] ?? '';
+            if (!statusRaw.trim()) {
+                throw ledgerParseFailure('Claims table row has an empty Status cell', path, rowLineNumber);
+            }
+            const claimText = cells[claimIdx] ?? '';
+            if (!claimText.trim()) {
+                throw ledgerParseFailure('Claims table row has an empty Claim cell', path, rowLineNumber);
+            }
+            const { status, passes, fixCommits, qualifiers } = classifyStatus(statusRaw);
+            const claim = {
+                id: idIdx !== -1 ? (cells[idIdx] ?? String(claims.length + 1)) : String(claims.length + 1),
+                claim: claimText,
+                statusRaw,
+                status,
+                fixCommits,
+                passes,
+                evidence: evidenceIdx !== -1 ? cells[evidenceIdx] : undefined,
+                line: rowLineNumber,
+                section: currentSection
+            };
+            if (qualifiers && qualifiers.length > 0)
+                claim.qualifiers = qualifiers;
+            claims.push(claim);
+            i++;
+        }
+    }
+    if (tableCount === 0) {
+        throw ledgerParseFailure('No claims table found (expected a markdown table with "Claim" and "Status" columns)', path);
+    }
+    return { path, claims, tableCount };
+}
+//# sourceMappingURL=parser.js.map

package/dist/audit-ledger/parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.js","sourceRoot":"","sources":["../../src/audit-ledger/parser.ts"],"names":[],"mappings":"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"}

package/dist/calculate/calculate.plugin.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Calculate Tool Plugin
+ *
+ * Registers the `calculate` tool (descriptor + lazy implementation loader) against
+ * the `tools/tool` kind owned by @vibesdotdev/tools. Composed by the plugins-core
+ * bundle (or apps via vibes.config) — never by @vibesdotdev/tools itself, which must
+ * stay pure framework/runtime and cannot depend on its implementations.
+ */
+declare const defaultExport: import("@vibesdotdev/kernel").RuntimePlugin;
+export default defaultExport;
+//# sourceMappingURL=calculate.plugin.d.ts.map

package/dist/calculate/calculate.plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"calculate.plugin.d.ts","sourceRoot":"","sources":["../../src/calculate/calculate.plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAQH,QAAA,MAAM,aAAa,6CAOjB,CAAC;AAEH,eAAe,aAAa,CAAC"}

package/dist/calculate/calculate.plugin.js

@@ -0,0 +1,22 @@
+/**
+ * Calculate Tool Plugin
+ *
+ * Registers the `calculate` tool (descriptor + lazy implementation loader) against
+ * the `tools/tool` kind owned by @vibesdotdev/tools. Composed by the plugins-core
+ * bundle (or apps via vibes.config) — never by @vibesdotdev/tools itself, which must
+ * stay pure framework/runtime and cannot depend on its implementations.
+ */
+import { createRuntimePlugin, loader } from '@vibesdotdev/kernel';
+import calculateTool from "./tools/calculate.descriptor.js";
+const TOOL = { kind: 'tools/tool' };
+// Hoisted const: tsc rewriteRelativeImportExtensions does not rewrite `.ts` specifiers inside `export default <expr>` (TS 6.0.3).
+const defaultExport = createRuntimePlugin({
+    id: 'tool-calculate',
+    name: 'Calculate Tool',
+    description: 'Safely evaluate mathematical expressions',
+    dependencies: ['tools'],
+    descriptors: [calculateTool],
+    loaders: [loader('calculate', TOOL, () => import("./tools/calculate.impl.js"))]
+});
+export default defaultExport;
+//# sourceMappingURL=calculate.plugin.js.map

package/dist/calculate/calculate.plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"calculate.plugin.js","sourceRoot":"","sources":["../../src/calculate/calculate.plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAClE,OAAO,aAAa,MAAM,iCAAiC,CAAC;AAE5D,MAAM,IAAI,GAAG,EAAE,IAAI,EAAE,YAAY,EAAW,CAAC;AAE7C,kIAAkI;AAClI,MAAM,aAAa,GAAG,mBAAmB,CAAC;IACzC,EAAE,EAAE,gBAAgB;IACpB,IAAI,EAAE,gBAAgB;IACtB,WAAW,EAAE,0CAA0C;IACvD,YAAY,EAAE,CAAC,OAAO,CAAC;IACvB,WAAW,EAAE,CAAC,aAAa,CAAC;IAC5B,OAAO,EAAE,CAAC,MAAM,CAAC,WAAW,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,2BAA2B,CAAC,CAAC,CAAC;CAC/E,CAAC,CAAC;AAEH,eAAe,aAAa,CAAC"}

package/dist/calculate/helpers.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Helper functions for calculate tool
+ */
+/** A calculation broken into the steps a reader can follow. */
+interface CalculationAnalysis {
+    steps: string[];
+    explanation: string;
+}
+/**
+ * Validates if a string is a safe mathematical expression
+ * Prevents code injection and other security issues
+ */
+export declare function isValidMathExpression(expression: string): boolean;
+/**
+ * Checks if a string has balanced brackets/parentheses
+ */
+export declare function hasBalancedBrackets(expression: string): boolean;
+/**
+ * Prepares an expression for evaluation by handling common
+ * mathematical functions and operations
+ */
+export declare function prepareExpression(expression: string): string;
+/**
+ * Analyze a calculation and break it down into steps
+ */
+export declare function analyzeCalculation(originalExpression: string, _preparedExpression: string): CalculationAnalysis;
+/**
+ * Safely evaluates a prepared mathematical expression without code generation
+ * (no eval / new Function), so it runs on workerd as well as Bun/Node.
+ */
+export declare function evaluateExpression(expression: string): number;
+export {};
+//# sourceMappingURL=helpers.d.ts.map

package/dist/calculate/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/calculate/helpers.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH,+DAA+D;AAC/D,UAAU,mBAAmB;IAC5B,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAsCjE;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAc/D;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAqB5D;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CACjC,kBAAkB,EAAE,MAAM,EAC1B,mBAAmB,EAAE,MAAM,GACzB,mBAAmB,CAqFrB;AAoKD;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAe7D"}

package/dist/calculate/helpers.js

@@ -0,0 +1,334 @@
+/**
+ * Helper functions for calculate tool
+ */
+import { CapabilityError, CaughtFailureSchema } from '@vibesdotdev/kernel';
+import { attemptSync } from "../shared/attempt.js";
+/**
+ * Validates if a string is a safe mathematical expression
+ * Prevents code injection and other security issues
+ */
+export function isValidMathExpression(expression) {
+    // Remove all whitespace
+    const cleaned = expression.replace(/\s+/g, '');
+    // List of allowed mathematical functions
+    const allowedFunctions = [
+        'sqrt',
+        'sin',
+        'cos',
+        'tan',
+        'log',
+        'exp',
+        'abs',
+        'round',
+        'floor',
+        'ceil'
+    ];
+    // Remove allowed function names to check remaining characters
+    let withoutFunctions = cleaned;
+    for (const func of allowedFunctions) {
+        withoutFunctions = withoutFunctions.replace(new RegExp(func, 'gi'), '');
+    }
+    // Check if remaining expression contains only valid math characters
+    const validChars = /^[0-9+\-*/().^%,\s\t\n]*$/;
+    const containsOnlyMathChars = validChars.test(withoutFunctions);
+    // Check for balanced parentheses
+    const hasBalancedParentheses = hasBalancedBrackets(expression);
+    // Check for javascript code patterns that might indicate injection attempts
+    const hasCodePatterns = /function|return|var|let|const|=>|\{|\}|;|eval|new|class|require|import|export|this|window|document|global/.test(expression);
+    return containsOnlyMathChars && hasBalancedParentheses && !hasCodePatterns;
+}
+/**
+ * Checks if a string has balanced brackets/parentheses
+ */
+export function hasBalancedBrackets(expression) {
+    const stack = [];
+    for (let i = 0; i < expression.length; i++) {
+        const char = expression[i];
+        if (char === '(') {
+            stack.push(char);
+        }
+        else if (char === ')') {
+            if (stack.length === 0)
+                return false;
+            stack.pop();
+        }
+    }
+    return stack.length === 0;
+}
+/**
+ * Prepares an expression for evaluation by handling common
+ * mathematical functions and operations
+ */
+export function prepareExpression(expression) {
+    let prepared = expression.trim();
+    // Replace common mathematical operations
+    prepared = prepared
+        // Replace power operations
+        .replace(/(\d+)\s*\^\s*(\d+)/g, 'Math.pow($1, $2)')
+        // Replace square root
+        .replace(/sqrt\s*\(\s*([^)]+)\s*\)/gi, 'Math.sqrt($1)')
+        // Replace other common functions
+        .replace(/sin\s*\(\s*([^)]+)\s*\)/gi, 'Math.sin($1)')
+        .replace(/cos\s*\(\s*([^)]+)\s*\)/gi, 'Math.cos($1)')
+        .replace(/tan\s*\(\s*([^)]+)\s*\)/gi, 'Math.tan($1)')
+        .replace(/log\s*\(\s*([^)]+)\s*\)/gi, 'Math.log($1)')
+        .replace(/exp\s*\(\s*([^)]+)\s*\)/gi, 'Math.exp($1)')
+        .replace(/abs\s*\(\s*([^)]+)\s*\)/gi, 'Math.abs($1)')
+        .replace(/round\s*\(\s*([^)]+)\s*\)/gi, 'Math.round($1)')
+        .replace(/floor\s*\(\s*([^)]+)\s*\)/gi, 'Math.floor($1)')
+        .replace(/ceil\s*\(\s*([^)]+)\s*\)/gi, 'Math.ceil($1)');
+    return prepared;
+}
+/**
+ * Analyze a calculation and break it down into steps
+ */
+export function analyzeCalculation(originalExpression, _preparedExpression) {
+    const steps = [];
+    let explanation = '';
+    // Clean up the expressions for analysis
+    const cleanOriginal = originalExpression.replace(/\s+/g, ' ').trim();
+    // Add the original expression as the first step
+    steps.push(`Start with: ${cleanOriginal}`);
+    // Check for specific operations and provide steps
+    if (cleanOriginal.includes('^')) {
+        const matches = [...cleanOriginal.matchAll(/(\d+)\s*\^\s*(\d+)/g)];
+        for (const match of matches) {
+            const base = parseFloat(match[1]);
+            const exponent = parseFloat(match[2]);
+            const result = Math.pow(base, exponent);
+            steps.push(`Calculate ${base}^${exponent} = ${result}`);
+        }
+    }
+    // Check for parentheses and provide steps for evaluating them
+    if (cleanOriginal.includes('(')) {
+        const matches = [...cleanOriginal.matchAll(/\(([^()]+)\)/g)];
+        for (const match of matches) {
+            const innerExpr = match[1].trim();
+            // An inner expression that does not evaluate on its own is still a step to
+            // name; the whole expression is evaluated, and refused, by the caller.
+            const inner = attemptSync(() => evaluateExpression(prepareExpression(innerExpr)));
+            steps.push(inner.ok
+                ? `Evaluate (${innerExpr}) = ${inner.value}`
+                : `Evaluate the expression inside parentheses: (${innerExpr})`);
+        }
+    }
+    // Check for functions and provide explanations
+    const functionMatches = cleanOriginal.match(/(\w+)\s*\(/);
+    if (functionMatches) {
+        const functionName = functionMatches[1].toLowerCase();
+        switch (functionName) {
+            case 'sqrt':
+                steps.push(`Calculate the square root of the argument`);
+                break;
+            case 'sin':
+            case 'cos':
+            case 'tan':
+                steps.push(`Calculate the ${functionName} trigonometric function of the argument`);
+                break;
+            case 'log':
+                steps.push(`Calculate the natural logarithm of the argument`);
+                break;
+            case 'abs':
+                steps.push(`Calculate the absolute value of the argument`);
+                break;
+        }
+    }
+    // For arithmetic expressions, break down by operator precedence
+    const hasMultipleOperations = /[+\-*/].*[+\-*/]/.test(cleanOriginal);
+    if (hasMultipleOperations) {
+        steps.push(`Following order of operations (PEMDAS): Parentheses, Exponents, Multiplication/Division, Addition/Subtraction`);
+        // For multiplication and division
+        if (['*', '/'].some((op) => cleanOriginal.includes(op))) {
+            steps.push(`Perform multiplication and division operations from left to right`);
+        }
+        // For addition and subtraction
+        if (['+', '-'].some((op) => cleanOriginal.includes(op))) {
+            steps.push(`Perform addition and subtraction operations from left to right`);
+        }
+    }
+    // Generate a detailed explanation
+    if (steps.length > 1) {
+        explanation = `To calculate "${cleanOriginal}": ${steps.slice(1).join('. ')}. The result is obtained by evaluating the expression following standard mathematical rules.`;
+    }
+    else {
+        explanation = `The expression "${cleanOriginal}" is evaluated following standard mathematical rules.`;
+    }
+    return { steps, explanation };
+}
+const MATH_FUNCS = new Map([
+    ['Math.pow', Math.pow],
+    ['Math.sqrt', Math.sqrt],
+    ['Math.cbrt', Math.cbrt],
+    ['Math.sin', Math.sin],
+    ['Math.cos', Math.cos],
+    ['Math.tan', Math.tan],
+    ['Math.log', Math.log],
+    ['Math.log2', Math.log2],
+    ['Math.log10', Math.log10],
+    ['Math.exp', Math.exp],
+    ['Math.abs', Math.abs],
+    ['Math.round', Math.round],
+    ['Math.floor', Math.floor],
+    ['Math.ceil', Math.ceil],
+    ['Math.sign', Math.sign],
+    ['Math.min', Math.min],
+    ['Math.max', Math.max]
+]);
+const MATH_CONSTS = new Map([
+    ['Math.PI', Math.PI],
+    ['Math.E', Math.E],
+    ['PI', Math.PI],
+    ['E', Math.E]
+]);
+function tokenizeMath(input) {
+    const tokens = [];
+    const isDigit = (c) => c >= '0' && c <= '9';
+    let i = 0;
+    while (i < input.length) {
+        const c = input[i];
+        if (c === ' ' || c === '\t' || c === '\n' || c === '\r') {
+            i++;
+            continue;
+        }
+        if (isDigit(c) || (c === '.' && isDigit(input[i + 1] ?? ''))) {
+            let num = '';
+            while (i < input.length && (isDigit(input[i]) || input[i] === '.'))
+                num += input[i++];
+            // optional scientific-notation exponent
+            if ((input[i] === 'e' || input[i] === 'E') &&
+                (isDigit(input[i + 1] ?? '') ||
+                    ((input[i + 1] === '+' || input[i + 1] === '-') && isDigit(input[i + 2] ?? '')))) {
+                num += input[i++];
+                if (input[i] === '+' || input[i] === '-')
+                    num += input[i++];
+                while (i < input.length && isDigit(input[i]))
+                    num += input[i++];
+            }
+            tokens.push({ type: 'num', value: num });
+            continue;
+        }
+        if (/[A-Za-z_]/.test(c)) {
+            let id = '';
+            while (i < input.length && /[A-Za-z0-9_.]/.test(input[i]))
+                id += input[i++];
+            tokens.push({ type: 'ident', value: id });
+            continue;
+        }
+        if (c === '(')
+            tokens.push({ type: 'lparen', value: c });
+        else if (c === ')')
+            tokens.push({ type: 'rparen', value: c });
+        else if (c === ',')
+            tokens.push({ type: 'comma', value: c });
+        else if ('+-*/^%'.includes(c))
+            tokens.push({ type: 'op', value: c });
+        else
+            throw new Error(`Unexpected character: ${c}`);
+        i++;
+    }
+    return tokens;
+}
+function parseMath(tokens) {
+    let pos = 0;
+    const peek = () => tokens[pos];
+    const isOp = (v) => {
+        const t = peek();
+        return !!t && t.type === 'op' && t.value === v;
+    };
+    function parseExpr() {
+        let val = parseTerm();
+        while (isOp('+') || isOp('-')) {
+            const op = tokens[pos++].value;
+            const rhs = parseTerm();
+            val = op === '+' ? val + rhs : val - rhs;
+        }
+        return val;
+    }
+    function parseTerm() {
+        let val = parseFactor();
+        while (isOp('*') || isOp('/') || isOp('%')) {
+            const op = tokens[pos++].value;
+            const rhs = parseFactor();
+            val = op === '*' ? val * rhs : op === '/' ? val / rhs : val % rhs;
+        }
+        return val;
+    }
+    function parseFactor() {
+        if (isOp('-') || isOp('+')) {
+            const op = tokens[pos++].value;
+            const operand = parseFactor();
+            return op === '-' ? -operand : operand;
+        }
+        let base = parsePrimary();
+        if (isOp('^')) {
+            pos++;
+            base = Math.pow(base, parseFactor()); // right-associative
+        }
+        return base;
+    }
+    function parsePrimary() {
+        const t = peek();
+        if (!t)
+            throw new Error('Unexpected end of expression');
+        if (t.type === 'num') {
+            pos++;
+            return parseFloat(t.value);
+        }
+        if (t.type === 'lparen') {
+            pos++;
+            const v = parseExpr();
+            if (peek()?.type !== 'rparen')
+                throw new Error('Expected )');
+            pos++;
+            return v;
+        }
+        if (t.type === 'ident') {
+            pos++;
+            const constant = MATH_CONSTS.get(t.value);
+            if (constant !== undefined)
+                return constant;
+            const fn = MATH_FUNCS.get(t.value);
+            if (fn) {
+                if (peek()?.type !== 'lparen')
+                    throw new Error(`Expected ( after ${t.value}`);
+                pos++;
+                const args = [];
+                if (peek()?.type !== 'rparen') {
+                    args.push(parseExpr());
+                    while (peek()?.type === 'comma') {
+                        pos++;
+                        args.push(parseExpr());
+                    }
+                }
+                if (peek()?.type !== 'rparen')
+                    throw new Error('Expected )');
+                pos++;
+                return fn(...args);
+            }
+            throw new Error(`Unknown identifier: ${t.value}`);
+        }
+        throw new Error(`Unexpected token: ${t.value}`);
+    }
+    const result = parseExpr();
+    if (pos < tokens.length)
+        throw new Error(`Unexpected trailing token: ${tokens[pos].value}`);
+    return result;
+}
+/**
+ * Safely evaluates a prepared mathematical expression without code generation
+ * (no eval / new Function), so it runs on workerd as well as Bun/Node.
+ */
+export function evaluateExpression(expression) {
+    try {
+        const result = parseMath(tokenizeMath(expression));
+        if (!Number.isFinite(result)) {
+            throw new Error('Calculation did not produce a valid number result');
+        }
+        return result;
+    }
+    catch (error) {
+        const failure = CaughtFailureSchema.parse(error);
+        throw new CapabilityError(`Calculation error: ${failure instanceof Error ? failure.message : failure.description}`, 'INVALID_INPUT', { reason: 'calculation-invalid', cause: failure });
+    }
+}
+//# sourceMappingURL=helpers.js.map