@almadar/evaluator 1.0.16 → 2.1.0

package/LICENSE

@@ -1,72 +1,21 @@
-Business Source License 1.1
-
-Parameters
-
-Licensor:             Almadar FZE
-Licensed Work:        KFlow Builder / Almadar
-                      The Licensed Work is (c) 2025-2026 Almadar FZE.
-Additional Use Grant: You may make production use of the Licensed Work for
-                      non-commercial purposes and for internal evaluation.
-                      Production use for commercial purposes requires a
-                      commercial license from the Licensor.
-Change Date:          2030-02-01
-Change License:       Apache License, Version 2.0
-
-Terms
-
-The Licensor hereby grants you the right to copy, modify, create derivative
-works, redistribute, and make non-production use of the Licensed Work. The
-Licensor may make an Additional Use Grant, above, permitting limited
-production use.
-
-Effective on the Change Date, or the fourth anniversary of the first publicly
-available distribution of a specific version of the Licensed Work under this
-License, whichever comes first, the Licensor hereby grants you rights under
-the terms of the Change License, and the rights granted in the paragraph
-above terminate.
-
-If your use of the Licensed Work does not comply with the requirements
-currently in effect as described in this License, you must purchase a
-commercial license from the Licensor, its affiliated entities, or authorized
-resellers, or you must refrain from using the Licensed Work.
-
-All copies of the original and modified Licensed Work, and derivative works
-of the Licensed Work, are subject to this License. This License applies
-separately for each version of the Licensed Work and the Change Date may vary
-for each version of the Licensed Work released by Licensor.
-
-You must conspicuously display this License on each original or modified copy
-of the Licensed Work. If you receive the Licensed Work in original or
-modified form from a third party, the terms and conditions set forth in this
-License apply to your use of that work.
-
-Any use of the Licensed Work in violation of this License will automatically
-terminate your rights under this License for the current and all other
-versions of the Licensed Work.
-
-This License does not grant you any right in any trademark or logo of
-Licensor or its affiliates (provided that you may use a trademark or logo of
-Licensor as expressly required by this License).
-
-TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
-AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
-EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
-TITLE.
-
----
-
-License text copyright (c) 2017 MariaDB Corporation Ab, All Rights Reserved.
-"Business Source License" is a trademark of MariaDB Corporation Ab.
-
-ADDITIONAL TERMS:
-
-Documentation (builder/packages/website/docs/) is licensed under CC BY 4.0.
-
-TRADEMARKS:
-
-"Orbital", "KFlow", "Almadar", and the Almadar logo are trademarks of
-Almadar FZE. You may not use these trademarks without prior written
-permission from Almadar FZE.
-
-For licensing inquiries: licensing@almadar.io
+MIT License
+
+Copyright (c) 2026 Almadar Team
+
+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,25 @@
+# @almadar/evaluator
+
+> S-expression evaluator for Almadar
+
+Part of the [Almadar](https://github.com/almadar-io/almadar) platform.
+
+## Installation
+
+```bash
+npm install @almadar/evaluator
+```
+
+## Usage
+
+```typescript
+import { /* ... */ } from '@almadar/evaluator';
+```
+
+## API
+
+<!-- Document public exports here -->
+
+## License
+
+MIT

package/dist/{index-DsM_--K3.d.ts → index-DBM7Xkm3.d.ts}

@@ -44,14 +44,32 @@ interface EvaluationContext {
     singletons: Map<string, Record<string, unknown>>;
     /** Local variables from 'let' bindings */
     locals?: Map<string, unknown>;
+    /**
+     * When true, log warnings when bindings resolve to undefined. (RCG-01)
+     * Helps detect typos and missing entity fields early.
+     */
+    strictBindings?: boolean;
+    /**
+     * Set by prob/condition when a predicate fails during inference.
+     * Checked by prob/posterior and prob/infer to reject samples.
+     */
+    _probRejected?: boolean;
+    /**
+     * Seeded PRNG state for deterministic probabilistic sampling.
+     * Stored as a mutable object so child contexts share the same state.
+     * Set by prob/seed.
+     */
+    _probSeed?: {
+        state: number;
+    };
     /** Mutate entity fields */
     mutateEntity?: (changes: Record<string, unknown>) => void;
     /** Emit an event */
     emit?: (event: string, payload?: unknown) => void;
     /** Navigate to a route */
     navigate?: (route: string, params?: Record<string, unknown>) => void;
-    /** Persist data (create/update/delete) */
-    persist?: (action: 'create' | 'update' | 'delete', data?: Record<string, unknown>) => Promise<void>;
+    /** Persist data (create/update/delete/batch) */
+    persist?: (action: 'create' | 'update' | 'delete' | 'batch', data?: Record<string, unknown>) => Promise<void>;
     /** Show a notification */
     notify?: (message: string, type?: 'success' | 'error' | 'warning' | 'info') => void;
     /** Spawn a new entity instance */
@@ -307,8 +325,13 @@ declare function evalSet(args: SExpr[], evaluate: Evaluator, ctx: EvaluationCont
  */
 declare function evalEmit(args: SExpr[], evaluate: Evaluator, ctx: EvaluationContext): void;
 /**
- * Evaluate persist: ["persist", action] or ["persist", action, data]
- * Actions: "create", "update", "delete"
+ * Evaluate persist:
+ * - ["persist", action] or ["persist", action, data]
+ *   Actions: "create", "update", "delete"
+ * - ["persist", "batch", [...operations]]
+ *   Batch action for atomic multi-document writes.
+ *   Each operation is an S-expression: ["create", "collection", {...data}],
+ *   ["update", "collection", "id", {...data}], or ["delete", "collection", "id"].
  */
 declare function evalPersist(args: SExpr[], evaluate: Evaluator, ctx: EvaluationContext): void;
 /**

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { SExpr } from '@almadar/core';
 export { CORE_BINDINGS, CoreBinding, Expression, ExpressionSchema, ParsedBinding, SExpr, SExprAtom, SExprSchema, collectBindings, getArgs, getOperator, isBinding, isSExpr, isSExprAtom, isSExprCall, isValidBinding, parseBinding, sexpr, walkSExpr } from '@almadar/core';
-import { E as EvaluationContext } from './index-DsM_--K3.js';
-export { c as createChildContext, a as createEffectContext, b as createMinimalContext, e as evalAbs, d as evalAdd, f as evalAnd, g as evalCallService, h as evalCeil, i as evalClamp, j as evalConcat, k as evalCount, l as evalDecrement, m as evalDespawn, n as evalDivide, o as evalDo, p as evalEmit, q as evalEmpty, r as evalEqual, s as evalFilter, t as evalFind, u as evalFirst, v as evalFloor, w as evalFn, x as evalGreaterThan, y as evalGreaterThanOrEqual, z as evalIf, A as evalIncludes, B as evalIncrement, C as evalLast, D as evalLessThan, F as evalLessThanOrEqual, G as evalLet, H as evalMap, I as evalMatches, J as evalMax, K as evalMin, L as evalModulo, M as evalMultiply, N as evalNavigate, O as evalNot, P as evalNotEqual, Q as evalNotify, R as evalNth, S as evalOr, T as evalPersist, U as evalRenderUI, V as evalRound, W as evalSet, X as evalSetDynamic, Y as evalSpawn, Z as evalSubtract, _ as evalSum, $ as evalWhen, a0 as resolveBinding } from './index-DsM_--K3.js';
+import { E as EvaluationContext } from './index-DBM7Xkm3.js';
+export { c as createChildContext, a as createEffectContext, b as createMinimalContext, e as evalAbs, d as evalAdd, f as evalAnd, g as evalCallService, h as evalCeil, i as evalClamp, j as evalConcat, k as evalCount, l as evalDecrement, m as evalDespawn, n as evalDivide, o as evalDo, p as evalEmit, q as evalEmpty, r as evalEqual, s as evalFilter, t as evalFind, u as evalFirst, v as evalFloor, w as evalFn, x as evalGreaterThan, y as evalGreaterThanOrEqual, z as evalIf, A as evalIncludes, B as evalIncrement, C as evalLast, D as evalLessThan, F as evalLessThanOrEqual, G as evalLet, H as evalMap, I as evalMatches, J as evalMax, K as evalMin, L as evalModulo, M as evalMultiply, N as evalNavigate, O as evalNot, P as evalNotEqual, Q as evalNotify, R as evalNth, S as evalOr, T as evalPersist, U as evalRenderUI, V as evalRound, W as evalSet, X as evalSetDynamic, Y as evalSpawn, Z as evalSubtract, _ as evalSum, $ as evalWhen, a0 as resolveBinding } from './index-DBM7Xkm3.js';
 
 /**
  * S-Expression Evaluator

package/dist/index.js

@@ -60,16 +60,34 @@ function resolveBinding(binding, ctx) {
         break;
     }
   }
-  for (const segment of path) {
+  for (let i = 0; i < path.length; i++) {
+    const segment = path[i];
     if (value === null || value === void 0) {
+      if (ctx.strictBindings) {
+        const resolvedSoFar = [root, ...path.slice(0, i)].join(".");
+        console.warn(
+          `[Binding] @${root}.${path.join(".")} resolved to undefined (failed at "${segment}" \u2014 @${resolvedSoFar} is ${value === null ? "null" : "undefined"})`
+        );
+      }
       return void 0;
     }
     if (typeof value === "object") {
       value = value[segment];
     } else {
+      if (ctx.strictBindings) {
+        const resolvedSoFar = [root, ...path.slice(0, i)].join(".");
+        console.warn(
+          `[Binding] @${root}.${path.join(".")} resolved to undefined (cannot navigate "${segment}" on non-object at @${resolvedSoFar})`
+        );
+      }
       return void 0;
     }
   }
+  if (value === void 0 && path.length > 0 && ctx.strictBindings) {
+    console.warn(
+      `[Binding] @${root}.${path.join(".")} resolved to undefined`
+    );
+  }
   return value;
 }
 
@@ -431,11 +449,26 @@ function evalEmit(args, evaluate2, ctx) {
 }
 function evalPersist(args, evaluate2, ctx) {
   const action = args[0];
-  const data = args.length > 1 ? evaluate2(args[1], ctx) : ctx.payload;
   if (!ctx.persist) {
     console.warn("No persist handler in context for persist effect");
     return;
   }
+  if (action === "batch") {
+    const rawOps = args[1];
+    if (!Array.isArray(rawOps)) {
+      console.warn("persist batch requires an array of operations as second argument");
+      return;
+    }
+    const operations = rawOps.map((op) => {
+      if (!Array.isArray(op)) return op;
+      return op.map((item) => evaluate2(item, ctx));
+    });
+    ctx.persist("batch", { operations }).catch((err) => {
+      console.error("Persist batch failed:", err);
+    });
+    return;
+  }
+  const data = args.length > 1 ? evaluate2(args[1], ctx) : ctx.payload;
   ctx.persist(action, data).catch((err) => {
     console.error(`Persist ${action} failed:`, err);
   });
@@ -1959,9 +1992,28 @@ function evalFormatCreditCard(args, evaluate2, ctx) {
 // std/async.ts
 var debounceTimers = /* @__PURE__ */ new Map();
 var throttleTimestamps = /* @__PURE__ */ new Map();
+var intervalTimers = /* @__PURE__ */ new Map();
+var intervalIdCounter = 0;
 async function evalAsyncDelay(args, evaluate2, ctx) {
   const ms = evaluate2(args[0], ctx);
-  return new Promise((resolve) => setTimeout(resolve, ms));
+  await new Promise((resolve) => setTimeout(resolve, ms));
+  if (args.length >= 2 && args[1] !== void 0) {
+    return evaluate2(args[1], ctx);
+  }
+  return void 0;
+}
+function evalAsyncInterval(args, evaluate2, ctx) {
+  const ms = evaluate2(args[0], ctx);
+  const effect = args[1];
+  const id = `interval_${++intervalIdCounter}`;
+  const timer = setInterval(() => {
+    try {
+      evaluate2(effect, ctx);
+    } catch {
+    }
+  }, ms);
+  intervalTimers.set(id, timer);
+  return id;
 }
 async function evalAsyncTimeout(args, evaluate2, ctx) {
   const effect = args[0];
@@ -2049,6 +2101,224 @@ async function evalAsyncSequence(args, evaluate2, ctx) {
   return results;
 }
 
+// std/prob.ts
+function mulberry32(seed) {
+  let t = seed.state += 1831565813;
+  t = Math.imul(t ^ t >>> 15, t | 1);
+  t ^= t + Math.imul(t ^ t >>> 7, t | 61);
+  return ((t ^ t >>> 14) >>> 0) / 4294967296;
+}
+function getRandom(ctx) {
+  if (ctx._probSeed) {
+    return mulberry32(ctx._probSeed);
+  }
+  return Math.random();
+}
+function gammaVariate(shape, ctx) {
+  if (shape < 1) {
+    const u = getRandom(ctx);
+    return gammaVariate(shape + 1, ctx) * Math.pow(u, 1 / shape);
+  }
+  const d = shape - 1 / 3;
+  const c = 1 / Math.sqrt(9 * d);
+  for (; ; ) {
+    let x;
+    let v;
+    do {
+      x = gaussianStandard(ctx);
+      v = 1 + c * x;
+    } while (v <= 0);
+    v = v * v * v;
+    const u = getRandom(ctx);
+    if (u < 1 - 0.0331 * (x * x) * (x * x)) {
+      return d * v;
+    }
+    if (Math.log(u) < 0.5 * x * x + d * (1 - v + Math.log(v))) {
+      return d * v;
+    }
+  }
+}
+function gaussianStandard(ctx) {
+  const u1 = getRandom(ctx);
+  const u2 = getRandom(ctx);
+  return Math.sqrt(-2 * Math.log(u1)) * Math.cos(2 * Math.PI * u2);
+}
+function evalProbSeed(args, evaluate2, ctx) {
+  const n = evaluate2(args[0], ctx);
+  ctx._probSeed = { state: n | 0 };
+}
+function evalProbFlip(args, evaluate2, ctx) {
+  const p = evaluate2(args[0], ctx);
+  return getRandom(ctx) < p;
+}
+function evalProbGaussian(args, evaluate2, ctx) {
+  const mu = evaluate2(args[0], ctx);
+  const sigma = evaluate2(args[1], ctx);
+  return mu + sigma * gaussianStandard(ctx);
+}
+function evalProbUniform(args, evaluate2, ctx) {
+  const lo = evaluate2(args[0], ctx);
+  const hi = evaluate2(args[1], ctx);
+  return lo + getRandom(ctx) * (hi - lo);
+}
+function evalProbBeta(args, evaluate2, ctx) {
+  const alpha = evaluate2(args[0], ctx);
+  const beta = evaluate2(args[1], ctx);
+  const x = gammaVariate(alpha, ctx);
+  const y = gammaVariate(beta, ctx);
+  return x / (x + y);
+}
+function evalProbCategorical(args, evaluate2, ctx) {
+  const items = evaluate2(args[0], ctx);
+  const weights = evaluate2(args[1], ctx);
+  const totalWeight = weights.reduce((sum, w) => sum + w, 0);
+  let r = getRandom(ctx) * totalWeight;
+  for (let i = 0; i < items.length; i++) {
+    r -= weights[i];
+    if (r <= 0) return items[i];
+  }
+  return items[items.length - 1];
+}
+function evalProbPoisson(args, evaluate2, ctx) {
+  const lambda = evaluate2(args[0], ctx);
+  const limit = Math.exp(-lambda);
+  let k = 0;
+  let p = 1;
+  do {
+    k++;
+    p *= getRandom(ctx);
+  } while (p > limit);
+  return k - 1;
+}
+function evalProbCondition(args, evaluate2, ctx) {
+  const predicate = evaluate2(args[0], ctx);
+  if (!predicate) {
+    ctx._probRejected = true;
+  }
+}
+function evalProbSample(args, evaluate2, ctx) {
+  const n = evaluate2(args[0], ctx);
+  const exprAst = args[1];
+  const results = [];
+  for (let i = 0; i < n; i++) {
+    results.push(evaluate2(exprAst, ctx));
+  }
+  return results;
+}
+function evalProbPosterior(args, evaluate2, ctx) {
+  const modelAst = args[0];
+  const evidenceAst = args[1];
+  const queryAst = args[2];
+  const n = evaluate2(args[3], ctx);
+  const results = [];
+  for (let i = 0; i < n; i++) {
+    const sampleEntity = { ...ctx.entity };
+    const sampleCtx = {
+      ...ctx,
+      entity: sampleEntity,
+      _probRejected: false,
+      mutateEntity: (changes) => {
+        Object.assign(sampleEntity, changes);
+      }
+    };
+    evaluate2(modelAst, sampleCtx);
+    if (sampleCtx._probRejected) continue;
+    const evidenceResult = evaluate2(evidenceAst, sampleCtx);
+    if (!evidenceResult) continue;
+    results.push(evaluate2(queryAst, sampleCtx));
+  }
+  return results;
+}
+function evalProbInfer(args, evaluate2, ctx) {
+  const modelAst = args[0];
+  const evidenceAst = args[1];
+  const queryAst = args[2];
+  const n = evaluate2(args[3], ctx);
+  const accepted = [];
+  for (let i = 0; i < n; i++) {
+    const sampleEntity = { ...ctx.entity };
+    const sampleCtx = {
+      ...ctx,
+      entity: sampleEntity,
+      _probRejected: false,
+      mutateEntity: (changes) => {
+        Object.assign(sampleEntity, changes);
+      }
+    };
+    evaluate2(modelAst, sampleCtx);
+    if (sampleCtx._probRejected) continue;
+    const evidenceResult = evaluate2(evidenceAst, sampleCtx);
+    if (!evidenceResult) continue;
+    const queryVal = evaluate2(queryAst, sampleCtx);
+    accepted.push(queryVal);
+  }
+  const count = accepted.length;
+  if (count === 0) {
+    return { mean: 0, variance: 0, samples: [], acceptRate: 0 };
+  }
+  const mean = accepted.reduce((s, v) => s + v, 0) / count;
+  const variance = accepted.reduce((s, v) => s + (v - mean) ** 2, 0) / count;
+  return {
+    mean,
+    variance,
+    samples: accepted,
+    acceptRate: count / n
+  };
+}
+function evalProbExpectedValue(args, evaluate2, ctx) {
+  const samples = evaluate2(args[0], ctx);
+  if (samples.length === 0) return 0;
+  return samples.reduce((s, v) => s + v, 0) / samples.length;
+}
+function evalProbVariance(args, evaluate2, ctx) {
+  const samples = evaluate2(args[0], ctx);
+  if (samples.length === 0) return 0;
+  const mean = samples.reduce((s, v) => s + v, 0) / samples.length;
+  return samples.reduce((s, v) => s + (v - mean) ** 2, 0) / samples.length;
+}
+function evalProbHistogram(args, evaluate2, ctx) {
+  const samples = evaluate2(args[0], ctx);
+  const bins = evaluate2(args[1], ctx);
+  if (samples.length === 0) {
+    return { binEdges: [], counts: [] };
+  }
+  const min = Math.min(...samples);
+  const max = Math.max(...samples);
+  const binWidth = (max - min) / bins || 1;
+  const binEdges = [];
+  const counts = new Array(bins).fill(0);
+  for (let i = 0; i <= bins; i++) {
+    binEdges.push(min + i * binWidth);
+  }
+  for (const s of samples) {
+    let idx = Math.floor((s - min) / binWidth);
+    if (idx >= bins) idx = bins - 1;
+    counts[idx]++;
+  }
+  return { binEdges, counts };
+}
+function evalProbPercentile(args, evaluate2, ctx) {
+  const samples = evaluate2(args[0], ctx);
+  const p = evaluate2(args[1], ctx);
+  if (samples.length === 0) return 0;
+  const sorted = [...samples].sort((a, b) => a - b);
+  const idx = p / 100 * (sorted.length - 1);
+  const lo = Math.floor(idx);
+  const hi = Math.ceil(idx);
+  if (lo === hi) return sorted[lo];
+  const frac = idx - lo;
+  return sorted[lo] * (1 - frac) + sorted[hi] * frac;
+}
+function evalProbCredibleInterval(args, evaluate2, ctx) {
+  const samples = evaluate2(args[0], ctx);
+  const alpha = evaluate2(args[1], ctx);
+  if (samples.length === 0) return [0, 0];
+  const sorted = [...samples].sort((a, b) => a - b);
+  const loIdx = Math.floor(alpha / 2 * (sorted.length - 1));
+  const hiIdx = Math.ceil((1 - alpha / 2) * (sorted.length - 1));
+  return [sorted[loIdx], sorted[hiIdx]];
+}
+
 // SExpressionEvaluator.ts
 var jitCache = /* @__PURE__ */ new Map();
 var MAX_JIT_CACHE_SIZE = 1e3;
@@ -2596,6 +2866,8 @@ var SExpressionEvaluator = class {
       // ===============================
       case "async/delay":
         return evalAsyncDelay(args, evaluate2, ctx);
+      case "async/interval":
+        return evalAsyncInterval(args, evaluate2, ctx);
       case "async/timeout":
         return evalAsyncTimeout(args, evaluate2, ctx);
       case "async/debounce":
@@ -2612,6 +2884,43 @@ var SExpressionEvaluator = class {
         return evalAsyncAll(args, evaluate2, ctx);
       case "async/sequence":
         return evalAsyncSequence(args, evaluate2, ctx);
+      // ===============================
+      // Standard Library: prob/*
+      // ===============================
+      case "prob/seed":
+        evalProbSeed(args, evaluate2, ctx);
+        return void 0;
+      case "prob/flip":
+        return evalProbFlip(args, evaluate2, ctx);
+      case "prob/gaussian":
+        return evalProbGaussian(args, evaluate2, ctx);
+      case "prob/uniform":
+        return evalProbUniform(args, evaluate2, ctx);
+      case "prob/beta":
+        return evalProbBeta(args, evaluate2, ctx);
+      case "prob/categorical":
+        return evalProbCategorical(args, evaluate2, ctx);
+      case "prob/poisson":
+        return evalProbPoisson(args, evaluate2, ctx);
+      case "prob/condition":
+        evalProbCondition(args, evaluate2, ctx);
+        return void 0;
+      case "prob/sample":
+        return evalProbSample(args, evaluate2, ctx);
+      case "prob/posterior":
+        return evalProbPosterior(args, evaluate2, ctx);
+      case "prob/infer":
+        return evalProbInfer(args, evaluate2, ctx);
+      case "prob/expected-value":
+        return evalProbExpectedValue(args, evaluate2, ctx);
+      case "prob/variance":
+        return evalProbVariance(args, evaluate2, ctx);
+      case "prob/histogram":
+        return evalProbHistogram(args, evaluate2, ctx);
+      case "prob/percentile":
+        return evalProbPercentile(args, evaluate2, ctx);
+      case "prob/credible-interval":
+        return evalProbCredibleInterval(args, evaluate2, ctx);
       default:
         console.warn(`Unknown operator: ${op}`);
         return void 0;