@exellix/graphs-studio-data-flow 0.1.0

package/src/lib/recordEligibilityRules.js

@@ -0,0 +1,542 @@
+/**
+ * Structured record eligibility under `conditions.dataFilters` on task nodes.
+ * Supports legacy `string[]` (path presence) and `{ match, rules, groups? }`.
+ *
+ * @typedef {{ fieldId?: string, label?: string, path: string, type?: string, operator: string, value?: unknown }} RecordEligibilityRule
+ * @typedef {{ match?: 'all'|'any', rules?: RecordEligibilityRule[], groups?: unknown[] }} RecordEligibilityFilters
+ */
+
+import { decodeJsonConditionsToRecordFilters } from './recordFiltersJsonConditionsBridge.js';
+
+/** @param {unknown} v */
+function isEmptyValue(v) {
+  if (v === null || v === undefined) return true;
+  if (typeof v === 'string') return v.trim() === '';
+  if (Array.isArray(v)) return v.length === 0;
+  if (typeof v === 'object') return Object.keys(v).length === 0;
+  return false;
+}
+
+/** @param {unknown} obj
+ * @param {string} dotPath */
+function deepGet(obj, dotPath) {
+  const p = String(dotPath || '').trim();
+  if (!p || obj == null || typeof obj !== 'object') return undefined;
+  const parts = p.split('.').filter(Boolean);
+  let cur = obj;
+  for (const key of parts) {
+    if (cur == null || typeof cur !== 'object') return undefined;
+    cur = /** @type {Record<string, unknown>} */ (cur)[key];
+  }
+  return cur;
+}
+
+/**
+ * Resolve a rule path against execution/job memory (playground-style context).
+ * @param {{ execution?: Record<string, unknown>, jobMemory?: Record<string, unknown>, taskMemory?: Record<string, unknown> }} ctx
+ * @param {string} path
+ */
+export function resolveEligibilityPath(ctx, path) {
+  const raw = String(path || '').trim();
+  if (!raw) return undefined;
+  const execution = ctx.execution && typeof ctx.execution === 'object' && !Array.isArray(ctx.execution) ? ctx.execution : {};
+  const jobMemory = ctx.jobMemory && typeof ctx.jobMemory === 'object' && !Array.isArray(ctx.jobMemory) ? ctx.jobMemory : {};
+  const taskMemory = ctx.taskMemory && typeof ctx.taskMemory === 'object' && !Array.isArray(ctx.taskMemory) ? ctx.taskMemory : {};
+  if (raw.startsWith('execution.')) return deepGet(execution, raw.slice('execution.'.length));
+  if (raw.startsWith('jobMemory.')) return deepGet(jobMemory, raw.slice('jobMemory.'.length));
+  if (raw.startsWith('taskMemory.')) return deepGet(taskMemory, raw.slice('taskMemory.'.length));
+  if (raw.startsWith('input.')) {
+    const input = execution.input != null && typeof execution.input === 'object' && !Array.isArray(execution.input) ? execution.input : {};
+    return deepGet(input, raw.slice('input.'.length));
+  }
+  const input = execution.input != null && typeof execution.input === 'object' && !Array.isArray(execution.input) ? execution.input : {};
+  const fromInput = deepGet(input, raw);
+  if (fromInput !== undefined) return fromInput;
+  return deepGet(execution, raw);
+}
+
+const STRING_OPS = new Set([
+  'equals',
+  'doesNotEqual',
+  'contains',
+  'doesNotContain',
+  'startsWith',
+  'endsWith',
+  'isEmpty',
+  'isNotEmpty',
+  'matchesRegex',
+]);
+
+const NUMBER_OPS = new Set([
+  'equals',
+  'doesNotEqual',
+  'greaterThan',
+  'greaterThanOrEqual',
+  'lessThan',
+  'lessThanOrEqual',
+  'between',
+  'isEmpty',
+  'isNotEmpty',
+]);
+
+const BOOL_OPS = new Set(['isTrue', 'isFalse', 'isEmpty', 'isNotEmpty']);
+
+const DATE_OPS = new Set(['before', 'after', 'between', 'inTheLast', 'olderThan', 'isEmpty', 'isNotEmpty']);
+
+const ARRAY_OPS = new Set([
+  'contains',
+  'doesNotContain',
+  'containsAnyOf',
+  'containsAllOf',
+  'isEmpty',
+  'isNotEmpty',
+]);
+
+/** @param {string} type */
+export function operatorsForFieldType(type) {
+  const t = String(type || 'unknown').toLowerCase();
+  if (t === 'number' || t === 'integer') return [...NUMBER_OPS];
+  if (t === 'boolean') return [...BOOL_OPS];
+  if (t === 'date' || t === 'datetime') return [...DATE_OPS];
+  if (t === 'array') return [...ARRAY_OPS];
+  return [...STRING_OPS];
+}
+
+/** @param {number} ts */
+function toMillis(ts) {
+  if (typeof ts === 'number' && Number.isFinite(ts)) return ts;
+  if (typeof ts === 'string' && ts.trim()) {
+    const d = Date.parse(ts);
+    return Number.isFinite(d) ? d : NaN;
+  }
+  return NaN;
+}
+
+/** @param {unknown} v */
+function asNumber(v) {
+  if (typeof v === 'number' && Number.isFinite(v)) return v;
+  if (typeof v === 'string' && v.trim() !== '') {
+    const n = Number(v);
+    return Number.isFinite(n) ? n : NaN;
+  }
+  return NaN;
+}
+
+/**
+ * @param {RecordEligibilityRule} rule
+ * @param {unknown} actual
+ */
+export function evaluateRule(rule, actual) {
+  const op = String(rule.operator || '');
+  const val = rule.value;
+  const empty = isEmptyValue(actual);
+
+  if (op === 'isEmpty') return empty;
+  if (op === 'isNotEmpty') return !empty;
+
+  if (op === 'isTrue') return actual === true;
+  if (op === 'isFalse') return actual === false;
+
+  if (op === 'equals') {
+    const an = asNumber(actual);
+    const vn = asNumber(val);
+    if (Number.isFinite(an) && Number.isFinite(vn)) return an === vn;
+    return String(actual ?? '') === String(val ?? '');
+  }
+  if (op === 'doesNotEqual') {
+    const an = asNumber(actual);
+    const vn = asNumber(val);
+    if (Number.isFinite(an) && Number.isFinite(vn)) return an !== vn;
+    return String(actual ?? '') !== String(val ?? '');
+  }
+
+  if (op === 'between' && (rule.type === 'date' || rule.type === 'datetime')) {
+    const at = toMillis(actual);
+    const o = val && typeof val === 'object' && !Array.isArray(val) ? val : {};
+    const lo = toMillis(/** @type {{ start?: unknown }} */ (o).start);
+    const hi = toMillis(/** @type {{ end?: unknown }} */ (o).end);
+    return Number.isFinite(at) && Number.isFinite(lo) && Number.isFinite(hi) && at >= lo && at <= hi;
+  }
+
+  const at = toMillis(actual);
+  const vt = toMillis(val);
+  if (op === 'before') return Number.isFinite(at) && Number.isFinite(vt) && at < vt;
+  if (op === 'after') return Number.isFinite(at) && Number.isFinite(vt) && at > vt;
+  if (op === 'inTheLast') {
+    const o = val && typeof val === 'object' && !Array.isArray(val) ? val : {};
+    const amount = asNumber(/** @type {{ amount?: unknown }} */ (o).amount);
+    const unit = String(/** @type {{ unit?: unknown }} */ (o).unit || 'days');
+    if (!Number.isFinite(at) || !Number.isFinite(amount) || amount < 0) return false;
+    const now = Date.now();
+    let ms = amount * 24 * 60 * 60 * 1000;
+    if (unit === 'hours') ms = amount * 60 * 60 * 1000;
+    if (unit === 'minutes') ms = amount * 60 * 1000;
+    return at >= now - ms && at <= now;
+  }
+  if (op === 'olderThan') {
+    const o = val && typeof val === 'object' && !Array.isArray(val) ? val : {};
+    const amount = asNumber(/** @type {{ amount?: unknown }} */ (o).amount);
+    const unit = String(/** @type {{ unit?: unknown }} */ (o).unit || 'days');
+    if (!Number.isFinite(at) || !Number.isFinite(amount) || amount < 0) return false;
+    const now = Date.now();
+    let ms = amount * 24 * 60 * 60 * 1000;
+    if (unit === 'hours') ms = amount * 60 * 60 * 1000;
+    if (unit === 'minutes') ms = amount * 60 * 1000;
+    return at < now - ms;
+  }
+
+  const an = asNumber(actual);
+  const vn = asNumber(val);
+  if (op === 'greaterThan') return Number.isFinite(an) && Number.isFinite(vn) && an > vn;
+  if (op === 'greaterThanOrEqual') return Number.isFinite(an) && Number.isFinite(vn) && an >= vn;
+  if (op === 'lessThan') return Number.isFinite(an) && Number.isFinite(vn) && an < vn;
+  if (op === 'lessThanOrEqual') return Number.isFinite(an) && Number.isFinite(vn) && an <= vn;
+  if (op === 'between') {
+    const lo = val && typeof val === 'object' && !Array.isArray(val) ? asNumber(/** @type {{ min?: unknown }} */ (val).min) : NaN;
+    const hi = val && typeof val === 'object' && !Array.isArray(val) ? asNumber(/** @type {{ max?: unknown }} */ (val).max) : NaN;
+    return Number.isFinite(an) && Number.isFinite(lo) && Number.isFinite(hi) && an >= lo && an <= hi;
+  }
+
+  if (typeof actual === 'string' || typeof val === 'string') {
+    if (op === 'contains') return typeof actual === 'string' && typeof val === 'string' && actual.includes(val);
+    if (op === 'doesNotContain') return typeof actual === 'string' && typeof val === 'string' && !actual.includes(val);
+    if (op === 'startsWith') return typeof actual === 'string' && typeof val === 'string' && actual.startsWith(val);
+    if (op === 'endsWith') return typeof actual === 'string' && typeof val === 'string' && actual.endsWith(val);
+    if (op === 'matchesRegex') {
+      if (typeof actual !== 'string' || typeof val !== 'string') return false;
+      try {
+        return new RegExp(val).test(actual);
+      } catch {
+        return false;
+      }
+    }
+  }
+
+  const arr = Array.isArray(actual) ? actual : typeof actual === 'string' ? [actual] : actual != null ? [actual] : [];
+  const asStrings = (x) => (Array.isArray(x) ? x : [x]).map((y) => String(y));
+  if (op === 'contains' && Array.isArray(actual)) {
+    const needle = String(val ?? '');
+    return arr.some((x) => String(x).includes(needle));
+  }
+  if (op === 'doesNotContain' && Array.isArray(actual)) {
+    const needle = String(val ?? '');
+    return !arr.some((x) => String(x).includes(needle));
+  }
+  if (op === 'containsAnyOf') {
+    const needles = asStrings(val);
+    return needles.some((n) => arr.some((x) => String(x) === n || String(x).includes(n)));
+  }
+  if (op === 'containsAllOf') {
+    const needles = asStrings(val);
+    return needles.every((n) => arr.some((x) => String(x) === n || String(x).includes(n)));
+  }
+
+  return false;
+}
+
+/**
+ * @param {unknown} raw
+ * @returns {RecordEligibilityFilters | null}
+ */
+export function normalizeConditionsDataFilters(raw) {
+  if (raw == null) return null;
+  if (Array.isArray(raw)) {
+    const paths = raw.map((x) => String(x).trim()).filter(Boolean);
+    if (paths.length === 0) return null;
+    return {
+      match: 'all',
+      rules: paths.map((path) => ({
+        path,
+        type: 'unknown',
+        operator: 'isNotEmpty',
+        label: humanizePathLabel(path),
+      })),
+    };
+  }
+  if (typeof raw !== 'object' || Array.isArray(raw)) return null;
+  const o = /** @type {Record<string, unknown>} */ (raw);
+  const match = o.match === 'any' ? 'any' : 'all';
+  const rulesRaw = Array.isArray(o.rules) ? o.rules : [];
+  /** @type {RecordEligibilityRule[]} */
+  const rules = [];
+  for (const r of rulesRaw) {
+    if (!r || typeof r !== 'object' || Array.isArray(r)) continue;
+    const row = /** @type {Record<string, unknown>} */ (r);
+    const path = typeof row.path === 'string' ? row.path.trim() : '';
+    if (!path) continue;
+    const operator = typeof row.operator === 'string' ? row.operator.trim() : 'isNotEmpty';
+    rules.push({
+      fieldId: typeof row.fieldId === 'string' ? row.fieldId : undefined,
+      label: typeof row.label === 'string' ? row.label : undefined,
+      path,
+      type: typeof row.type === 'string' ? row.type : 'string',
+      operator,
+      value: row.value,
+    });
+  }
+  if (rules.length === 0 && !Array.isArray(o.groups)) return null;
+  return { match, rules, groups: Array.isArray(o.groups) ? o.groups : undefined };
+}
+
+/** @param {string} path */
+export function humanizePathLabel(path) {
+  const tail = String(path || '').split('.').filter(Boolean).pop() || path;
+  return tail
+    .replace(/([a-z])([A-Z])/g, '$1 $2')
+    .replace(/[_-]+/g, ' ')
+    .replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+/**
+ * @param {RecordEligibilityFilters | null} filters
+ * @param {{ execution?: Record<string, unknown>, jobMemory?: Record<string, unknown>, taskMemory?: Record<string, unknown> }} ctx
+ */
+export function evaluateRecordEligibilityFilters(filters, ctx) {
+  if (!filters || !Array.isArray(filters.rules) || filters.rules.length === 0) {
+    return { passed: true, matchedRules: 0, failedRules: 0, ruleResults: [], reason: 'no_rules' };
+  }
+  const mode = filters.match === 'any' ? 'any' : 'all';
+  /** @type {{ rule: RecordEligibilityRule, passed: boolean, actual: unknown }[]} */
+  const ruleResults = [];
+  for (const rule of filters.rules) {
+    const actual = resolveEligibilityPath(ctx, rule.path);
+    const passed = evaluateRule(rule, actual);
+    ruleResults.push({ rule, passed, actual });
+  }
+  const passedCount = ruleResults.filter((x) => x.passed).length;
+  const failedCount = ruleResults.length - passedCount;
+  const passed = mode === 'any' ? passedCount > 0 : failedCount === 0;
+  return {
+    passed,
+    matchedRules: passedCount,
+    failedRules: failedCount,
+    ruleResults,
+    mode,
+  };
+}
+
+/**
+ * Playground gate: OR across configured arms (narratives, structured data filters, ai filter).
+ * Narratives / AI are not evaluated here — reported with `evaluated: false` so execution is not blocked.
+ *
+ * @param {Record<string, unknown>|null|undefined} conditions
+ * @param {{ execution?: Record<string, unknown>, jobMemory?: Record<string, unknown>, taskMemory?: Record<string, unknown> }} ctx
+ */
+export function evaluateNodeConditionsForPlayground(conditions, ctx) {
+  const c = conditions && typeof conditions === 'object' && !Array.isArray(conditions) ? conditions : {};
+  const narratives = Array.isArray(c.narratives) ? c.narratives.map((x) => String(x)).filter(Boolean) : [];
+  const aiCond =
+    c.aiCondition && typeof c.aiCondition === 'object' && !Array.isArray(c.aiCondition)
+      ? /** @type {Record<string, unknown>} */ (c.aiCondition)
+      : {};
+  const aiFilter =
+    typeof aiCond.condition === 'string'
+      ? aiCond.condition.trim()
+      : typeof c.aiFilter === 'string'
+        ? c.aiFilter.trim()
+        : '';
+  const df = normalizeConditionsDataFilters(c.dataFilters) || decodeJsonConditionsToRecordFilters(c.jsonConditions);
+
+  const arms = [];
+  if (narratives.length > 0) {
+    arms.push({
+      id: 'narratives',
+      passed: true,
+      evaluated: false,
+      note: 'Narrative eligibility is evaluated by the graph engine / Narrix runtime, not the playground execute stub.',
+    });
+  }
+  if (df && df.rules && df.rules.length > 0) {
+    const ev = evaluateRecordEligibilityFilters(df, ctx);
+    arms.push({
+      id: 'dataFilters',
+      passed: ev.passed,
+      evaluated: true,
+      detail: ev,
+    });
+  }
+  if (aiFilter) {
+    arms.push({
+      id: 'aiCondition',
+      passed: true,
+      evaluated: false,
+      note: 'AI condition prompt is not evaluated in the playground execute stub; the graph engine should apply it.',
+    });
+  }
+
+  if (arms.length === 0) {
+    return { skip: false, arms: [], combinedPassed: true };
+  }
+  const combinedPassed = arms.some((a) => a.passed);
+  return {
+    skip: !combinedPassed,
+    arms,
+    combinedPassed,
+  };
+}
+
+/**
+ * Same evaluation rules as {@link evaluateNodeConditionsForPlayground}: `metadata.graphEntry.conditions`
+ * uses the identical payload shape as task `conditions`.
+ *
+ * @param {Record<string, unknown>|null|undefined} graphEntryConditions
+ * @param {{ execution?: Record<string, unknown>, jobMemory?: Record<string, unknown>, taskMemory?: Record<string, unknown> }} ctx
+ */
+export function evaluateGraphEntryConditionsForPlayground(graphEntryConditions, ctx) {
+  return evaluateNodeConditionsForPlayground(graphEntryConditions, ctx);
+}
+
+/**
+ * @param {unknown} example
+ * @returns {Record<string, unknown>|null}
+ */
+export function tryParseJsonObjectExample(example) {
+  if (!example || typeof example !== 'object' || Array.isArray(example)) return null;
+  const format = typeof example.format === 'string' ? example.format : 'json';
+  const value = example.value;
+  if (typeof value !== 'string' || !value.trim()) return null;
+  if (format !== 'json') return null;
+  try {
+    const parsed = JSON.parse(value);
+    if (parsed != null && typeof parsed === 'object' && !Array.isArray(parsed)) return /** @type {Record<string, unknown>} */ (parsed);
+  } catch {
+    return null;
+  }
+  return null;
+}
+
+/**
+ * Build field picker options for the Record Filters UI.
+ * @param {{
+ *   graphData?: Record<string, unknown>|null,
+ *   smartInputPaths?: { path: string, title?: string }[],
+ *   runtimeReadPaths?: string[],
+ * }} p
+ */
+export function buildRecordFilterFieldCatalog(p) {
+  /** @type {{ id: string, label: string, path: string, section: string, type: string, enumValues?: string[] }[]} */
+  const out = [];
+  const seen = new Set();
+
+  const push = (id, label, path, section, type, enumValues) => {
+    const key = `${section}:${path}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    out.push({ id, label, path, section, type, ...(enumValues?.length ? { enumValues } : {}) });
+  };
+
+  const ge = p.graphData?.metadata && typeof p.graphData.metadata === 'object' && !Array.isArray(p.graphData.metadata)
+    ? /** @type {Record<string, unknown>} */ (p.graphData.metadata).graphEntry
+    : null;
+  const geObj = ge && typeof ge === 'object' && !Array.isArray(ge) ? /** @type {Record<string, unknown>} */ (ge) : null;
+  const ex = geObj?.exampleInput ?? (Array.isArray(geObj?.exampleInputs) ? geObj.exampleInputs[0] : null);
+  const sample = tryParseJsonObjectExample(ex);
+  if (sample) {
+    for (const k of Object.keys(sample)) {
+      const v = sample[k];
+      const t = inferTypeFromValue(v);
+      push(`record:${k}`, humanizePathLabel(k), `input.${k}`, 'Record fields', t);
+    }
+  }
+
+  const inputs = geObj && Array.isArray(geObj.inputs) ? geObj.inputs : [];
+  for (const row of inputs) {
+    if (!row || typeof row !== 'object' || Array.isArray(row)) continue;
+    const r = /** @type {Record<string, unknown>} */ (row);
+    const pathStr = typeof r.path === 'string' ? r.path.trim() : '';
+    if (!pathStr) continue;
+    const name = typeof r.name === 'string' ? r.name : typeof r.title === 'string' ? r.title : humanizePathLabel(pathStr);
+    const fullPath = pathStr.startsWith('execution.') ? pathStr : pathStr.startsWith('input.') ? pathStr : `input.${pathStr}`;
+    push(`entry:${pathStr}`, String(name), fullPath, 'Record fields', inferTypeFromValue(r.example));
+  }
+
+  for (const sp of p.smartInputPaths || []) {
+    const path = String(sp.path || '').trim();
+    if (!path) continue;
+    const full = path.startsWith('input.') ? path : `input.${path.replace(/^\.+/, '')}`;
+    const title = String(sp.title || '').trim();
+    push(`smart:${path}`, title || humanizePathLabel(path), full, 'Smart input fields', 'string');
+  }
+
+  for (const path of p.runtimeReadPaths || []) {
+    const pth = String(path || '').trim();
+    if (!pth) continue;
+    push(`rt:${pth}`, humanizePathLabel(pth.split('.').pop() || pth), pth, 'Runtime fields', 'unknown');
+  }
+
+  return out;
+}
+
+/** @param {unknown} v */
+function inferTypeFromValue(v) {
+  if (v == null) return 'string';
+  if (typeof v === 'number') return 'number';
+  if (typeof v === 'boolean') return 'boolean';
+  if (Array.isArray(v)) return 'array';
+  if (typeof v === 'string') {
+    if (/^\d{4}-\d{2}-\d{2}/.test(v) && Number.isFinite(Date.parse(v))) return 'date';
+    return 'string';
+  }
+  return 'string';
+}
+
+/**
+ * @param {RecordEligibilityFilters|null} filters
+ * @param {Record<string, unknown>[]} samples
+ */
+export function previewRecordEligibilityAgainstSamples(filters, samples) {
+  if (!filters || !filters.rules?.length || !Array.isArray(samples) || samples.length === 0) {
+    return { available: false, reason: 'No sample records or no rules to evaluate.', totalRecords: 0, matchedRecords: 0, previewRows: [] };
+  }
+  let matched = 0;
+  /** @type {Record<string, unknown>[]} */
+  const previewRows = [];
+  for (const rec of samples) {
+    const ctx = { execution: { input: rec } };
+    const ev = evaluateRecordEligibilityFilters(filters, ctx);
+    if (ev.passed) {
+      matched++;
+      if (previewRows.length < 25) previewRows.push(rec);
+    }
+  }
+  return {
+    available: true,
+    totalRecords: samples.length,
+    matchedRecords: matched,
+    previewRows,
+  };
+}
+
+/**
+ * Sample `execution.input`-shaped objects for Studio preview (graph examples + last run snapshot).
+ * @param {Record<string, unknown>|null|undefined} graphData
+ * @param {unknown} lastExec
+ */
+export function collectStudioRecordFilterSamples(graphData, lastExec) {
+  /** @type {Record<string, unknown>[]} */
+  const samples = [];
+  const push = (o) => {
+    if (o && typeof o === 'object' && !Array.isArray(o)) samples.push(/** @type {Record<string, unknown>} */ (o));
+  };
+  const md =
+    graphData?.metadata && typeof graphData.metadata === 'object' && !Array.isArray(graphData.metadata)
+      ? /** @type {Record<string, unknown>} */ (graphData.metadata)
+      : null;
+  const ge = md?.graphEntry && typeof md.graphEntry === 'object' && !Array.isArray(md.graphEntry) ? md.graphEntry : null;
+  if (ge) {
+    const inputs = Array.isArray(ge.exampleInputs) ? ge.exampleInputs : [];
+    for (const ex of inputs) {
+      const o = tryParseJsonObjectExample(ex);
+      if (o) push(o);
+    }
+    const one = tryParseJsonObjectExample(ge.exampleInput);
+    if (one) push(one);
+  }
+  const le = lastExec && typeof lastExec === 'object' && !Array.isArray(lastExec) ? /** @type {Record<string, unknown>} */ (lastExec) : null;
+  const ep = le?.executionPreview && typeof le.executionPreview === 'object' && !Array.isArray(le.executionPreview)
+    ? /** @type {Record<string, unknown>} */ (le.executionPreview)
+    : null;
+  const inp = ep?.input;
+  if (inp && typeof inp === 'object' && !Array.isArray(inp)) push(/** @type {Record<string, unknown>} */ (inp));
+  return samples;
+}

package/src/lib/recordFiltersJsonConditionsBridge.js

@@ -0,0 +1,97 @@
+/**
+ * Bridge studio record-eligibility UI (`RecordEligibilityFilters`) and canonical
+ * `conditions.jsonConditions` (`{ condition, parameters?, negate? }`).
+ */
+
+/** Studio convention — graph-engine accepts any non-empty `condition` string. */
+export const RECORD_ELIGIBILITY_JSON_CONDITION_ID = 'exellix.recordEligibility.v1';
+
+/**
+ * @typedef {import('./recordEligibilityRules.js').RecordEligibilityFilters} RecordEligibilityFilters
+ */
+
+/**
+ * @param {RecordEligibilityFilters | null | undefined} filters
+ * @returns {Record<string, unknown> | undefined}
+ */
+export function encodeRecordFiltersToJsonConditions(filters) {
+  if (!filters || !Array.isArray(filters.rules) || filters.rules.length === 0) return undefined;
+  const match = filters.match === 'any' ? 'any' : 'all';
+  /** @type {Record<string, unknown>[]} */
+  const rules = [];
+  for (const r of filters.rules) {
+    if (!r || typeof r !== 'object') continue;
+    const path = typeof r.path === 'string' ? r.path.trim() : '';
+    const operator = typeof r.operator === 'string' ? r.operator.trim() : '';
+    if (!path || !operator) continue;
+    /** @type {Record<string, unknown>} */
+    const rule = { path, operator };
+    if (typeof r.type === 'string' && r.type.trim()) rule.type = r.type.trim();
+    if (r.value !== undefined && r.value !== '') rule.value = r.value;
+    if (typeof r.fieldId === 'string' && r.fieldId.trim()) rule.fieldId = r.fieldId.trim();
+    if (typeof r.label === 'string' && r.label.trim()) rule.label = r.label.trim();
+    rules.push(rule);
+  }
+  if (rules.length === 0) return undefined;
+  /** @type {Record<string, unknown>} */
+  const parameters = { match, rules };
+  if (Array.isArray(filters.groups) && filters.groups.length > 0) {
+    parameters.groups = filters.groups;
+  }
+  return {
+    condition: RECORD_ELIGIBILITY_JSON_CONDITION_ID,
+    parameters,
+  };
+}
+
+/**
+ * @param {unknown} jsonConditions
+ * @returns {RecordEligibilityFilters | undefined}
+ */
+export function decodeJsonConditionsToRecordFilters(jsonConditions) {
+  if (!jsonConditions || typeof jsonConditions !== 'object' || Array.isArray(jsonConditions)) return undefined;
+  const jc = /** @type {Record<string, unknown>} */ (jsonConditions);
+  if (jc.condition !== RECORD_ELIGIBILITY_JSON_CONDITION_ID) return undefined;
+  const params = jc.parameters;
+  if (!params || typeof params !== 'object' || Array.isArray(params)) return undefined;
+  const p = /** @type {Record<string, unknown>} */ (params);
+  const match = p.match === 'any' ? 'any' : 'all';
+  const rulesRaw = Array.isArray(p.rules) ? p.rules : [];
+  /** @type {import('./recordEligibilityRules.js').RecordEligibilityRule[]} */
+  const rules = [];
+  for (const r of rulesRaw) {
+    if (!r || typeof r !== 'object' || Array.isArray(r)) continue;
+    const row = /** @type {Record<string, unknown>} */ (r);
+    const path = typeof row.path === 'string' ? row.path.trim() : '';
+    const operator = typeof row.operator === 'string' ? row.operator.trim() : '';
+    if (!path || !operator) continue;
+    /** @type {import('./recordEligibilityRules.js').RecordEligibilityRule} */
+    const rule = { path, operator };
+    if (typeof row.type === 'string') rule.type = row.type;
+    if (row.value !== undefined) rule.value = row.value;
+    if (typeof row.fieldId === 'string') rule.fieldId = row.fieldId;
+    if (typeof row.label === 'string') rule.label = row.label;
+    rules.push(rule);
+  }
+  if (rules.length === 0) return undefined;
+  /** @type {RecordEligibilityFilters} */
+  const out = { match, rules };
+  if (Array.isArray(p.groups) && p.groups.length > 0) out.groups = p.groups;
+  return out;
+}
+
+/**
+ * @param {unknown} conditions
+ * @returns {RecordEligibilityFilters | undefined}
+ */
+export function readRecordFiltersFromConditions(conditions) {
+  if (!conditions || typeof conditions !== 'object' || Array.isArray(conditions)) return undefined;
+  const c = /** @type {Record<string, unknown>} */ (conditions);
+  const fromJson = decodeJsonConditionsToRecordFilters(c.jsonConditions);
+  if (fromJson) return fromJson;
+  const df = c.dataFilters;
+  if (df && typeof df === 'object' && !Array.isArray(df)) {
+    return /** @type {RecordEligibilityFilters} */ (df);
+  }
+  return undefined;
+}