@autochitect/engine 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CostForecast
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,102 @@
+# forecaster
+
+A 245KB WebAssembly financial modeling engine. Write cost models in a purpose-built DSL, get instant evaluation with a full dependency graph. Runs entirely client-side — no server, no latency, no data leaving the browser.
+
+## Install
+
+```bash
+npm install forecaster
+```
+
+## Quick start
+
+```javascript
+import { createEngine } from 'forecaster';
+
+const engine = await createEngine(
+  new URL('forecaster/engine.wasm', import.meta.url)
+);
+
+const result = engine.evaluate(`
+  revenue: Input
+  cost_ratio: Input
+  costs = revenue * cost_ratio
+  profit = revenue - costs
+`, {
+  revenue: 500000,
+  cost_ratio: 0.6
+});
+
+console.log(result.results);
+// { revenue: 500000, cost_ratio: 0.6, costs: 300000, profit: 200000 }
+```
+
+## What you get
+
+**`result.results`** — computed values for every variable.
+
+**`result.graph`** — the full dependency DAG showing how each value was derived. Nodes have `kind` (input, constant, formula, map, scan) and edges show data flow. Use this to build audit trails, trace calculations back to source inputs, or render interactive visualizations.
+
+**`result.errors`** / **`result.warnings`** — with line and column numbers.
+
+## The DSL
+
+The language is deliberately small. It's not a spreadsheet formula language — it's designed for financial modeling specifically.
+
+```
+# Declarations
+revenue: Input("annual_revenue")
+tax_rate: Const(0.21)
+growth: Param
+
+# Formulas
+gross_profit = revenue * (1 - cost_ratio)
+net_income = gross_profit * (1 - tax_rate)
+
+# Array operations
+periods = SEQUENCE(12, 1, 1)
+monthly = MAP(periods, LAMBDA(p, revenue / 12 * POWER(1 + growth, p)))
+
+# Accumulation
+cumulative = SCAN(monthly, 0, LAMBDA(acc, m, acc + m))
+```
+
+**Inputs** bind to external data (your JSON). **Constants** are fixed values. **References** alias other variables.
+
+**MAP** transforms arrays element-wise. **SCAN** accumulates (like reduce, but returns intermediate results). **LAMBDA** defines inline functions with named parameters.
+
+The engine compiles this into a directed acyclic graph, topologically sorts it, and evaluates in one pass. The graph is immutable — switching scenarios just swaps the input context, so it's instant.
+
+## Browser usage
+
+```html
+<script type="module">
+  import { createEngine } from './node_modules/forecaster/index.mjs';
+  const engine = await createEngine('./node_modules/forecaster/engine.wasm');
+  const result = engine.evaluate('x = 2 + 2', {});
+  document.body.textContent = JSON.stringify(result.results);
+</script>
+```
+
+## Node.js usage
+
+```javascript
+import { createEngine } from 'forecaster';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const wasmPath = join(__dirname, 'node_modules/forecaster/engine.wasm');
+const engine = await createEngine(wasmPath);
+```
+
+## Options
+
+```javascript
+// Skip the dependency graph for faster evaluation
+engine.evaluate(source, inputs, { graph: false });
+```
+
+## License
+
+MIT

package/index.d.ts

@@ -0,0 +1,27 @@
+export interface EvalResult {
+  success: boolean;
+  results: Record<string, number | number[] | string | null>;
+  errors: Array<{ message: string; line: number; col: number }>;
+  warnings: Array<{ message: string; line: number; col: number }>;
+  graph?: {
+    nodes: Array<{
+      id: number;
+      name: string;
+      kind: 'constant' | 'input' | 'param' | 'formula' | 'map' | 'scan';
+      value: number | number[] | string | null;
+      expression: string | null;
+      inputKey: string | null;
+    }>;
+    edges: Array<{ source: number; target: number }>;
+  };
+}
+
+export interface EvalOptions {
+  graph?: boolean;
+}
+
+export interface Engine {
+  evaluate(source: string, inputs?: Record<string, unknown>, options?: EvalOptions): EvalResult;
+}
+
+export function createEngine(wasmSource: string | Response | ArrayBuffer): Promise<Engine>;

package/index.mjs

