@scenario-labs/sdk 2.4.0-alpha.1 → 2.5.0

package/src/lib/cel/functions.ts

@@ -0,0 +1,109 @@
+import type { Environment } from '@marcbachmann/cel-js';
+
+import {
+  mulberry32,
+  normalizeSeed,
+  sampleWithoutReplacement,
+  sampleWithReplacement,
+  type RandomSource,
+} from './prng';
+
+/**
+ * Random integer with exactly `digits` digits, e.g. random(5) -> 48574.
+ * Ported verbatim from the backend's cel_evaluator for back-compat with
+ * deployed workflows. Float precision degrades above 15 digits.
+ */
+function randomDigits(digits: bigint | number): bigint {
+  const d = Number(digits);
+  if (d <= 0) return 0n;
+  const min = 10 ** (d - 1);
+  const max = 10 ** d;
+  return BigInt(Math.floor(Math.random() * (max - min)) + min);
+}
+
+function randomSampleImpl(
+  list: unknown,
+  count: bigint | number,
+  seed: bigint | number | undefined,
+  withReplacement: boolean,
+): unknown[] {
+  if (!Array.isArray(list)) return [];
+  const rand: RandomSource = seed === undefined ? Math.random : mulberry32(normalizeSeed(seed));
+  const k = Number(count);
+  return withReplacement ? sampleWithReplacement(list, k, rand) : sampleWithoutReplacement(list, k, rand);
+}
+
+const RANDOM_SAMPLE_DESCRIPTION =
+  'Sample items from a list. An int seed makes the result reproducible (same seed, same sample); ' +
+  'withReplacement allows duplicates. Without replacement, count is clamped to the list size.';
+
+const PARAM_LIST = { name: 'list', description: 'List to sample from' };
+const PARAM_COUNT = { name: 'count', description: 'Number of items to sample' };
+const PARAM_SEED = { name: 'seed', description: 'Seed for reproducible sampling' };
+const PARAM_WITH_REPLACEMENT = { name: 'withReplacement', description: 'Allow duplicate picks' };
+
+/** Register the shared base functions. Order and semantics are stable API. */
+export function registerBaseFunctions(env: Environment): Environment {
+  // Registered as dyn so cel-js doesn't reject null before reaching the handler.
+  env.registerFunction('trim(dyn): string', (s: string) => (s == null ? '' : String(s).trim()), {
+    description: 'Trim leading and trailing whitespace. Null-safe: null becomes "".',
+    params: [{ name: 'value', description: 'Value to trim; null yields ""' }],
+  });
+
+  // Registered as dyn first arg so cel-js doesn't reject non-list inputs before the handler.
+  env.registerFunction(
+    'slice(dyn, int, int): list',
+    (arr: unknown, start: bigint | number, end: bigint | number) => {
+      if (!Array.isArray(arr)) return [];
+      return arr.slice(Number(start), Number(end));
+    },
+    {
+      description: 'Return list[start:end] with JS Array.prototype.slice semantics.',
+      params: [
+        { name: 'list', description: 'List to slice' },
+        { name: 'start', description: 'Start index (inclusive)' },
+        { name: 'end', description: 'End index (exclusive)' },
+      ],
+    },
+  );
+
+  env.registerFunction('random(int): int', (digits: bigint | number) => randomDigits(digits), {
+    description: 'Random integer with exactly N digits, e.g. random(5) -> 48574. Unseeded.',
+    params: [{ name: 'digits', description: 'Number of digits in the result' }],
+  });
+
+  env.registerFunction(
+    'randomSample(list, int): list',
+    (list: unknown, count: bigint | number) => randomSampleImpl(list, count, undefined, false),
+    { description: RANDOM_SAMPLE_DESCRIPTION, params: [PARAM_LIST, PARAM_COUNT] },
+  );
+
+  env.registerFunction(
+    'randomSample(list, int, int): list',
+    (list: unknown, count: bigint | number, seed: bigint | number) =>
+      randomSampleImpl(list, count, seed, false),
+    { description: RANDOM_SAMPLE_DESCRIPTION, params: [PARAM_LIST, PARAM_COUNT, PARAM_SEED] },
+  );
+
+  env.registerFunction(
+    'randomSample(list, int, bool): list',
+    (list: unknown, count: bigint | number, withReplacement: boolean) =>
+      randomSampleImpl(list, count, undefined, withReplacement),
+    {
+      description: RANDOM_SAMPLE_DESCRIPTION,
+      params: [PARAM_LIST, PARAM_COUNT, PARAM_WITH_REPLACEMENT],
+    },
+  );
+
+  env.registerFunction(
+    'randomSample(list, int, int, bool): list',
+    (list: unknown, count: bigint | number, seed: bigint | number, withReplacement: boolean) =>
+      randomSampleImpl(list, count, seed, withReplacement),
+    {
+      description: RANDOM_SAMPLE_DESCRIPTION,
+      params: [PARAM_LIST, PARAM_COUNT, PARAM_SEED, PARAM_WITH_REPLACEMENT],
+    },
+  );
+
+  return env;
+}

