@lucern/confidence 0.3.0-alpha.0 → 0.3.0-alpha.10

package/dist/v1/operations/lucern.js

@@ -1,8 +1,10 @@
+import { z } from 'zod';
+
 // src/v1/operations/subjectiveLogic/index.ts
-function opinion(belief, disbelief, uncertainty, baseRate = 0.5) {
-  const b = Math.max(0, Math.min(1, belief));
-  const d = Math.max(0, Math.min(1, disbelief));
-  const u = Math.max(0, Math.min(1, uncertainty));
+function mkOpinion(belief, disbelief, uncertainty, baseRate) {
+  const b = Number.isFinite(belief) ? Math.max(0, belief) : 0;
+  const d = Number.isFinite(disbelief) ? Math.max(0, disbelief) : 0;
+  const u = Number.isFinite(uncertainty) ? Math.max(0, uncertainty) : 0;
   const a = Math.max(0, Math.min(1, baseRate));
   const sum = b + d + u;
   if (sum === 0) {
@@ -15,8 +17,9 @@ function opinion(belief, disbelief, uncertainty, baseRate = 0.5) {
     a
   };
 }
-function vacuous(baseRate = 0.5) {
-  return { b: 0, d: 0, u: 1, a: baseRate };
+var opinion = mkOpinion;
+function vacuous(baseRate) {
+  return mkOpinion(0, 0, 1, baseRate);
 }
 function project(o) {
   return o.b + o.a * o.u;
@@ -172,7 +175,7 @@ function conditionalDeduction(opinionA, ifTrue, ifFalse, fallbackBaseRate) {
   );
 }
 function negate(o) {
-  return { b: o.d, d: o.b, u: o.u, a: 1 - o.a };
+  return mkOpinion(o.d, o.b, o.u, 1 - o.a);
 }
 function constraintFusion(left, right, mode = "pressure") {
   if (mode === "redistribute") {
@@ -239,6 +242,15 @@ function informationGain(o) {
 function finiteNumber(value) {
   return typeof value === "number" && Number.isFinite(value) ? value : void 0;
 }
+function requiredOpinionNumber(label, ...values) {
+  for (const value of values) {
+    const numberValue = finiteNumber(value);
+    if (numberValue !== void 0) {
+      return numberValue;
+    }
+  }
+  throw new Error(`Opinion record is missing required ${label}.`);
+}
 function clamp01(value) {
   return Math.max(0, Math.min(1, value));
 }
@@ -253,34 +265,56 @@ function toStoredOpinionFields(opinion2) {
     baseRate: opinion2.a
   };
 }
-function readOpinionFromRecord(source, fallback = {}) {
+function readOpinionFromRecord(source) {
   const record = source && typeof source === "object" ? source : {};
-  return {
-    b: finiteNumber(record.b) ?? finiteNumber(record.belief) ?? finiteNumber(record.slBelief) ?? finiteNumber(record.opinion_b) ?? fallback.b ?? 0,
-    d: finiteNumber(record.d) ?? finiteNumber(record.disbelief) ?? finiteNumber(record.slDisbelief) ?? finiteNumber(record.opinion_d) ?? fallback.d ?? 0,
-    u: finiteNumber(record.u) ?? finiteNumber(record.uncertainty) ?? finiteNumber(record.slUncertainty) ?? finiteNumber(record.opinion_u) ?? fallback.u ?? 1,
-    a: finiteNumber(record.a) ?? finiteNumber(record.baseRate) ?? finiteNumber(record.slBaseRate) ?? finiteNumber(record.opinion_a) ?? fallback.a ?? 0.5
-  };
+  return mkOpinion(
+    requiredOpinionNumber(
+      "belief",
+      record.b,
+      record.belief,
+      record.slBelief,
+      record.opinion_b
+    ),
+    requiredOpinionNumber(
+      "disbelief",
+      record.d,
+      record.disbelief,
+      record.slDisbelief,
+      record.opinion_d
+    ),
+    requiredOpinionNumber(
+      "uncertainty",
+      record.u,
+      record.uncertainty,
+      record.slUncertainty,
+      record.opinion_u
+    ),
+    requiredOpinionNumber(
+      "baseRate",
+      record.a,
+      record.baseRate,
+      record.slBaseRate,
+      record.opinion_a
+    )
+  );
 }
 function opinionFromScalar(value, mode, options) {
   const clampedValue = clamp01(value);
-  const baseRate = clamp01(options?.baseRate ?? 0.5);
+  const baseRate = options?.baseRate === void 0 ? void 0 : clamp01(options.baseRate);
   switch (mode) {
     case "base_rate":
-      return {
-        b: 0,
-        d: 0,
-        u: 1,
-        a: clampedValue
-      };
+      return mkOpinion(0, 0, 1, clampedValue);
     case "dogmatic":
-      return {
-        b: clampedValue,
-        d: 1 - clampedValue,
-        u: 0,
-        a: baseRate
-      };
+      if (baseRate === void 0) {
+        throw new Error('opinionFromScalar(value, "dogmatic") requires options.baseRate.');
+      }
+      return mkOpinion(clampedValue, 1 - clampedValue, 0, baseRate);
     case "projected_with_u": {
+      if (baseRate === void 0) {
+        throw new Error(
+          'opinionFromScalar(value, "projected_with_u") requires options.baseRate.'
+        );
+      }
       const uncertainty = options?.uncertainty;
       if (uncertainty === void 0) {
         throw new Error(
@@ -289,22 +323,57 @@ function opinionFromScalar(value, mode, options) {
       }
       const clampedUncertainty = clamp01(uncertainty);
       const evidenceWeight = 1 - clampedUncertainty;
-      return {
-        b: clampedValue * evidenceWeight,
-        d: (1 - clampedValue) * evidenceWeight,
-        u: clampedUncertainty,
-        a: baseRate
-      };
+      return mkOpinion(
+        clampedValue * evidenceWeight,
+        (1 - clampedValue) * evidenceWeight,
+        clampedUncertainty,
+        baseRate
+      );
     }
   }
   throw new Error(`Unsupported opinionFromScalar mode: ${mode}`);
 }
-function toDogmaticOpinion(confidence, baseRate = 0.5) {
+function toDogmaticOpinion(confidence, baseRate) {
   return opinionFromScalar(confidence, "dogmatic", { baseRate });
 }
 function hasProjectedOpinionChanged(current, next, tolerance = 0.01) {
   return Math.abs(confidenceFromOpinion(next) - confidenceFromOpinion(current)) >= tolerance;
 }
+var SL_EPSILON = 1e-9;
+z.object({
+  b: z.number(),
+  d: z.number(),
+  u: z.number(),
+  a: z.number()
+}).refine((o) => Math.abs(o.b + o.d + o.u - 1) < SL_EPSILON, {
+  message: "SL invariant b+d+u=1 violated"
+});
+function fromStorage(fields) {
+  const sum = fields.belief + fields.disbelief + fields.uncertainty;
+  const opinion2 = mkOpinion(
+    fields.belief,
+    fields.disbelief,
+    fields.uncertainty,
+    fields.baseRate
+  );
+  if (Math.abs(sum - 1) < SL_EPSILON) {
+    return { ok: true, opinion: opinion2 };
+  }
+  return {
+    ok: false,
+    opinion: opinion2,
+    repairNeeded: true,
+    reason: `Stored fields sum to ${sum.toFixed(6)}, not 1; normalized on read`
+  };
+}
+function toStorage(opinion2) {
+  return {
+    belief: opinion2.b,
+    disbelief: opinion2.d,
+    uncertainty: opinion2.u,
+    baseRate: opinion2.a
+  };
+}
 function toEpochMs(value) {
   if (typeof value === "number" && Number.isFinite(value)) {
     return value;
@@ -336,7 +405,10 @@ function temporalDecay(sourceOpinion, now, decayParams) {
     return { ...sourceOpinion };
   }
   const retainedEvidenceWeight = Math.pow(0.5, ageMs / halfLifeMs);
-  return trustDiscount(sourceOpinion, retainedEvidenceWeight);
+  return trustDiscount(
+    mkOpinion(sourceOpinion.b, sourceOpinion.d, sourceOpinion.u, sourceOpinion.a),
+    retainedEvidenceWeight
+  );
 }
 
 // src/v1/operations/contradiction/detectTupleContradiction.ts
@@ -373,7 +445,14 @@ function evaluateTupleContradictionTransition(args) {
 
 // src/v1/operations/dynamics/cascade.ts
 function dampedDependencyOpinion(dependencyOpinion, beliefOpinion, mode = "continuous", threshold = 0.3) {
-  const dependencyProjection = project(dependencyOpinion);
+  const dependencyProjection = project(
+    mkOpinion(
+      dependencyOpinion.b,
+      dependencyOpinion.d,
+      dependencyOpinion.u,
+      dependencyOpinion.a
+    )
+  );
   if (mode === "threshold") {
     if (dependencyProjection < threshold) {
       return opinion(
@@ -398,40 +477,49 @@ function dampedDependencyCascade(dependencyOpinion, beliefOpinion, mode = "conti
     opinion: dampedDependencyOpinion(dependencyOpinion, beliefOpinion, mode),
     operator: "dependency_cascade",
     rationale: `Damped dependency cascade (${mode}): prerequisite at ${project(
-      dependencyOpinion
+      mkOpinion(
+        dependencyOpinion.b,
+        dependencyOpinion.d,
+        dependencyOpinion.u,
+        dependencyOpinion.a
+      )
     ).toFixed(2)}`
   };
 }
 
 // src/v1/operations/dynamics/defeat.ts
 function applyNegativeSupport(source, target, weight, metadata = {}) {
+  const sourceOpinion = mkOpinion(source.b, source.d, source.u, source.a);
+  const targetOpinion = mkOpinion(target.b, target.d, target.u, target.a);
   if (metadata.constraint === "xor") {
     const result = constraintFusion(
-      source,
-      target,
+      sourceOpinion,
+      targetOpinion,
       metadata.normalization ?? "pressure"
     );
     return {
       opinion: result.o2,
       operator: "constraint_fusion",
-      rationale: `XOR constraint: source belief at ${project(source).toFixed(
-        2
-      )} pressures target`
+      rationale: `XOR constraint: source belief at ${project(
+        sourceOpinion
+      ).toFixed(2)} pressures target`
     };
   }
-  const discounted = trustDiscount(negate(source), Math.abs(weight));
+  const discounted = trustDiscount(negate(sourceOpinion), Math.abs(weight));
   return {
-    opinion: cumulativeFusion(target, discounted),
+    opinion: cumulativeFusion(targetOpinion, discounted),
     operator: "cumulative_fusion",
     rationale: `Contradicting evidence (weight=${weight.toFixed(
       2
-    )}) from source at ${project(source).toFixed(2)}`
+    )}) from source at ${project(sourceOpinion).toFixed(2)}`
   };
 }
 function applyNegativeEvidence(source, target, weight) {
-  const discounted = trustDiscount(negate(source), Math.abs(weight));
+  const sourceOpinion = mkOpinion(source.b, source.d, source.u, source.a);
+  const targetOpinion = mkOpinion(target.b, target.d, target.u, target.a);
+  const discounted = trustDiscount(negate(sourceOpinion), Math.abs(weight));
   return {
-    opinion: cumulativeFusion(target, discounted),
+    opinion: cumulativeFusion(targetOpinion, discounted),
     operator: "cumulative_fusion",
     rationale: `Contradicting evidence (weight=${weight.toFixed(2)})`
   };
@@ -442,28 +530,32 @@ var EDGE_PROPAGATION_RULES = {
   supports: {
     direction: "outgoing",
     handler: (source, target, weight, metadata) => {
+      const sourceOpinion = mkOpinion(source.b, source.d, source.u, source.a);
+      const targetOpinion = mkOpinion(target.b, target.d, target.u, target.a);
       if (weight < 0) {
-        return applyNegativeSupport(source, target, weight, metadata);
+        return applyNegativeSupport(sourceOpinion, targetOpinion, weight, metadata);
       }
-      const discounted = trustDiscount(source, weight);
+      const discounted = trustDiscount(sourceOpinion, weight);
       return {
-        opinion: cumulativeFusion(target, discounted),
+        opinion: cumulativeFusion(targetOpinion, discounted),
         operator: "cumulative_fusion",
         rationale: `Supporting evidence (weight=${weight.toFixed(
           2
-        )}) from source at ${project(source).toFixed(2)}`
+        )}) from source at ${project(sourceOpinion).toFixed(2)}`
       };
     }
   },
   informs: {
     direction: "outgoing",
     handler: (source, target, weight) => {
+      const sourceOpinion = mkOpinion(source.b, source.d, source.u, source.a);
+      const targetOpinion = mkOpinion(target.b, target.d, target.u, target.a);
       if (weight < 0) {
-        return applyNegativeEvidence(source, target, weight);
+        return applyNegativeEvidence(sourceOpinion, targetOpinion, weight);
       }
-      const discounted = trustDiscount(source, Math.abs(weight));
+      const discounted = trustDiscount(sourceOpinion, Math.abs(weight));
       return {
-        opinion: cumulativeFusion(target, discounted),
+        opinion: cumulativeFusion(targetOpinion, discounted),
         operator: "cumulative_fusion",
         rationale: `Supporting evidence (weight=${weight.toFixed(2)})`
       };
@@ -472,23 +564,35 @@ var EDGE_PROPAGATION_RULES = {
   depends_on: {
     direction: "incoming",
     handler: (source, target, _weight, metadata) => {
+      const sourceOpinion = mkOpinion(source.b, source.d, source.u, source.a);
+      const targetOpinion = mkOpinion(target.b, target.d, target.u, target.a);
       if (metadata.conditionalA && metadata.conditionalNotA) {
         return {
           opinion: conditionalDeduction(
-            source,
-            metadata.conditionalA,
-            metadata.conditionalNotA,
-            target.a
+            sourceOpinion,
+            mkOpinion(
+              metadata.conditionalA.b,
+              metadata.conditionalA.d,
+              metadata.conditionalA.u,
+              metadata.conditionalA.a
+            ),
+            mkOpinion(
+              metadata.conditionalNotA.b,
+              metadata.conditionalNotA.d,
+              metadata.conditionalNotA.u,
+              metadata.conditionalNotA.a
+            ),
+            targetOpinion.a
           ),
           operator: "conditional_deduction",
           rationale: `Conditional deduction: prerequisite at ${project(
-            source
+            sourceOpinion
           ).toFixed(2)}`
         };
       }
       return dampedDependencyCascade(
-        source,
-        target,
+        sourceOpinion,
+        targetOpinion,
         metadata.propagation ?? "continuous"
       );
     }
@@ -580,10 +684,6 @@ function normalizeBaseRateVector(baseRate, size) {
   if (size === 0) {
     return [];
   }
-  const fallback = Array.from({ length: size }, () => 1 / size);
-  if (!baseRate) {
-    return fallback;
-  }
   if (baseRate.length !== size) {
     throw new Error(
       `Base-rate vector length ${baseRate.length} must match evidence vector length ${size}.`
@@ -592,11 +692,11 @@ function normalizeBaseRateVector(baseRate, size) {
   const normalized = baseRate.map((value) => clampNonNegative(value));
   const total = normalized.reduce((sum, value) => sum + value, 0);
   if (total === 0) {
-    return fallback;
+    throw new Error("Base-rate vector must contain at least one positive value.");
   }
   return normalized.map((value) => value / total);
 }
-function opinionFromDirichlet(alpha, nonInformativeWeight = DEFAULT_NON_INFORMATIVE_WEIGHT, baseRate) {
+function opinionFromDirichlet(alpha, nonInformativeWeight, baseRate) {
   const evidence = alpha.map((value) => clampNonNegative(value));
   const safeWeight = normalizeNonInformativeWeight(nonInformativeWeight);
   const normalizedBaseRate = normalizeBaseRateVector(baseRate, evidence.length);
@@ -615,18 +715,18 @@ function opinionFromDirichlet(alpha, nonInformativeWeight = DEFAULT_NON_INFORMAT
     a: normalizedBaseRate
   };
 }
-function opinionFromBeta(alpha, beta, nonInformativeWeight = DEFAULT_NON_INFORMATIVE_WEIGHT, baseRate = 0.5) {
+function opinionFromBeta(alpha, beta, nonInformativeWeight, baseRate) {
   const dirichlet = opinionFromDirichlet(
     [alpha, beta],
     nonInformativeWeight,
     [clamp012(baseRate), 1 - clamp012(baseRate)]
   );
-  return {
-    b: dirichlet.b[0] ?? 0,
-    d: dirichlet.b[1] ?? 0,
-    u: dirichlet.u,
-    a: dirichlet.a[0] ?? clamp012(baseRate)
-  };
+  return mkOpinion(
+    dirichlet.b[0] ?? 0,
+    dirichlet.b[1] ?? 0,
+    dirichlet.u,
+    dirichlet.a[0] ?? clamp012(baseRate)
+  );
 }
 
 // src/v1/operations/dynamics/revision.ts
@@ -661,7 +761,7 @@ function reviseConfidenceOpinion(args) {
     priorEvidence.alpha + newEvidence.alpha,
     priorEvidence.beta + newEvidence.beta,
     args.nonInformativeWeight ?? DEFAULT_NON_INFORMATIVE_WEIGHT,
-    args.baseRate ?? 0.5
+    args.baseRate
   );
 }
 
@@ -928,6 +1028,9 @@ function generateContractId() {
   }
   return `contract-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
 }
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
 function deriveContractStatus(result, currentStatus) {
   if (currentStatus === "archived") {
     return currentStatus;
@@ -1069,18 +1172,17 @@ function pickFiniteNumber(config, keys) {
   return void 0;
 }
 function getEvaluatorInputRecord(inputData, nestedKey) {
-  if (!inputData || typeof inputData !== "object") {
+  if (!isRecord(inputData)) {
     return {};
   }
-  const root = inputData;
-  const nested = root[nestedKey];
-  if (nested && typeof nested === "object") {
+  const nested = inputData[nestedKey];
+  if (isRecord(nested)) {
     return nested;
   }
-  return root;
+  return inputData;
 }
 function parseEvidentialEvaluatorConfig(value) {
-  if (!value || typeof value !== "object") {
+  if (!isRecord(value)) {
     throw new Error(
       "Evidential contracts require condition.evaluatorConfig with metric/operator/threshold."
     );
@@ -1098,7 +1200,7 @@ function parseEvidentialEvaluatorConfig(value) {
   if (typeof threshold !== "number" || !Number.isFinite(threshold)) {
     throw new Error("Evidential contracts require a numeric threshold.");
   }
-  const actionParams = config.actionParams && typeof config.actionParams === "object" && config.actionParams !== null ? config.actionParams : void 0;
+  const actionParams = isRecord(config.actionParams) ? config.actionParams : void 0;
   return {
     metric,
     operator,
@@ -1147,7 +1249,7 @@ function buildEvidentialRationale(args) {
   return `${clause}; comparison ${args.comparisonSatisfied ? "passed" : "failed"}, resulting in ${args.result}.`;
 }
 function parseMetricCheckerConfig(value) {
-  if (!value || typeof value !== "object") {
+  if (!isRecord(value)) {
     throw new Error(
       "metric_checker requires condition.evaluatorConfig with observedValue/operator/threshold."
     );
@@ -1164,7 +1266,7 @@ function parseMetricCheckerConfig(value) {
   };
 }
 function parseReferenceCheckCounterConfig(value) {
-  if (!value || typeof value !== "object") {
+  if (!isRecord(value)) {
     throw new Error(
       "reference_check_counter requires condition.evaluatorConfig with tag/operator/threshold."
     );
@@ -1187,7 +1289,7 @@ function parseReferenceCheckCounterConfig(value) {
   };
 }
 function parseTemporalDeadlineConfig(value) {
-  if (!value || typeof value !== "object") {
+  if (!isRecord(value)) {
     return {};
   }
   const config = value;
@@ -1201,7 +1303,7 @@ function parseTemporalDeadlineConfig(value) {
   };
 }
 function parseMarketIndexComparatorConfig(value) {
-  if (!value || typeof value !== "object") {
+  if (!isRecord(value)) {
     throw new Error(
       "market_index_comparator requires condition.evaluatorConfig with subjectValue/benchmarkValue/operator/threshold."
     );
@@ -1228,6 +1330,8 @@ function parseMarketIndexComparatorConfig(value) {
 // src/v1/operations/lucern.ts
 var LUCERN_SPECIFIC_OPERATOR_NAMES = [
   "clamp01",
+  "fromStorage",
+  "toStorage",
   "toStoredOpinionFields",
   "readOpinionFromRecord",
   "opinionFromScalar",
@@ -1248,6 +1352,7 @@ var LUCERN_SPECIFIC_OPERATOR_NAMES = [
   "propagateAllEdges",
   "bayesianUpdate",
   "reviseConfidence",
+  "reviseConfidenceOpinion",
   "computeBaseDecay",
   "computeDeadlineUrgency",
   "computeEffectiveDecay",
@@ -1275,6 +1380,6 @@ var LUCERN_SPECIFIC_OPERATOR_NAMES = [
   "parseMarketIndexComparatorConfig"
 ];
 
-export { LUCERN_SPECIFIC_OPERATOR_NAMES, applyNegativeEvidence, applyNegativeSupport, areTensioned, bayesianUpdate, buildComparisonRationale, buildEvidentialRationale, clamp01, compareMetricValue, computeBaseDecay, computeDeadlineUrgency, computeEffectiveDecay, confidenceLevel, constraintFusion, createInheritedContractRecord, decay, deriveContractModulationPlan, deriveContractStatus, deriveVerificationTrigger, detectTupleContradiction, evaluateTupleContradictionTransition, evidenceBalance, getEvaluatorInputRecord, getPropagationTraversalSpecs, getRescoringSchedule, hasProjectedOpinionChanged, informationGain, isPropagationEdgeType, normalizeEvidentialAction, normalizeTupleContradictionPolicy, opinionFromScalar, parseComparisonOperator, parseEvidentialEvaluatorConfig, parseMarketIndexComparatorConfig, parseMetricCheckerConfig, parseNumericThreshold, parseReferenceCheckCounterConfig, parseTemporalDeadlineConfig, pickFiniteNumber, propagateAllEdges, propagateThroughEdge, readOpinionFromRecord, resolveComparisonResult, reviseConfidence, temporalDecay, toDogmaticOpinion, toStoredOpinionFields };
+export { LUCERN_SPECIFIC_OPERATOR_NAMES, applyNegativeEvidence, applyNegativeSupport, areTensioned, bayesianUpdate, buildComparisonRationale, buildEvidentialRationale, clamp01, compareMetricValue, computeBaseDecay, computeDeadlineUrgency, computeEffectiveDecay, confidenceLevel, constraintFusion, createInheritedContractRecord, decay, deriveContractModulationPlan, deriveContractStatus, deriveVerificationTrigger, detectTupleContradiction, evaluateTupleContradictionTransition, evidenceBalance, fromStorage, getEvaluatorInputRecord, getPropagationTraversalSpecs, getRescoringSchedule, hasProjectedOpinionChanged, informationGain, isPropagationEdgeType, normalizeEvidentialAction, normalizeTupleContradictionPolicy, opinionFromScalar, parseComparisonOperator, parseEvidentialEvaluatorConfig, parseMarketIndexComparatorConfig, parseMetricCheckerConfig, parseNumericThreshold, parseReferenceCheckCounterConfig, parseTemporalDeadlineConfig, pickFiniteNumber, propagateAllEdges, propagateThroughEdge, readOpinionFromRecord, resolveComparisonResult, reviseConfidence, reviseConfidenceOpinion, temporalDecay, toDogmaticOpinion, toStorage, toStoredOpinionFields };
 //# sourceMappingURL=lucern.js.map
 //# sourceMappingURL=lucern.js.map