@@ -0,0 +1,129 @@
+const WASI_SHIM = {
+  fd_write: (fd, iovs_ptr, iovs_len, nwritten_ptr, mem) => {
+    const view = new DataView(mem.buffer);
+    let written = 0;
+    for (let i = 0; i < iovs_len; i++) {
+      written += view.getUint32(iovs_ptr + i * 8 + 4, true);
+    }
+    view.setUint32(nwritten_ptr, written, true);
+    return 0;
+  },
+  fd_close: () => 0,
+  fd_seek: (fd, lo, hi, whence, ptr, mem) => {
+    new DataView(mem.buffer).setBigUint64(ptr, 0n, true);
+    return 0;
+  },
+  fd_fdstat_get: (fd, buf, mem) => {
+    for (let i = 0; i < 24; i++) new DataView(mem.buffer).setUint8(buf + i, 0);
+    return 0;
+  },
+  environ_sizes_get: (cp, bp, mem) => {
+    const v = new DataView(mem.buffer);
+    v.setUint32(cp, 0, true);
+    v.setUint32(bp, 0, true);
+    return 0;
+  },
+  args_sizes_get: (ap, bp, mem) => {
+    const v = new DataView(mem.buffer);
+    v.setUint32(ap, 0, true);
+    v.setUint32(bp, 0, true);
+    return 0;
+  },
+  clock_time_get: (id, prec, ptr, mem) => {
+    new DataView(mem.buffer).setBigUint64(ptr, BigInt(Date.now()) * 1000000n, true);
+    return 0;
+  },
+  proc_exit: (code) => { throw new Error(`proc_exit(${code})`); },
+};
+
+const STUB_ERRNO = {
+  fd_read: 0, fd_sync: 0, fd_pread: 0, fd_pwrite: 0, fd_readdir: 0,
+  fd_prestat_get: 8, fd_prestat_dir_name: 28,
+  fd_filestat_get: 0, fd_filestat_set_size: 0, fd_filestat_set_times: 0,
+  environ_get: 0, args_get: 0,
+  path_open: 44, path_create_directory: 44, path_filestat_get: 44,
+  path_filestat_set_times: 44, path_link: 44, path_readlink: 44,
+  path_remove_directory: 44, path_rename: 44, path_symlink: 44,
+  path_unlink_file: 44, sched_yield: 0, poll_oneoff: 0,
+  sock_accept: 58, sock_recv: 58, sock_send: 58, sock_shutdown: 58,
+};
+
+function buildWasiImports(memoryRef) {
+  const imports = {};
+  for (const [name, fn] of Object.entries(WASI_SHIM)) {
+    if (typeof fn === 'function') {
+      if (name === 'proc_exit') {
+        imports[name] = fn;
+      } else {
+        imports[name] = (...args) => fn(...args, memoryRef.current);
+      }
+    }
+  }
+  for (const [name, errno] of Object.entries(STUB_ERRNO)) {
+    imports[name] = () => errno;
+  }
+  imports.clock_res_get = (id, ptr) => {
+    new DataView(memoryRef.current.buffer).setBigUint64(ptr, 1000000n, true);
+    return 0;
+  };
+  imports.random_get = (buf, len) => {
+    const view = new Uint8Array(memoryRef.current.buffer, buf, len);
+    if (typeof crypto !== 'undefined' && crypto.getRandomValues) {
+      crypto.getRandomValues(view);
+    } else {
+      for (let i = 0; i < len; i++) view[i] = Math.floor(Math.random() * 256);
+    }
+    return 0;
+  };
+  return imports;
+}
+
+export async function createEngine(wasmSource) {
+  const memoryRef = { current: null };
+  const imports = { wasi_snapshot_preview1: buildWasiImports(memoryRef) };
+
+  let bytes;
+  if (wasmSource instanceof ArrayBuffer || ArrayBuffer.isView(wasmSource)) {
+    bytes = wasmSource;
+  } else if (wasmSource instanceof Response || (typeof wasmSource === 'object' && typeof wasmSource.then === 'function')) {
+    const response = await wasmSource;
+    bytes = await response.arrayBuffer();
+  } else if (typeof wasmSource === 'string') {
+    if (typeof fetch !== 'undefined') {
+      bytes = await (await fetch(wasmSource)).arrayBuffer();
+    } else {
+      const fs = await import('fs');
+      const path = await import('path');
+      bytes = fs.readFileSync(wasmSource);
+    }
+  } else {
+    throw new Error('wasmSource must be a URL string, Response, or ArrayBuffer');
+  }
+
+  const { instance } = await WebAssembly.instantiate(bytes, imports);
+  memoryRef.current = instance.exports.memory;
+
+  function writeString(str) {
+    const enc = new TextEncoder().encode(str);
+    const ptr = instance.exports.wasm_alloc(enc.length);
+    if (ptr === 0) throw new Error('WASM allocation failed');
+    new Uint8Array(memoryRef.current.buffer, ptr, enc.length).set(enc);
+    return { ptr, len: enc.length };
+  }
+
+  return {
+    evaluate(source, inputs = {}, options = {}) {
+      const includeGraph = options.graph !== false;
+      const src = writeString(source);
+      const json = writeString(JSON.stringify(inputs));
+      const resultLen = instance.exports.wasm_eval(
+        src.ptr, src.len,
+        json.ptr, json.len,
+        includeGraph ? 1 : 0
+      );
+      const resultPtr = instance.exports.wasm_result_ptr();
+      const resultBytes = new Uint8Array(memoryRef.current.buffer, resultPtr, resultLen);
+      return JSON.parse(new TextDecoder().decode(resultBytes));
+    },
+  };
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@autochitect/engine",
+  "version": "1.0.0",
+  "description": "A 245KB WebAssembly financial modeling engine. Define cost models in a purpose-built DSL, get instant evaluation with full dependency tracing. No server required.",
+  "license": "MIT",
+  "type": "module",
+  "main": "index.mjs",
+  "types": "index.d.ts",
+  "files": [
+    "index.mjs",
+    "index.d.ts",
+    "engine.wasm",
+    "LICENSE",
+    "README.md"
+  ],
+  "keywords": [
+    "financial-modeling",
+    "cost-estimation",
+    "wasm",
+    "webassembly",
+    "dsl",
+    "spreadsheet",
+    "calculation-engine",
+    "scenario-analysis",
+    "dependency-graph"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:autochitect/engine.git"
+  },
+  "homepage": "https://autochitect.com/engine"
+}