formlab-mcp 0.6.49 → 0.6.50

package/vendor/nesting.js

@@ -0,0 +1,323 @@
+// ============================================================
+// NESTED FORMULATIONS — plumbing
+// ============================================================
+// A composition row can reference either an ingredient (c.ingredientId)
+// OR another formulation (c.formulationId). Exactly one of the two is
+// set. A row pointing at a formulation is a "sub-formula" row.
+//
+// The helpers here are the foundation for milestones 2-6 (modal,
+// recursive cost/fractions, rollups, version pointers).
+// ============================================================
+
+const MAX_NESTING_DEPTH = 5;
+
+// True if the composition row points at another formulation.
+function isSubFormulaRow(c) {
+  return !!(c && c.formulationId);
+}
+
+// Resolve a row to its referenced formulation, or null if missing/deleted.
+function _resolveSubFormula(c) {
+  if (!c || !c.formulationId) return null;
+  return db.formulations.find(f => f.id === c.formulationId) || null;
+}
+
+// Compute the max nesting depth under `formulation`. A formulation with
+// no sub-formula rows has depth 0. Returns Infinity if a cycle is hit
+// (defensive — cycles should be blocked at add time, but never trust
+// stored data blindly).
+function _subTreeDepth(formulation, _seen) {
+  if (!formulation) return 0;
+  _seen = _seen || new Set();
+  if (_seen.has(formulation.id)) return Infinity;
+  _seen.add(formulation.id);
+  let maxChild = 0;
+  for (const c of (formulation.composition || [])) {
+    if (!isSubFormulaRow(c)) continue;
+    const child = _resolveSubFormula(c);
+    if (!child) continue;
+    const d = _subTreeDepth(child, _seen) + 1;
+    if (d > maxChild) maxChild = d;
+  }
+  _seen.delete(formulation.id);
+  return maxChild;
+}
+
+// True if including `candidateId` as a sub-formula inside `parentId`
+// would (directly or indirectly) reference `parentId`. parentId may be
+// null for new formulations being authored (no cycle possible yet).
+function hasCycle(parentId, candidateId) {
+  if (!parentId || !candidateId) return false;
+  if (parentId === candidateId) return true;
+  const candidate = db.formulations.find(f => f.id === candidateId);
+  if (!candidate) return false;
+  // Walk descendants of candidate; if we find parentId anywhere, that's a cycle.
+  const stack = [candidate];
+  const seen = new Set([candidate.id]);
+  while (stack.length) {
+    const cur = stack.pop();
+    for (const c of (cur.composition || [])) {
+      if (!isSubFormulaRow(c)) continue;
+      if (c.formulationId === parentId) return true;
+      if (seen.has(c.formulationId)) continue;
+      seen.add(c.formulationId);
+      const child = _resolveSubFormula(c);
+      if (child) stack.push(child);
+    }
+  }
+  return false;
+}
+
+// Combined gate the modal will call before letting the user add a row.
+// Returns { ok: true } or { ok: false, reason: '...' }.
+function canIncludeSubFormula(parentId, candidateId) {
+  if (!candidateId) return { ok: false, reason: 'No formulation selected' };
+  const candidate = db.formulations.find(f => f.id === candidateId);
+  if (!candidate) return { ok: false, reason: 'Formulation not found' };
+  if (parentId && parentId === candidateId) {
+    return { ok: false, reason: 'Cannot include a formulation in itself' };
+  }
+  if (hasCycle(parentId, candidateId)) {
+    return { ok: false, reason: 'Would create a cycle' };
+  }
+  // Parent's existing depth + 1 (new child) + candidate's own sub-tree
+  // must fit within MAX_NESTING_DEPTH.
+  const parent = parentId ? db.formulations.find(f => f.id === parentId) : null;
+  const parentDepth = parent ? _subTreeDepth(parent) : 0;
+  const candidateDepth = _subTreeDepth(candidate);
+  const totalDepth = Math.max(parentDepth, 1 + candidateDepth);
+  if (totalDepth > MAX_NESTING_DEPTH) {
+    return { ok: false, reason: `Exceeds depth limit (${MAX_NESTING_DEPTH} levels)` };
+  }
+  return { ok: true };
+}
+
+// Recursively expand a formulation's composition into a flat list of
+// pure-ingredient rows. Each output row is:
+//   {
+//     ingredientId, amount, unit,         // same shape as a normal row
+//     _weight,                            // fractional weight of this row
+//                                         //   relative to the ROOT formulation
+//                                         //   (1.0 = the whole root). Useful
+//                                         //   for cost/fraction roll-up math.
+//     _path: [formulationId, ...]         // sub-formula chain that led here
+//   }
+//
+// Strategy: at each level we compute each row's wt-fraction within its
+// own parent (using normalized wt%/g/etc). For sub-formula rows we
+// recurse and multiply child fractions by the parent's fraction. For
+// ingredient rows we emit a flat row carrying _weight = parentWeight ×
+// rowFraction.
+//
+// Caveats:
+//  - This is a fraction-only flatten. Absolute units inside a
+//    sub-formula are normalized to wt-fractions of that sub-formula
+//    before being scaled by the parent's contribution. Computing cost
+//    and percentages from this output is straightforward; reconstructing
+//    absolute masses requires a separate basis assumption (the caller's
+//    job).
+//  - Rows with unknown/unparseable amounts contribute 0.
+//  - Volume units (mL etc.) are converted to mass via the ingredient's
+//    density if known, otherwise the row contributes 0 and is logged in
+//    `unresolved` for the caller to surface.
+function _flattenComposition(formulation, opts) {
+  opts = opts || {};
+  const out = [];
+  const unresolved = [];
+
+  function walk(f, weight, path, depth) {
+    if (!f || weight <= 0) return;
+    if (depth > MAX_NESTING_DEPTH) {
+      unresolved.push({ reason: 'depth-limit', formulationId: f.id, path: path.slice() });
+      return;
+    }
+    const rawRows = Array.isArray(f.composition) ? f.composition : [];
+    const rows = rawRows.filter(c => c && (c.ingredientId || c.formulationId));
+    if (!rows.length) return;
+
+    // Compute each row's wt-fraction WITHIN this formulation. We reuse the
+    // same logic shape as computeCompositionFractions but inline here so
+    // this helper stays self-contained (computeCompositionFractions will
+    // grow to call back into _flattenComposition in milestone 3).
+    const fracs = _rowWtFractionsWithin(f, unresolved);
+
+    for (let i = 0; i < rows.length; i++) {
+      const c = rows[i];
+      const fr = fracs[i] || 0;
+      if (fr <= 0) continue;
+      if (isSubFormulaRow(c)) {
+        if (path.indexOf(c.formulationId) >= 0) {
+          unresolved.push({ reason: 'cycle', formulationId: c.formulationId, path: path.slice() });
+          continue;
+        }
+        const child = _resolveSubFormula(c);
+        if (!child) {
+          unresolved.push({ reason: 'deleted-subformula', formulationId: c.formulationId, path: path.slice() });
+          continue;
+        }
+        walk(child, weight * fr, path.concat([c.formulationId]), depth + 1);
+      } else {
+        // Carry the leaf's role so the flattened-view UI can render
+        // a rolled-up role column. Other consumers (cost / inventory /
+        // properties) ignore the field — additive, no breakage.
+        out.push({
+          ingredientId: c.ingredientId,
+          amount: c.amount,
+          unit: c.unit,
+          role: c.role || '',
+          _weight: weight * fr,
+          _path: path.slice(),
+        });
+      }
+    }
+  }
+
+  walk(formulation, 1, [formulation ? formulation.id : null].filter(Boolean), 0);
+  return { rows: out, unresolved };
+}
+
+// Rolled-up density (kg/L) of a formulation, computed by flattening to
+// leaf ingredients and taking the harmonic-mean density weighted by
+// each leaf's wt-fraction. Returns null if any leaf is missing density.
+//
+// Derivation: for a unit mass (1 kg) of the formulation, leaf i
+// contributes weight_i kg and occupies weight_i / density_i L. So
+// total volume per kg = Σ (weight_i / density_i), and the formulation
+// density is 1 / that sum.
+// Density the PLANNER should use for this formula (kg/L === g/mL), with its
+// provenance. A declared finished density (measured on a batch, or typed from
+// a spec) wins over the ideal-mix estimate, because real mixes contract or
+// expand — 50 mL ethanol + 50 mL water is 96 mL — and the estimate below
+// assumes they don't (2026-09-13, "volume-based batch target").
+//   → { kgPerL, source: 'finished' | 'ideal', temp, batchId, how } | null
+//   how: 'measured' | 'manual' | 'spec' (finished only)
+function formulaPlanningDensity(formulation) {
+  if (!formulation) return null;
+  const fd = formulation.finishedDensity;
+  const v = fd ? parseFloat(fd.value) : NaN;
+  if (isFinite(v) && v > 0) {
+    return { kgPerL: v, source: 'finished', temp: (fd.temp != null && fd.temp !== '') ? fd.temp : null,
+             batchId: fd.batchId || null, how: fd.source || 'manual' };
+  }
+  const est = _idealMixDensity(formulation);
+  return (est != null) ? { kgPerL: est, source: 'ideal', temp: null, batchId: null, how: null } : null;
+}
+
+// Effective density for every caller that needs "the formula's density"
+// (batch cost, actual-volume estimate, sub-formula rows, find-by-results…):
+// the declared finished density when there is one, else the ideal-mix
+// estimate. Synthetic objects ({ id, composition }) have no finishedDensity
+// and get the estimate as before.
+function _rolledUpDensity(formulation) {
+  const pd = formulaPlanningDensity(formulation);
+  return pd ? pd.kgPerL : null;
+}
+
+// Ideal-mix (sum-of-parts) estimate: harmonic mean of leaf densities weighted
+// by wt-fraction. Ignores contraction on mixing, entrained air and temperature.
+function _idealMixDensity(formulation) {
+  if (!formulation) return null;
+  const flat = _flattenComposition(formulation);
+  if (!flat.rows.length) return null;
+  let invSum = 0;
+  for (const r of flat.rows) {
+    if (r._weight <= 0) continue;
+    const ing = db.ingredients.find(i => i.id === r.ingredientId);
+    if (!ing) return null;
+    const d = (typeof _densityToKgPerL === 'function')
+      ? _densityToKgPerL(ing.density, ing.densityUnit) : null;
+    if (!d) return null;
+    invSum += r._weight / d;
+  }
+  return invSum > 0 ? 1 / invSum : null;
+}
+
+// Helper: per-row wt-fractions within a single formulation level (no
+// recursion). Looks at the row units, normalizes mass/volume rows to
+// kg via density where possible, and returns a parallel array of
+// fractions summing to ≤ 1. Pure wt%/% rows are normalized to sum to 1
+// if they sum to anything > 0.
+function _rowWtFractionsWithin(f, unresolved) {
+  // Defensive: tampered imports could land a truthy non-array here
+  // (string, object, number). `(f.composition || [])` only catches
+  // falsy — it would still try .filter() on the wrong shape and
+  // crash. Caught 2026-05-31 by import/export round-trip stress test.
+  const raw = Array.isArray(f.composition) ? f.composition : [];
+  const comp = raw.filter(c => c && (c.ingredientId || c.formulationId));
+  if (!comp.length) return [];
+
+  const kinds = comp.map(c => {
+    const u = String(c.unit || 'wt%').trim();
+    const lower = u.toLowerCase();
+    if (lower.startsWith('wt') || u === '%') return 'wt';
+    if (lower.startsWith('vol')) return 'vol';
+    if (typeof MASS_TO_KG !== 'undefined' && u in MASS_TO_KG) return 'mass';
+    if (typeof VOL_TO_L   !== 'undefined' && u in VOL_TO_L)   return 'volabs';
+    return 'unknown';
+  });
+
+  // A fractional row (wt%/vol%) and an absolute one (g, mL…) cannot be pooled:
+  // the conversion below turns absolute rows into kilograms while a fractional
+  // row contributes its RAW number, so "50 wt%" silently becomes 50 kg — making
+  // the same row read 99.98% beside 10 g and 0.5% beside 10 ton. There is no
+  // correct answer without a batch basis, so refuse to invent one: flag it and
+  // return zeros, the same shape this function already uses for a volume row
+  // with no density. The editor blocks new saves; this covers data that predates
+  // the block or arrived by import. wt% WITH vol% is NOT this case — density
+  // reconciles those, and they resolve through the branches below.
+  const _hasFrac = kinds.some(k => k === 'wt' || k === 'vol');
+  const _hasAbs  = kinds.some(k => k === 'mass' || k === 'volabs');
+  if (_hasFrac && _hasAbs) {
+    unresolved && unresolved.push({ reason: 'mixed-basis', formulationId: f ? f.id : null });
+    return comp.map(_ => 0);
+  }
+
+  const allWt = kinds.every(k => k === 'wt');
+  if (allWt) {
+    const nums = comp.map(c => Math.max(0, parseFloat(c.amount) || 0));
+    const sum = nums.reduce((a, b) => a + b, 0);
+    if (sum <= 0) return nums.map(_ => 0);
+    return nums.map(n => n / sum);
+  }
+
+  // For mass + vol absolute mixes: convert each to kg if possible (vol
+  // needs the ingredient density; sub-formula rows assume neutral mass
+  // for now — milestone 3 will refine with rollup density).
+  const kgPerRow = comp.map((c, i) => {
+    const u = String(c.unit || '').trim();
+    const amt = Math.max(0, parseFloat(c.amount) || 0);
+    if (!amt) return 0;
+    if (kinds[i] === 'mass') return amt * MASS_TO_KG[u];
+    if (kinds[i] === 'volabs') {
+      if (c.ingredientId) {
+        const ing = db.ingredients.find(x => x.id === c.ingredientId);
+        const d = ing ? _densityToKgPerL(ing.density, ing.densityUnit) : null;
+        if (d) return amt * VOL_TO_L[u] * d;
+        unresolved && unresolved.push({ reason: 'no-density', ingredientId: c.ingredientId });
+        return 0;
+      }
+      // Sub-formula volume row — compute the child's rolled-up density
+      // (mirrors the pattern js/cost.js already uses for sub-formula
+      // cost rollup). _rolledUpDensity recursively flattens the child;
+      // cycle/depth detection on _flattenComposition keeps the
+      // recursion bounded. When the child has at least one leaf with
+      // no density, _rolledUpDensity returns null and we surface a
+      // matching unresolved entry so the consumption modal can warn.
+      const child = _resolveSubFormula(c);
+      if (!child) {
+        unresolved && unresolved.push({ reason: 'deleted-subformula', formulationId: c.formulationId });
+        return 0;
+      }
+      const d = _rolledUpDensity(child);
+      if (d) return amt * VOL_TO_L[u] * d;
+      unresolved && unresolved.push({ reason: 'no-subformula-density', formulationId: c.formulationId });
+      return 0;
+    }
+    if (kinds[i] === 'wt')  return amt; // treat as relative weight
+    if (kinds[i] === 'vol') return amt; // treat as relative volume (best-effort)
+    return 0;
+  });
+  const sum = kgPerRow.reduce((a, b) => a + b, 0);
+  if (sum <= 0) return kgPerRow.map(_ => 0);
+  return kgPerRow.map(n => n / sum);
+}