dravoice 0.1.2 → 0.1.3

package/src/v2/stylometry.js

@@ -1,332 +1,342 @@
-import { clampScore, round } from "./text-utils.js";
-
-export const STYLOMETRIC_REFERENCES = [
-  "Burrows Delta (Burrows, 2002)",
-  "Cosine Delta (Smith & Aldridge, 2011)",
-  "Function-word stylometry (Kestemont, 2014)",
-  "Authorship-attribution feature families (Stamatatos, 2009)",
-  "Cohesion and discourse measures inspired by Coh-Metrix (Graesser et al., 2004)",
-];
-
-const DEFAULT_THRESHOLDS = {
-  rhythm: 0.36,
-  lexical: 0.32,
-  register: 0.45,
-  discourse: 0.28,
-  rhetoricalShape: 0.42,
-  evidence: 0.30,
-  structure: 0.42,
-};
-
-const FAMILY_WEIGHTS = {
-  rhythm: 0.75,
-  lexical: 0.85,
-  register: 0.50,
-  discourse: 0.70,
-  rhetoricalShape: 0.70,
-  evidence: 0.85,
-  structure: 0.65,
-};
-
-export function defaultStyleThresholds() {
-  return Object.fromEntries(Object.entries(DEFAULT_THRESHOLDS).map(([family, threshold]) => [
-    family,
-    { threshold, observations: 0, stability: 0.45 },
-  ]));
-}
-
-export function familyWeight(family) {
-  return FAMILY_WEIGHTS[family] ?? 0.6;
-}
-
-export function distanceByFamily(family, sourceFeatures, draftFeatures) {
-  if (family === "rhythm") {
-    return rhythmDistance(sourceFeatures, draftFeatures);
-  }
-  if (family === "lexical") {
-    return lexicalDistance(sourceFeatures, draftFeatures);
-  }
-  if (family === "register") {
-    return registerDistance(sourceFeatures, draftFeatures);
-  }
-  if (family === "discourse") {
-    return discourseDistance(sourceFeatures, draftFeatures);
-  }
-  if (family === "rhetoricalShape") {
-    return shapeDistance(sourceFeatures, draftFeatures);
-  }
-  if (family === "evidence") {
-    return evidenceDistance(sourceFeatures, draftFeatures);
-  }
-  if (family === "structure") {
-    return shapeDistance(sourceFeatures, draftFeatures);
-  }
-  return 0;
-}
-
-export function familyScoreFromDistance(distance, threshold) {
-  const ratio = distance / Math.max(0.01, threshold);
-  return clampScore(100 / (1 + Math.exp(3 * (ratio - 1.35))));
-}
-
-export function calibratedFamilyDrift(distance, threshold) {
-  return round(Math.max(0, distance - threshold) / Math.max(0.01, threshold), 3);
-}
-
-export function percentile(values, ratio) {
-  const sorted = values.filter((value) => Number.isFinite(value)).sort((left, right) => left - right);
-  if (sorted.length === 0) {
-    return 0;
-  }
-  const index = Math.min(sorted.length - 1, Math.max(0, Math.ceil((sorted.length - 1) * ratio)));
-  return sorted[index];
-}
-
-export function familyDiagnosticsFor(sourceProfile, draftProfile) {
-  const thresholds = sourceProfile.calibration?.styleThresholds?.families ?? defaultStyleThresholds();
-  return Object.fromEntries(Object.keys(sourceProfile.families).map((family) => {
-    const distance = distanceByFamily(
-      family,
-      sourceProfile.families[family].features,
-      draftProfile.families[family].features,
-    );
-    const thresholdData = thresholds[family] ?? defaultStyleThresholds()[family] ?? { threshold: 0.4, stability: 0.45 };
-    const threshold = thresholdData.threshold ?? 0.4;
-    return [family, {
-      distance,
-      threshold,
-      stability: thresholdData.stability ?? stabilityFromObservationCount(thresholdData.observations ?? 0),
-      drift: calibratedFamilyDrift(distance, threshold),
-      score: familyScoreFromDistance(distance, threshold),
-    }];
-  }));
-}
-
-export function styleDistanceFromDiagnostics(familyDiagnostics) {
-  const entries = Object.entries(familyDiagnostics);
-  const weighted = entries.map(([family, item]) => [
-    100 - item.score,
-    familyWeight(family) * Math.max(0.35, item.stability ?? 0.45),
-  ]);
-  return Math.round(weightedMean(weighted));
-}
-
-export function stabilityFromDistances(values) {
-  const finite = values.filter((value) => Number.isFinite(value));
-  if (finite.length < 2) {
-    return stabilityFromObservationCount(finite.length);
-  }
-  const mean = finite.reduce((sum, value) => sum + value, 0) / finite.length;
-  const variance = finite.reduce((sum, value) => sum + (value - mean) ** 2, 0) / finite.length;
-  const coefficient = Math.sqrt(variance) / Math.max(0.01, mean);
-  return round(Math.max(0.35, Math.min(1, 1 - coefficient)), 3);
-}
-
-function rhythmDistance(source, draft) {
-  return weightedMean([
-    [distributionDelta(source.sentenceWords, draft.sentenceWords), 0.40],
-    [distributionDelta(source.paragraphWords, draft.paragraphWords), 0.32],
-    [distributionDelta(source.paragraphSentences, draft.paragraphSentences), 0.16],
-    [Math.abs((source.listDensity ?? 0) - (draft.listDensity ?? 0)), 0.06],
-    [Math.abs((source.quoteDensity ?? 0) - (draft.quoteDensity ?? 0)), 0.06],
-  ]);
-}
-
-function lexicalDistance(source, draft) {
-  return weightedMean([
-    [topItemDistance(source.functionWords, draft.functionWords), 1.00],
-    [topItemDistance(source.functionWordBigrams, draft.functionWordBigrams), 0.75],
-    [topItemDistance(source.maskedCharacterFourgrams, draft.maskedCharacterFourgrams), 1.00],
-    [topItemDistance(source.characterTrigrams, draft.characterTrigrams), 0.45],
-    [topItemDistance(source.sentenceInitialTokens, draft.sentenceInitialTokens), 0.35],
-    [topItemDistance(source.sentenceFinalTokens, draft.sentenceFinalTokens), 0.35],
-    [topItemDistance(source.punctuationNgrams, draft.punctuationNgrams), 0.45],
-    [punctuationDistance(source.punctuation, draft.punctuation), 0.85],
-    [Math.abs((source.vocabularyRichness?.contentTypeTokenRatio ?? 0) - (draft.vocabularyRichness?.contentTypeTokenRatio ?? 0)), 0.25],
-    [distributionDelta(source.wordLength, draft.wordLength), 0.40],
-  ]);
-}
-
-function registerDistance(source, draft) {
-  const primaryDelta = source.primary?.value === draft.primary?.value ? 0 : 0.65;
-  return weightedMean([
-    [primaryDelta, 0.8],
-    [topItemDistance(source.scores, draft.scores), 0.2],
-  ]);
-}
-
-function discourseDistance(source, draft) {
-  const transitionDelta = rateMapDistance(source.transitionRates, draft.transitionRates);
-  const callbackDelta = Math.abs((source.sentenceCallbacks ?? 0) - (draft.sentenceCallbacks ?? 0));
-  return weightedMean([
-    [transitionDelta, 0.55],
-    [topItemDistance(source.transitionBigrams, draft.transitionBigrams), 0.25],
-    [topItemDistance(source.transitionTrigrams, draft.transitionTrigrams), 0.10],
-    [callbackDelta, 0.20],
-  ]);
-}
-
-function evidenceDistance(source, draft) {
-  return weightedMean([
-    [Math.abs((source.evidenceSentenceRate ?? 0) - (draft.evidenceSentenceRate ?? 0)), 0.30],
-    [Math.abs((source.claimSentenceRate ?? 0) - (draft.claimSentenceRate ?? 0)), 0.14],
-    [Math.max(0, (source.supportedClaimRate ?? 0) - (draft.supportedClaimRate ?? 0)), 0.20],
-    [Math.max(0, (draft.unsupportedClaimRate ?? 0) - (source.unsupportedClaimRate ?? 0)), 0.26],
-    [topItemDistance(source.evidenceTypes, draft.evidenceTypes), 0.20],
-  ]);
-}
-
-function shapeDistance(source, draft) {
-  return weightedMean([
-    [sequenceDistance(source.openingMoves, draft.openingMoves), 0.35],
-    [topItemDistance(source.openingMovePatterns, draft.openingMovePatterns), 0.25],
-    [topItemDistance(source.moveRates, draft.moveRates), 0.20],
-    [topItemDistance(source.moveBigrams ?? source.commonSequences, draft.moveBigrams ?? draft.commonSequences), 0.25],
-    [topItemDistance(source.moveTrigrams, draft.moveTrigrams), 0.15],
-  ]);
-}
-
-function distributionDelta(source, draft) {
-  if (!source || !draft) {
-    return 0;
-  }
-  return weightedMean([
-    [relativeDelta(source.median, draft.median), 0.45],
-    [relativeDelta(source.p25, draft.p25), 0.20],
-    [relativeDelta(source.p75, draft.p75), 0.20],
-    [relativeDelta(source.mean, draft.mean), 0.15],
-  ]);
-}
-
-function punctuationDistance(source = {}, draft = {}) {
-  return rateMapDistance(source, draft);
-}
-
-function rateMapDistance(source = {}, draft = {}) {
-  const keys = Array.from(new Set([...Object.keys(source), ...Object.keys(draft)]));
-  if (keys.length === 0) {
-    return 0;
-  }
-  return keys.reduce((sum, key) => sum + Math.abs((source[key] ?? 0) - (draft[key] ?? 0)), 0) / keys.length;
-}
-
-function topItemDistance(sourceItems, draftItems) {
-  if (!Array.isArray(sourceItems) || !Array.isArray(draftItems)) {
-    return null;
-  }
-  if (sourceItems.length === 0 && draftItems.length === 0) {
-    return null;
-  }
-  const source = normalizedItemMap(sourceItems);
-  const draft = normalizedItemMap(draftItems);
-  const delta = rateMapDistance(source, draft);
-  const cosine = cosineDistance(source, draft);
-  const jsd = jensenShannonDistance(source, draft);
-  return weightedMean([
-    [delta, 0.30],
-    [cosine, 0.45],
-    [jsd, 0.25],
-  ]);
-}
-
-function normalizedItemMap(items) {
-  const weightedItems = items.map((item) => ({
-    value: item.value,
-    weight: item.count ?? item.score ?? 0,
-  }));
-  const total = weightedItems.reduce((sum, item) => sum + item.weight, 0);
-  return Object.fromEntries(weightedItems.map((item) => [item.value, item.weight / Math.max(1, total)]));
-}
-
-function cosineDistance(left, right) {
-  const keys = Array.from(new Set([...Object.keys(left), ...Object.keys(right)]));
-  if (keys.length === 0) {
-    return 0;
-  }
-  let dot = 0;
-  let leftNorm = 0;
-  let rightNorm = 0;
-  for (const key of keys) {
-    const leftValue = left[key] ?? 0;
-    const rightValue = right[key] ?? 0;
-    dot += leftValue * rightValue;
-    leftNorm += leftValue ** 2;
-    rightNorm += rightValue ** 2;
-  }
-  if (leftNorm === 0 && rightNorm === 0) {
-    return 0;
-  }
-  if (leftNorm === 0 || rightNorm === 0) {
-    return 1;
-  }
-  return Math.max(0, Math.min(1, 1 - dot / (Math.sqrt(leftNorm) * Math.sqrt(rightNorm))));
-}
-
-function jensenShannonDistance(left, right) {
-  const keys = Array.from(new Set([...Object.keys(left), ...Object.keys(right)]));
-  if (keys.length === 0) {
-    return 0;
-  }
-  const midpoint = {};
-  for (const key of keys) {
-    midpoint[key] = ((left[key] ?? 0) + (right[key] ?? 0)) / 2;
-  }
-  return Math.sqrt((klDivergence(left, midpoint, keys) + klDivergence(right, midpoint, keys)) / 2);
-}
-
-function klDivergence(source, target, keys) {
-  let sum = 0;
-  for (const key of keys) {
-    const sourceValue = source[key] ?? 0;
-    const targetValue = target[key] ?? 0;
-    if (sourceValue > 0 && targetValue > 0) {
-      sum += sourceValue * Math.log2(sourceValue / targetValue);
-    }
-  }
-  return sum;
-}
-
-function sequenceDistance(source = [], draft = []) {
-  if (source.length === 0 && draft.length === 0) {
-    return 0;
-  }
-  if (source.length === 0 || draft.length === 0) {
-    return 1;
-  }
-  const limit = Math.min(source.length, draft.length);
-  let matches = 0;
-  for (let index = 0; index < limit; index += 1) {
-    if (source[index] === draft[index]) {
-      matches += 1;
-    } else if (source.includes(draft[index]) || draft.includes(source[index])) {
-      matches += 0.5;
-    }
-  }
-  return 1 - matches / limit;
-}
-
-function relativeDelta(sourceValue, draftValue) {
-  return Math.abs((sourceValue ?? 0) - (draftValue ?? 0)) / Math.max(1, sourceValue ?? 0);
-}
-
-function weightedMean(weightedValues) {
-  const usableValues = weightedValues.filter(([value, weight]) => Number.isFinite(value) && weight > 0);
-  const totalWeight = usableValues.reduce((sum, [, weight]) => sum + weight, 0);
-  if (totalWeight === 0) {
-    return 0;
-  }
-  return round(usableValues.reduce((sum, [value, weight]) => sum + value * weight, 0) / totalWeight, 3);
-}
-
-function stabilityFromObservationCount(observations) {
-  if (observations >= 5) {
-    return 0.85;
-  }
-  if (observations >= 3) {
-    return 0.7;
-  }
-  if (observations >= 2) {
-    return 0.6;
-  }
-  return 0.45;
-}
+import { clampScore, round } from "./text-utils.js";
+
+export const STYLOMETRIC_REFERENCES = [
+  "Burrows Delta (Burrows, 2002)",
+  "Cosine Delta (Smith & Aldridge, 2011)",
+  "Function-word stylometry (Kestemont, 2014)",
+  "Authorship-attribution feature families (Stamatatos, 2009)",
+  "Cohesion and discourse measures inspired by Coh-Metrix (Graesser et al., 2004)",
+];
+
+const DEFAULT_THRESHOLDS = {
+  rhythm: 0.36,
+  lexical: 0.32,
+  register: 0.45,
+  discourse: 0.28,
+  rhetoricalShape: 0.42,
+  evidence: 0.30,
+  structure: 0.42,
+};
+
+const FAMILY_WEIGHTS = {
+  rhythm: 0.75,
+  lexical: 0.85,
+  register: 0.50,
+  discourse: 0.70,
+  rhetoricalShape: 0.70,
+  evidence: 0.85,
+  structure: 0.65,
+};
+
+export function defaultStyleThresholds() {
+  return Object.fromEntries(Object.entries(DEFAULT_THRESHOLDS).map(([family, threshold]) => [
+    family,
+    { threshold, observations: 0, stability: 0.45 },
+  ]));
+}
+
+export function familyWeight(family) {
+  return FAMILY_WEIGHTS[family] ?? 0.6;
+}
+
+export function distanceByFamily(family, sourceFeatures, draftFeatures) {
+  if (family === "rhythm") {
+    return rhythmDistance(sourceFeatures, draftFeatures);
+  }
+  if (family === "lexical") {
+    return lexicalDistance(sourceFeatures, draftFeatures);
+  }
+  if (family === "register") {
+    return registerDistance(sourceFeatures, draftFeatures);
+  }
+  if (family === "discourse") {
+    return discourseDistance(sourceFeatures, draftFeatures);
+  }
+  if (family === "rhetoricalShape") {
+    return shapeDistance(sourceFeatures, draftFeatures);
+  }
+  if (family === "evidence") {
+    return evidenceDistance(sourceFeatures, draftFeatures);
+  }
+  if (family === "structure") {
+    return structureDistance(sourceFeatures, draftFeatures);
+  }
+  return 0;
+}
+
+export function familyScoreFromDistance(distance, threshold) {
+  const ratio = distance / Math.max(0.01, threshold);
+  return clampScore(100 / (1 + Math.exp(3 * (ratio - 1.35))));
+}
+
+export function calibratedFamilyDrift(distance, threshold) {
+  return round(Math.max(0, distance - threshold) / Math.max(0.01, threshold), 3);
+}
+
+export function percentile(values, ratio) {
+  const sorted = values.filter((value) => Number.isFinite(value)).sort((left, right) => left - right);
+  if (sorted.length === 0) {
+    return 0;
+  }
+  const index = Math.min(sorted.length - 1, Math.max(0, Math.ceil((sorted.length - 1) * ratio)));
+  return sorted[index];
+}
+
+export function familyDiagnosticsFor(sourceProfile, draftProfile) {
+  const thresholds = sourceProfile.calibration?.styleThresholds?.families ?? defaultStyleThresholds();
+  return Object.fromEntries(Object.keys(sourceProfile.families).map((family) => {
+    const distance = distanceByFamily(
+      family,
+      sourceProfile.families[family].features,
+      draftProfile.families[family].features,
+    );
+    const thresholdData = thresholds[family] ?? defaultStyleThresholds()[family] ?? { threshold: 0.4, stability: 0.45 };
+    const threshold = thresholdData.threshold ?? 0.4;
+    return [family, {
+      distance,
+      threshold,
+      stability: thresholdData.stability ?? stabilityFromObservationCount(thresholdData.observations ?? 0),
+      drift: calibratedFamilyDrift(distance, threshold),
+      score: familyScoreFromDistance(distance, threshold),
+    }];
+  }));
+}
+
+export function styleDistanceFromDiagnostics(familyDiagnostics) {
+  const entries = Object.entries(familyDiagnostics);
+  const weighted = entries.map(([family, item]) => [
+    100 - item.score,
+    familyWeight(family) * Math.max(0.35, item.stability ?? 0.45),
+  ]);
+  return Math.round(weightedMean(weighted));
+}
+
+export function stabilityFromDistances(values) {
+  const finite = values.filter((value) => Number.isFinite(value));
+  if (finite.length < 2) {
+    return stabilityFromObservationCount(finite.length);
+  }
+  const mean = finite.reduce((sum, value) => sum + value, 0) / finite.length;
+  const variance = finite.reduce((sum, value) => sum + (value - mean) ** 2, 0) / finite.length;
+  const coefficient = Math.sqrt(variance) / Math.max(0.01, mean);
+  return round(Math.max(0.35, Math.min(1, 1 - coefficient)), 3);
+}
+
+function rhythmDistance(source, draft) {
+  return weightedMean([
+    [distributionDelta(source.sentenceWords, draft.sentenceWords), 0.40],
+    [distributionDelta(source.paragraphWords, draft.paragraphWords), 0.32],
+    [distributionDelta(source.paragraphSentences, draft.paragraphSentences), 0.16],
+    [Math.abs((source.listDensity ?? 0) - (draft.listDensity ?? 0)), 0.06],
+    [Math.abs((source.quoteDensity ?? 0) - (draft.quoteDensity ?? 0)), 0.06],
+  ]);
+}
+
+function lexicalDistance(source, draft) {
+  return weightedMean([
+    [topItemDistance(source.functionWords, draft.functionWords), 1.00],
+    [topItemDistance(source.functionWordBigrams, draft.functionWordBigrams), 0.75],
+    [topItemDistance(source.maskedCharacterFourgrams, draft.maskedCharacterFourgrams), 1.00],
+    [topItemDistance(source.characterTrigrams, draft.characterTrigrams), 0.45],
+    [topItemDistance(source.sentenceInitialTokens, draft.sentenceInitialTokens), 0.35],
+    [topItemDistance(source.sentenceFinalTokens, draft.sentenceFinalTokens), 0.35],
+    [topItemDistance(source.punctuationNgrams, draft.punctuationNgrams), 0.45],
+    [punctuationDistance(source.punctuation, draft.punctuation), 0.85],
+    [Math.abs((source.vocabularyRichness?.contentTypeTokenRatio ?? 0) - (draft.vocabularyRichness?.contentTypeTokenRatio ?? 0)), 0.25],
+    [distributionDelta(source.wordLength, draft.wordLength), 0.40],
+  ]);
+}
+
+function registerDistance(source, draft) {
+  const primaryDelta = source.primary?.value === draft.primary?.value ? 0 : 0.65;
+  return weightedMean([
+    [primaryDelta, 0.8],
+    [topItemDistance(source.scores, draft.scores), 0.2],
+  ]);
+}
+
+function discourseDistance(source, draft) {
+  const transitionDelta = rateMapDistance(source.transitionRates, draft.transitionRates);
+  const callbackDelta = Math.abs((source.sentenceCallbacks ?? 0) - (draft.sentenceCallbacks ?? 0));
+  return weightedMean([
+    [transitionDelta, 0.55],
+    [topItemDistance(source.transitionBigrams, draft.transitionBigrams), 0.25],
+    [topItemDistance(source.transitionTrigrams, draft.transitionTrigrams), 0.10],
+    [callbackDelta, 0.20],
+  ]);
+}
+
+function evidenceDistance(source, draft) {
+  return weightedMean([
+    [Math.abs((source.evidenceSentenceRate ?? 0) - (draft.evidenceSentenceRate ?? 0)), 0.30],
+    [Math.abs((source.claimSentenceRate ?? 0) - (draft.claimSentenceRate ?? 0)), 0.14],
+    [Math.max(0, (source.supportedClaimRate ?? 0) - (draft.supportedClaimRate ?? 0)), 0.20],
+    [Math.max(0, (draft.unsupportedClaimRate ?? 0) - (source.unsupportedClaimRate ?? 0)), 0.26],
+    [topItemDistance(source.evidenceTypes, draft.evidenceTypes), 0.20],
+  ]);
+}
+
+function shapeDistance(source, draft) {
+  return weightedMean([
+    [sequenceDistance(source.openingMoves, draft.openingMoves), 0.35],
+    [topItemDistance(source.openingMovePatterns, draft.openingMovePatterns), 0.25],
+    [topItemDistance(source.moveRates, draft.moveRates), 0.20],
+    [topItemDistance(source.moveBigrams ?? source.commonSequences, draft.moveBigrams ?? draft.commonSequences), 0.25],
+    [topItemDistance(source.moveTrigrams, draft.moveTrigrams), 0.15],
+  ]);
+}
+
+function structureDistance(source, draft) {
+  return weightedMean([
+    [distributionDelta(source.sectionWords, draft.sectionWords), 0.35],
+    [distributionDelta(source.headingCount, draft.headingCount), 0.20],
+    [Math.abs((source.listDocumentRate ?? 0) - (draft.listDocumentRate ?? 0)), 0.18],
+    [Math.abs((source.quoteDocumentRate ?? 0) - (draft.quoteDocumentRate ?? 0)), 0.12],
+    [sequenceDistance(source.openingMoves, draft.openingMoves), 0.15],
+  ]);
+}
+
+function distributionDelta(source, draft) {
+  if (!source || !draft) {
+    return 0;
+  }
+  return weightedMean([
+    [relativeDelta(source.median, draft.median), 0.45],
+    [relativeDelta(source.p25, draft.p25), 0.20],
+    [relativeDelta(source.p75, draft.p75), 0.20],
+    [relativeDelta(source.mean, draft.mean), 0.15],
+  ]);
+}
+
+function punctuationDistance(source = {}, draft = {}) {
+  return rateMapDistance(source, draft);
+}
+
+function rateMapDistance(source = {}, draft = {}) {
+  const keys = Array.from(new Set([...Object.keys(source), ...Object.keys(draft)]));
+  if (keys.length === 0) {
+    return 0;
+  }
+  return keys.reduce((sum, key) => sum + Math.abs((source[key] ?? 0) - (draft[key] ?? 0)), 0) / keys.length;
+}
+
+function topItemDistance(sourceItems, draftItems) {
+  if (!Array.isArray(sourceItems) || !Array.isArray(draftItems)) {
+    return null;
+  }
+  if (sourceItems.length === 0 && draftItems.length === 0) {
+    return null;
+  }
+  const source = normalizedItemMap(sourceItems);
+  const draft = normalizedItemMap(draftItems);
+  const delta = rateMapDistance(source, draft);
+  const cosine = cosineDistance(source, draft);
+  const jsd = jensenShannonDistance(source, draft);
+  return weightedMean([
+    [delta, 0.30],
+    [cosine, 0.45],
+    [jsd, 0.25],
+  ]);
+}
+
+function normalizedItemMap(items) {
+  const weightedItems = items.map((item) => ({
+    value: item.value,
+    weight: item.count ?? item.score ?? 0,
+  }));
+  const total = weightedItems.reduce((sum, item) => sum + item.weight, 0);
+  return Object.fromEntries(weightedItems.map((item) => [item.value, item.weight / Math.max(1, total)]));
+}
+
+function cosineDistance(left, right) {
+  const keys = Array.from(new Set([...Object.keys(left), ...Object.keys(right)]));
+  if (keys.length === 0) {
+    return 0;
+  }
+  let dot = 0;
+  let leftNorm = 0;
+  let rightNorm = 0;
+  for (const key of keys) {
+    const leftValue = left[key] ?? 0;
+    const rightValue = right[key] ?? 0;
+    dot += leftValue * rightValue;
+    leftNorm += leftValue ** 2;
+    rightNorm += rightValue ** 2;
+  }
+  if (leftNorm === 0 && rightNorm === 0) {
+    return 0;
+  }
+  if (leftNorm === 0 || rightNorm === 0) {
+    return 1;
+  }
+  return Math.max(0, Math.min(1, 1 - dot / (Math.sqrt(leftNorm) * Math.sqrt(rightNorm))));
+}
+
+function jensenShannonDistance(left, right) {
+  const keys = Array.from(new Set([...Object.keys(left), ...Object.keys(right)]));
+  if (keys.length === 0) {
+    return 0;
+  }
+  const midpoint = {};
+  for (const key of keys) {
+    midpoint[key] = ((left[key] ?? 0) + (right[key] ?? 0)) / 2;
+  }
+  return Math.sqrt((klDivergence(left, midpoint, keys) + klDivergence(right, midpoint, keys)) / 2);
+}
+
+function klDivergence(source, target, keys) {
+  let sum = 0;
+  for (const key of keys) {
+    const sourceValue = source[key] ?? 0;
+    const targetValue = target[key] ?? 0;
+    if (sourceValue > 0 && targetValue > 0) {
+      sum += sourceValue * Math.log2(sourceValue / targetValue);
+    }
+  }
+  return sum;
+}
+
+function sequenceDistance(source = [], draft = []) {
+  if (source.length === 0 && draft.length === 0) {
+    return 0;
+  }
+  if (source.length === 0 || draft.length === 0) {
+    return 1;
+  }
+  const limit = Math.min(source.length, draft.length);
+  let matches = 0;
+  for (let index = 0; index < limit; index += 1) {
+    if (source[index] === draft[index]) {
+      matches += 1;
+    } else if (source.includes(draft[index]) || draft.includes(source[index])) {
+      matches += 0.5;
+    }
+  }
+  return 1 - matches / limit;
+}
+
+function relativeDelta(sourceValue, draftValue) {
+  return Math.abs((sourceValue ?? 0) - (draftValue ?? 0)) / Math.max(1, sourceValue ?? 0);
+}
+
+function weightedMean(weightedValues) {
+  const usableValues = weightedValues.filter(([value, weight]) => Number.isFinite(value) && weight > 0);
+  const totalWeight = usableValues.reduce((sum, [, weight]) => sum + weight, 0);
+  if (totalWeight === 0) {
+    return 0;
+  }
+  return round(usableValues.reduce((sum, [value, weight]) => sum + value * weight, 0) / totalWeight, 3);
+}
+
+function stabilityFromObservationCount(observations) {
+  if (observations >= 5) {
+    return 0.85;
+  }
+  if (observations >= 3) {
+    return 0.7;
+  }
+  if (observations >= 2) {
+    return 0.6;
+  }
+  return 0.45;
+}