@ngockhoale/ukit 3.0.2 → 3.0.4

package/src/core/experiments/deliberation.js

@@ -0,0 +1,321 @@
+/**
+ * deliberation.js (TASK-011 / M06.1)
+ *
+ * Read-only deliberation experiments — Arena (2–3 independent candidates +
+ * evidence-rubric judge), Swarm (≥3 independent read-only lanes), smart judge —
+ * behind `experiments.deliberation.enabled` (default false). Not wired into
+ * route-task; evaluated by fixtures (SPEC §5 FR-021, FR-023; §14 "M06 wiring").
+ *
+ * Disabled posture: activation predicates return `{activate:false}` and
+ * `runArena` returns `{status:'disabled'}` BEFORE any judge call — zero calls,
+ * zero prompt content.
+ *
+ * Judge contract: `judge({findings, rubric}) → verdict` where findings are
+ * frozen candidate descriptors `{candidateId, criterionScores?, violations?,
+ * evidence?}` and verdict is `{selected, rejected, uncertainty,
+ * requiredValidation}`. `selected`/`rejected[]` entries MUST carry `citations`
+ * drawn from candidate evidence — a majority-only verdict is rejected. Hard
+ * rubric constraints (`rubric.hardConstraints`) are floors: a verdict that
+ * selects a violator or declares `waivedConstraints` is rejected. `smartJudge`
+ * is the built-in deterministic judge implementing the same contract.
+ */
+
+const MIN_ARENA_CANDIDATES = 2;
+const MAX_ARENA_CANDIDATES = 3;
+const MIN_SWARM_LANES = 3;
+
+function deliberationEnabled(config) {
+  return config?.experiments?.deliberation?.enabled === true;
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function candidateIdOf(entry) {
+  return entry?.candidateId ?? entry?.id ?? null;
+}
+
+function citationsOf(entry) {
+  return Array.isArray(entry?.citations) ? entry.citations : [];
+}
+
+/**
+ * Arena activation predicate. Fires only when the route carries ≥2 materially
+ * different viable alternatives AND budget allows; suppressed on established
+ * precedent, reversible changes, or cosmetic-only alternatives.
+ *
+ * @param {object} route — route summary fields: `alternatives[]`
+ *   ({id, viable, materiallyDifferent}), `budget.callsRemaining`,
+ *   `precedent`, `reversible`.
+ * @param {object} [config] — runtime config; absent/disabled → suppress.
+ * @returns {{activate: boolean, reasons: string[]}}
+ */
+export function evaluateArenaActivation(route = null, config = null) {
+  if (!deliberationEnabled(config)) {
+    return { activate: false, reasons: ['experiment-disabled'] };
+  }
+  const reasons = [];
+  if (route?.precedent) {
+    reasons.push('established-precedent');
+  }
+  if (route?.reversible === true) {
+    reasons.push('reversible-change');
+  }
+  const alternatives = Array.isArray(route?.alternatives) ? route.alternatives : [];
+  const material = alternatives.filter(
+    (alt) => alt?.viable === true && alt?.materiallyDifferent === true,
+  );
+  if (material.length < MIN_ARENA_CANDIDATES) {
+    reasons.push('insufficient-material-alternatives');
+  }
+  const callsRemaining = route?.budget?.callsRemaining;
+  const budgetAllows = !(typeof callsRemaining === 'number' && callsRemaining < 1);
+  if (!budgetAllows) {
+    reasons.push('budget-exhausted');
+  }
+  if (reasons.length > 0) {
+    return { activate: false, reasons };
+  }
+  return { activate: true, reasons: ['material-alternatives', 'budget-allows'] };
+}
+
+/**
+ * Swarm activation predicate. Fires only on ≥3 independent read-only lanes;
+ * any mutating or dependent lane suppresses the whole swarm.
+ *
+ * @param {object} route — route summary field `lanes[]`
+ *   ({id, readOnly, independent}).
+ * @param {object} [config]
+ * @returns {{activate: boolean, reasons: string[], lanes?: string[]}}
+ */
+export function evaluateSwarmActivation(route = null, config = null) {
+  if (!deliberationEnabled(config)) {
+    return { activate: false, reasons: ['experiment-disabled'], lanes: [] };
+  }
+  const lanes = Array.isArray(route?.lanes) ? route.lanes : [];
+  const reasons = [];
+  if (lanes.some((lane) => lane?.readOnly !== true)) {
+    reasons.push('lane-not-read-only');
+  }
+  const independent = lanes.filter(
+    (lane) => lane?.readOnly === true && lane?.independent === true,
+  );
+  if (independent.length < MIN_SWARM_LANES) {
+    reasons.push('insufficient-independent-lanes');
+  }
+  if (reasons.length > 0) {
+    return { activate: false, reasons, lanes: [] };
+  }
+  return {
+    activate: true,
+    reasons: ['independent-read-only-lanes'],
+    lanes: independent.map((lane) => lane.id),
+  };
+}
+
+/**
+ * Deterministic evidence-rubric judge. Scores each finding against weighted
+ * rubric criteria; findings violating a hard constraint are ineligible for
+ * selection regardless of score. Hard constraints are never waivable.
+ *
+ * @param {{findings: object[], rubric: {criteria?: {id, weight?}[],
+ *   hardConstraints?: string[]}}} input
+ * @returns {{selected: object|null, rejected: object[], uncertainty: string[],
+ *   requiredValidation: string[]}}
+ */
+export function smartJudge({ findings = [], rubric = {} } = {}) {
+  const criteria = Array.isArray(rubric?.criteria) ? rubric.criteria : [];
+  const hardConstraints = new Set(
+    Array.isArray(rubric?.hardConstraints) ? rubric.hardConstraints : [],
+  );
+  const scored = (Array.isArray(findings) ? findings : []).map((finding) => {
+    const scores = isPlainObject(finding?.criterionScores) ? finding.criterionScores : {};
+    const score = criteria.reduce(
+      (sum, criterion) => sum + Number(scores[criterion.id] ?? 0) * Number(criterion.weight ?? 1),
+      0,
+    );
+    const violations = (Array.isArray(finding?.violations) ? finding.violations : [])
+      .filter((id) => hardConstraints.has(id));
+    return { finding, score, violations };
+  });
+
+  const eligible = scored.filter((entry) => entry.violations.length === 0);
+  const rejected = [];
+  for (const entry of scored) {
+    if (entry.violations.length > 0) {
+      rejected.push({
+        candidateId: candidateIdOf(entry.finding),
+        reason: `hard-constraint:${entry.violations.join(',')}`,
+        citations: Array.isArray(entry.finding?.evidence) ? entry.finding.evidence : [],
+      });
+    }
+  }
+
+  eligible.sort((a, b) => b.score - a.score);
+  const top = eligible[0] ?? null;
+  const runnerUp = eligible[1] ?? null;
+  const uncertainty = [];
+  const requiredValidation = [];
+
+  let selected = null;
+  if (top) {
+    const citations = Array.isArray(top.finding?.evidence) ? top.finding.evidence : [];
+    if (citations.length === 0) {
+      uncertainty.push(`no-evidence:${candidateIdOf(top.finding)}`);
+      requiredValidation.push(`collect-evidence:${candidateIdOf(top.finding)}`);
+    } else {
+      selected = {
+        candidateId: candidateIdOf(top.finding),
+        score: top.score,
+        citations,
+      };
+    }
+  }
+  if (top && runnerUp && top.score - runnerUp.score <= 1) {
+    uncertainty.push(`close-call:${candidateIdOf(top.finding)}~${candidateIdOf(runnerUp.finding)}`);
+    requiredValidation.push(`validate-tiebreak:${candidateIdOf(top.finding)}`);
+  }
+  for (const entry of eligible) {
+    if (entry === top) continue;
+    rejected.push({
+      candidateId: candidateIdOf(entry.finding),
+      reason: 'lower-score',
+      citations: Array.isArray(entry.finding?.evidence) ? entry.finding.evidence : [],
+    });
+  }
+  if (!selected && !top) {
+    uncertainty.push('no-eligible-candidate');
+    requiredValidation.push('re-scope-candidates');
+  }
+
+  return { selected, rejected, uncertainty, requiredValidation };
+}
+
+/**
+ * Post-checks a judge verdict against the arena floors. Returns the list of
+ * rejection reasons (empty = verdict stands).
+ */
+function verdictViolations(verdict, candidates, rubric) {
+  const reasons = [];
+  const hardConstraints = new Set(
+    Array.isArray(rubric?.hardConstraints) ? rubric.hardConstraints : [],
+  );
+  const waived = Array.isArray(verdict?.waivedConstraints) ? verdict.waivedConstraints : [];
+  if (waived.some((id) => hardConstraints.has(id)) || waived.length > 0) {
+    reasons.push('hard-constraint-waived');
+  }
+  const selectedId = candidateIdOf(verdict?.selected);
+  if (selectedId !== null) {
+    const selectedFinding = candidates.find((c) => candidateIdOf(c) === selectedId);
+    const violations = Array.isArray(selectedFinding?.violations) ? selectedFinding.violations : [];
+    if (violations.some((id) => hardConstraints.has(id))) {
+      reasons.push('hard-constraint-violation-selected');
+    }
+  }
+  const entries = [verdict?.selected, ...(Array.isArray(verdict?.rejected) ? verdict.rejected : [])]
+    .filter(Boolean);
+  if (entries.some((entry) => citationsOf(entry).length === 0)) {
+    reasons.push('majority-only-verdict');
+  }
+  return reasons;
+}
+
+// Deep-frozen structural copy: plain objects and arrays are cloned and frozen
+// recursively so a judge cannot mutate nested state (violations, evidence)
+// to defeat the verdict post-check. Non-plain values pass through frozen-safe.
+function deepFreezeCopy(value) {
+  if (Array.isArray(value)) {
+    return Object.freeze(value.map(deepFreezeCopy));
+  }
+  if (isPlainObject(value)) {
+    const copy = {};
+    for (const [key, item] of Object.entries(value)) {
+      copy[key] = deepFreezeCopy(item);
+    }
+    return Object.freeze(copy);
+  }
+  return value;
+}
+
+/**
+ * Run a read-only arena over 2–3 frozen candidates with an evidence-rubric
+ * judge. The judge receives frozen copies — mutation attempts throw. The
+ * verdict is post-checked: hard-constraint waivers/violations and
+ * majority-only (citation-free) verdicts are rejected.
+ *
+ * @param {{candidates: object[], rubric: object, judge: Function,
+ *   config?: object}} input
+ * @returns {{status: 'ok'|'disabled'|'rejected', selected?: object|null,
+ *   rejected?: object[], uncertainty?: string[], requiredValidation?: string[],
+ *   reasons?: string[]}}
+ */
+export function runArena({ candidates = [], rubric = {}, judge = smartJudge, config = null } = {}) {
+  if (!deliberationEnabled(config)) {
+    return { status: 'disabled', selected: null, rejected: [], reasons: ['experiment-disabled'] };
+  }
+  const list = Array.isArray(candidates) ? candidates : [];
+  if (list.length < MIN_ARENA_CANDIDATES || list.length > MAX_ARENA_CANDIDATES) {
+    throw new TypeError(
+      `arena requires ${MIN_ARENA_CANDIDATES}–${MAX_ARENA_CANDIDATES} candidates.`,
+    );
+  }
+  if (typeof judge !== 'function') {
+    throw new TypeError('arena judge must be a function.');
+  }
+  // Read-only: the judge sees deep-frozen copies — mutation of any nested field
+  // (e.g. hiding a hard-constraint violation) throws in strict mode. A shallow
+  // freeze would leave nested arrays/objects mutable and defeat the post-check.
+  const findings = list.map((candidate) => deepFreezeCopy(candidate));
+  const verdict = judge({ findings, rubric }) ?? {};
+  const reasons = verdictViolations(verdict, findings, rubric);
+  if (reasons.length > 0) {
+    return { status: 'rejected', selected: null, rejected: [], reasons };
+  }
+  return {
+    status: 'ok',
+    selected: verdict.selected ?? null,
+    rejected: Array.isArray(verdict.rejected) ? verdict.rejected : [],
+    uncertainty: Array.isArray(verdict.uncertainty) ? verdict.uncertainty : [],
+    requiredValidation: Array.isArray(verdict.requiredValidation) ? verdict.requiredValidation : [],
+  };
+}
+
+const SCORECARD_VERDICTS = new Set(['net-gain', 'neutral', 'negative']);
+
+/**
+ * Emit a normalized experiment scorecard (FR-023). Promotion requires
+ * `verdict:'net-gain'` + maintainer review; `neutral|negative` keeps the
+ * experiment disabled.
+ *
+ * @param {{experimentId: string, taskClass: string, baselineRef: string,
+ *   deltas: {quality,rework,latency,calls}, verdict: string}} record
+ * @returns {object} scorecard with `promotionEligible` + `disposition`.
+ */
+export function emitExperimentScorecard(record = {}) {
+  if (!isPlainObject(record) || typeof record.experimentId !== 'string' || !record.experimentId) {
+    throw new TypeError('scorecard record.experimentId must be a non-empty string.');
+  }
+  if (!SCORECARD_VERDICTS.has(record.verdict)) {
+    throw new TypeError(`scorecard verdict must be one of ${[...SCORECARD_VERDICTS].join('|')}.`);
+  }
+  const deltas = isPlainObject(record.deltas) ? record.deltas : {};
+  const scorecard = {
+    experimentId: record.experimentId,
+    taskClass: record.taskClass ?? null,
+    baselineRef: record.baselineRef ?? null,
+    deltas: {
+      quality: Number(deltas.quality ?? 0),
+      rework: Number(deltas.rework ?? 0),
+      latency: Number(deltas.latency ?? 0),
+      calls: Number(deltas.calls ?? 0),
+    },
+    verdict: record.verdict,
+  };
+  const promotionEligible = record.verdict === 'net-gain';
+  return {
+    ...scorecard,
+    promotionEligible,
+    disposition: promotionEligible ? 'maintainer-review' : 'stay-disabled',
+  };
+}