package/src/lib/cel/index.ts

@@ -0,0 +1,8 @@
+export {
+  createCelEnvironment,
+  evaluateCel,
+  type CelFunctionParam,
+  type CelFunctionRegistration,
+  type EvaluateCelOptions,
+} from './environment';
+export { Environment } from '@marcbachmann/cel-js';

package/src/lib/cel/prng.ts

@@ -0,0 +1,62 @@
+/**
+ * Deterministic PRNG + sampling primitives backing the CEL `randomSample`
+ * function.
+ *
+ * STABILITY CONTRACT — DO NOT CHANGE THESE ALGORITHMS.
+ * The same seed must produce the same sample on every runtime and every SDK
+ * version: the backend (server) and frontend (client) rely on agreeing outputs,
+ * and customers rely on seeds for reproducible workflow runs. Golden-value
+ * tests in tests/lib/cel/prng.test.ts pin the exact outputs.
+ */
+
+/** A source of random floats in [0, 1). */
+export type RandomSource = () => number;
+
+/**
+ * mulberry32: fast 32-bit PRNG with exact, platform-independent output.
+ * `seed` is coerced to uint32 (via `>>> 0`); use {@link normalizeSeed} to
+ * convert arbitrary CEL ints before calling this.
+ */
+export function mulberry32(seed: number): RandomSource {
+  let a = seed >>> 0;
+  return () => {
+    a = (a + 0x6d2b79f5) | 0;
+    let t = Math.imul(a ^ (a >>> 15), 1 | a);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+/** Normalize a CEL int (bigint or number) to a uint32 PRNG seed. */
+export function normalizeSeed(seed: bigint | number): number {
+  return Number(BigInt.asUintN(32, BigInt(seed)));
+}
+
+/**
+ * Sample `count` distinct elements via partial Fisher–Yates.
+ * `count` is clamped to [0, list.length]; the input list is not mutated.
+ */
+export function sampleWithoutReplacement<T>(list: readonly T[], count: number, rand: RandomSource): T[] {
+  const n = list.length;
+  const k = Math.min(Math.max(count, 0), n);
+  if (k === 0) return [];
+  const pool = list.slice();
+  for (let i = 0; i < k; i++) {
+    const j = i + Math.floor(rand() * (n - i));
+    const tmp = pool[i]!;
+    pool[i] = pool[j]!;
+    pool[j] = tmp;
+  }
+  return pool.slice(0, k);
+}
+
+/** `count` independent draws; duplicates allowed. Returns [] if the list is empty or count <= 0. */
+export function sampleWithReplacement<T>(list: readonly T[], count: number, rand: RandomSource): T[] {
+  const n = list.length;
+  if (n === 0 || count <= 0) return [];
+  const out: T[] = [];
+  for (let i = 0; i < count; i++) {
+    out.push(list[Math.floor(rand() * n)]!);
+  }
+  return out;
+}

package/src/lib/workflow_converter.ts

@@ -52,7 +52,13 @@ export type WorkflowEditorNode =
   | {
       id: string;
       type: 'sliceAssets';
-      data: NodeCommonData & { from?: number | string; count?: number | string };
+      data: NodeCommonData & {
+        from?: number | string;
+        count?: number | string;
+        isRandomize?: boolean;
+        randomSeed?: string;
+        value?: string;
+      };
     }
   | { id: string; type: 'forEach'; data: NodeCommonData }
   | { id: string; type: 'forEachEnd'; data: NodeCommonData & { parentNodeId?: string } }
@@ -561,6 +567,50 @@ function getOutputHandleVarName(targetNodeId: string, handleName: string): strin
   return ['output', 'allOutputs'].includes(handleName) ? targetNodeId : `${targetNodeId}_${handleName}`;
 }
 
+function getIsSliceAssetsItemsSourceHandle(nodeId: string, sourceHandle: string | null | undefined): boolean {
+  return sourceHandle === `${nodeId}-source-items` || sourceHandle === `${nodeId}-source-assets`;
+}
+
+/**
+ * Builds the concat variables and flow inputs for a list-concatenating node
+ * (groupItems, sliceAssets in randomize mode) from its incoming edges.
+ * `getVarName` maps a target node id + output handle name to the variable name,
+ * which differs between callers.
+ */
+function collectConcatVarsAndInputs(
+  edges: WorkflowEditorEdge[],
+  ctx: SourceRefContext,
+  getVarName: (targetNodeId: string, handleName: string) => string,
+): { variables: ConcatVariable[]; flowInputs: WorkflowEditorFlowInput[] } {
+  const { nodes, inputNodeIds } = ctx;
+  const variables: ConcatVariable[] = [];
+  const flowInputs: WorkflowEditorFlowInput[] = [];
+
+  for (const edge of edges) {
+    const targetNode = nodes.find((n) => n.id === edge.target);
+    if (!targetNode) continue;
+    const ref = getSourceRef(edge, ctx);
+    if (!ref) continue;
+    const outHandle = targetNode.data.outputHandles?.find((h) => h.id === edge.targetHandle);
+    const outHandleName = outHandle?.name ?? 'output';
+    const varName = getVarName(targetNode.id, outHandleName);
+    const isArr =
+      (targetNode.type === 'asset' && !!(targetNode.data as { isMultiple?: boolean }).isMultiple) ||
+      targetNode.type === 'groupItems' ||
+      targetNode.type === 'sliceAssets' ||
+      outHandleName === 'allOutputs';
+    const isRequired =
+      inputNodeIds.includes(targetNode.id) ?
+        (targetNode.type === 'asset' && !!(targetNode.data as { isRequired?: boolean }).isRequired) ||
+        ['firstFrame', 'lastFrame'].includes(outHandleName)
+      : true;
+    variables.push({ name: varName, isArray: isArr, isRequired });
+    flowInputs.push({ name: varName, type: isArr ? 'file_array' : 'file', ref });
+  }
+
+  return { variables, flowInputs };
+}
+
 function setOrPushFlowInput(
   flowInputs: WorkflowEditorFlowInput[],
   existingIndex: number,
@@ -1522,32 +1572,12 @@ export function convertWorkflowEditorToFlow(
       // GroupItems -> array concatenation
       // ------------------------------------
     } else if (node.type === 'groupItems') {
-      const flowInputs: WorkflowEditorFlowInput[] = [];
-      const variables: ConcatVariable[] = [];
       const conditionalHandleId = getConditionalInputHandleId(node.id);
-
-      for (const edge of incomingEdges) {
-        if (edge.sourceHandle === conditionalHandleId) continue;
-        const targetNode = nodes.find((n) => n.id === edge.target);
-        if (!targetNode) continue;
-        const ref = getSourceRef(edge, ctx);
-        if (!ref) continue;
-        const outHandle = targetNode.data.outputHandles?.find((h) => h.id === edge.targetHandle);
-        const outHandleName = outHandle?.name ?? 'output';
-        const varName = `${targetNode.id}_${outHandleName}`;
-        const isArr =
-          (targetNode.type === 'asset' && !!(targetNode.data as { isMultiple?: boolean }).isMultiple) ||
-          targetNode.type === 'groupItems' ||
-          targetNode.type === 'sliceAssets' ||
-          outHandleName === 'allOutputs';
-        const isRequired =
-          inputNodeIds.includes(targetNode.id) ?
-            (targetNode.type === 'asset' && !!(targetNode.data as { isRequired?: boolean }).isRequired) ||
-            ['firstFrame', 'lastFrame'].includes(outHandleName)
-          : true;
-        variables.push({ name: varName, isArray: isArr, isRequired });
-        flowInputs.push({ name: varName, type: isArr ? 'file_array' : 'file', ref });
-      }
+      const { variables, flowInputs } = collectConcatVarsAndInputs(
+        incomingEdges.filter((e) => e.sourceHandle !== conditionalHandleId),
+        ctx,
+        (targetNodeId, handleName) => `${targetNodeId}_${handleName}`,
+      );
 
       const orderedValues = convertValueToList((node.data as { value?: string }).value ?? '');
       variables.sort((a, b) => orderedValues.indexOf(a.name) - orderedValues.indexOf(b.name));
@@ -1561,20 +1591,46 @@ export function convertWorkflowEditorToFlow(
       });
 
       // ------------------------------------
-      // SliceAssets -> slice(list, from, from+count)
+      // SliceAssets -> slice(list, from, from+count) or randomSample(list, count, seed)
       // ------------------------------------
     } else if (node.type === 'sliceAssets') {
-      const assetsEdge = incomingEdges.find((e) => e.sourceHandle === `${node.id}-source-assets`);
-      if (!assetsEdge) {
-        flow.push({ id: flowId, type: 'transform', logic: { transform: '[]' } });
+      const sliceData = node.data as {
+        from?: number | string;
+        count?: number | string;
+        isRandomize?: boolean;
+        randomSeed?: string;
+      };
+      const conditionalHandleId = getConditionalInputHandleId(node.id);
+      const itemsEdges = incomingEdges.filter(
+        (e) =>
+          e.sourceHandle !== conditionalHandleId &&
+          getIsSliceAssetsItemsSourceHandle(node.id, e.sourceHandle),
+      );
+
+      if (sliceData.isRandomize) {
+        const { variables, flowInputs } = collectConcatVarsAndInputs(itemsEdges, ctx, getOutputHandleVarName);
+        flowInputs.push(...collectConditionalConnectionInputs(incomingEdges, node.id, ctx));
+
+        const count = Math.max(1, parseInt(String(sliceData.count ?? ''), 10) || 1);
+        const seed = parseInt(String(sliceData.randomSeed ?? ''), 10) || 0;
+        const transform = `randomSample(${buildConcatArrayTransform(variables)}, ${count}, ${seed})`;
+
+        flow.push({
+          id: flowId,
+          type: 'transform',
+          logic: { transform },
+          inputs: flowInputs.length > 0 ? flowInputs : undefined,
+        });
       } else {
-        const targetNode = nodes.find((n) => n.id === assetsEdge.target);
-        if (targetNode) {
-          const ref = getSourceRef(assetsEdge, ctx);
-          if (ref) {
+        const assetsEdge = itemsEdges[0];
+        if (!assetsEdge) {
+          flow.push({ id: flowId, type: 'transform', logic: { transform: '[]' } });
+        } else {
+          const targetNode = nodes.find((n) => n.id === assetsEdge.target);
+          const ref = targetNode ? getSourceRef(assetsEdge, ctx) : undefined;
+          if (targetNode && ref) {
             const outHandle = targetNode.data.outputHandles?.find((h) => h.id === assetsEdge.targetHandle);
             const varName = getOutputHandleVarName(targetNode.id, outHandle?.name ?? 'output');
-            const sliceData = node.data as { from?: number | string; count?: number | string };
             const from = parseInt(String(sliceData.from ?? ''), 10) || 0;
             const count = parseInt(String(sliceData.count ?? ''), 10) || 0;
             const transform =