@ngockhoale/ukit 3.3.3 → 3.4.1

package/src/index/crossCheckMatrix.js

@@ -0,0 +1,412 @@
+// crossCheckMatrix.js — adaptive cross-check depth matrix (BL-016 /
+// SPEC FR-004 / ARCH §Adaptive Cross-Check).
+//
+// Verification depth scales with risk instead of being uniform — a separate
+// dimension from implementation depth (fast path vs full workflow). This
+// module is deterministic and pure: it resolves
+//
+//   change-risk × implementer-reliability × evidence-quality
+//     → none | runnable | review-round | escalate
+//
+// and the result feeds the review policy's `escalationDepth` input slot
+// (src/index/reviewPolicy.js), which maps depth → action floor.
+//
+// Contract (SPEC §8):
+//   resolveCrossCheckDepth({riskFloor?, rigor?, implementerReliability?,
+//     evidenceQuality?, reviewer?, implementer?, runnable?, role?, model?,
+//     project?, overrides?}) → {depth, reasons[]}
+//
+// Invariants from ARCH §Adaptive Cross-Check:
+//   * high change-risk overrides implementer reliability — a strong model on
+//     an auth/data-path change still escalates to mandatory review.
+//   * a reviewer of the SAME model family is not independent review — a
+//     same-family re-read never satisfies a review-round; the depth demotes
+//     to `runnable` with the limit stated in reasons[].
+//   * no reviewer → `runnable` where possible + honest stated limit; the
+//     caller reports INCONCLUSIVE when nothing is runnable (the depth enum
+//     cannot return INCONCLUSIVE — it names a depth, not a verdict).
+//   * implementer-reliability is a joined outcome signal, never a model-name
+//     verdict — absent or unrecognized input resolves to baseline-neutral
+//     'unknown' (GAP M13).
+//   * `crossCheck.{role|model}×{project}` maintainer overrides may tighten or
+//     loosen within the enum; malformed overrides are ignored, never fatal.
+//
+// Parity: tests/consistency/crossCheckParity.test.js locks this module and
+// the installed mirror to identical exports, identical matrix rows, and
+// identical {depth, reasons[]} on shared fixtures.
+
+// Ordered by severity — override clamping and floor comparisons rely on the
+// index order, so consumers must never reorder this list.
+export const CROSS_CHECK_DEPTHS = Object.freeze([
+  'none',
+  'runnable',
+  'review-round',
+  'escalate',
+]);
+
+export const CROSS_CHECK_RISK_LEVELS = Object.freeze(['low', 'medium', 'high']);
+
+export const CROSS_CHECK_RELIABILITY_LEVELS = Object.freeze([
+  'trusted',
+  'needs-oversight',
+  'unknown',
+]);
+
+export const CROSS_CHECK_EVIDENCE_QUALITIES = Object.freeze([
+  'strong',
+  'thin',
+  'missing-hooks',
+]);
+
+// The ARCH §Adaptive Cross-Check matrix verbatim (7 rows). 'any' is a
+// wildcard. First matching row wins, which gives the two 'any'-wildcard rows
+// their precedence: high-risk escalate beats everything; missing-hooks
+// degrade applies to whatever remains.
+export const CROSS_CHECK_MATRIX = Object.freeze([
+  { risk: 'low', reliability: 'trusted', evidence: 'strong', depth: 'none' },
+  { risk: 'low', reliability: 'needs-oversight', evidence: 'thin', depth: 'review-round' },
+  { risk: 'low', reliability: 'unknown', evidence: 'strong', depth: 'runnable' },
+  { risk: 'medium', reliability: 'trusted', evidence: 'strong', depth: 'runnable' },
+  { risk: 'medium', reliability: 'needs-oversight', evidence: 'any', depth: 'review-round' },
+  { risk: 'high', reliability: 'any', evidence: 'any', depth: 'escalate' },
+  { risk: 'any', reliability: 'any', evidence: 'missing-hooks', depth: 'runnable' },
+]);
+
+// Cells the matrix does not list resolve conservatively: needs-oversight on
+// a low/medium-risk change is the row-2/row-5 signal family, so it still
+// earns a review round; trusted and baseline-neutral reliability never drop
+// below `runnable` on unlisted cells — thin evidence can never justify `none`.
+const RELIABILITY_RESIDUAL = Object.freeze({
+  'needs-oversight': 'review-round',
+});
+
+// Bounded maintainer override shapes: a bound leaf carries only these keys
+// (validated in src/core/runtimeConfig.js); all other top-level keys of the
+// section are reserved.
+const BOUND_KEYS = new Set(['depth', 'minDepth', 'maxDepth']);
+const CROSS_CHECK_SECTION_KEYS = new Set(['enabled', 'byRole', 'byModel']);
+
+const MAX_ID_LENGTH = 96;
+
+const RISK_ALIASES = Object.freeze({
+  high: 'high',
+  'high-risk': 'high',
+  critical: 'high',
+  medium: 'medium',
+  moderate: 'medium',
+  low: 'low',
+  none: 'low',
+  trivial: 'low',
+});
+
+const RELIABILITY_ALIASES = Object.freeze({
+  trusted: 'trusted',
+  'needs-oversight': 'needs-oversight',
+  unknown: 'unknown',
+  baseline: 'unknown',
+  'baseline-neutral': 'unknown',
+});
+
+// Receipt classes attesting real-run/surface evidence vs build-only or
+// claimed-only work (ARCH: evidence-quality is about receipt classes present,
+// never about what the agent asserts).
+const STRONG_EVIDENCE_TOKENS = new Set([
+  'strong',
+  'surface-check',
+  'render-observation',
+  'io-run',
+  'run-receipt',
+  'real-run',
+  'verification-evidence',
+  'write-evidence',
+]);
+const THIN_EVIDENCE_TOKENS = new Set([
+  'thin',
+  'build-only',
+  'claimed',
+  'claimed-only',
+  'log',
+]);
+const MISSING_HOOKS_TOKENS = new Set([
+  'missing-hooks',
+  'unavailable',
+  'cannot-produce',
+]);
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function depthIndex(depth) {
+  return CROSS_CHECK_DEPTHS.indexOf(depth);
+}
+
+function boundedId(value) {
+  return typeof value === 'string' && value.trim()
+    ? value.trim().slice(0, MAX_ID_LENGTH)
+    : null;
+}
+
+// ─── input normalization ────────────────────────────────────────────────────
+
+// riskFloor arrives as the route record's {floor:'none'|'high-risk', codes[]},
+// a bare enum/code string, or a level name. `rigor` (R0-R4) only ever RAISES
+// the floor: R3+ ceremony on a non-floor route still counts as medium risk —
+// the router asked for deep work, so verification follows.
+function normalizeRisk(riskFloor, rigor) {
+  let risk = 'low';
+  if (typeof riskFloor === 'string') {
+    risk = RISK_ALIASES[riskFloor.trim().toLowerCase()] ?? 'low';
+  } else if (isPlainObject(riskFloor)) {
+    const floor = typeof riskFloor.floor === 'string'
+      ? riskFloor.floor.trim().toLowerCase()
+      : null;
+    if (RISK_ALIASES[floor]) {
+      risk = RISK_ALIASES[floor];
+    } else if (typeof riskFloor.risk === 'string') {
+      risk = RISK_ALIASES[riskFloor.risk.trim().toLowerCase()] ?? 'low';
+    }
+  }
+  if (risk === 'low' && typeof rigor === 'string') {
+    const level = /^r(\d)$/i.exec(rigor.trim());
+    if (level && Number(level[1]) >= 3) risk = 'medium';
+  }
+  return risk;
+}
+
+// Reliability is joined outcome data, never a model-name verdict: anything
+// absent or unrecognized collapses to baseline-neutral 'unknown'.
+function normalizeReliability(value) {
+  if (typeof value !== 'string') return 'unknown';
+  return RELIABILITY_ALIASES[value.trim().toLowerCase()] ?? 'unknown';
+}
+
+function normalizeEvidenceQuality(value) {
+  if (value == null) return 'thin';
+  if (Array.isArray(value)) {
+    if (value.length === 0) return 'thin';
+    const tokens = value
+      .filter((token) => typeof token === 'string' && token.trim())
+      .map((token) => token.trim().toLowerCase());
+    if (tokens.some((token) => MISSING_HOOKS_TOKENS.has(token))) return 'missing-hooks';
+    if (tokens.some((token) => STRONG_EVIDENCE_TOKENS.has(token))) return 'strong';
+    return 'thin';
+  }
+  if (typeof value === 'string') {
+    const token = value.trim().toLowerCase();
+    if (MISSING_HOOKS_TOKENS.has(token)) return 'missing-hooks';
+    if (STRONG_EVIDENCE_TOKENS.has(token)) return 'strong';
+    return 'thin';
+  }
+  if (isPlainObject(value)) {
+    if (typeof value.quality === 'string') return normalizeEvidenceQuality(value.quality);
+    if (Array.isArray(value.classes)) return normalizeEvidenceQuality(value.classes);
+  }
+  return 'thin';
+}
+
+// ─── reviewer independence ──────────────────────────────────────────────────
+// A review-round only counts when a reviewer of a DIFFERENT model family
+// exists — same-family re-reads and self re-reads are not independent review
+// (SPEC FR-004). A reviewer descriptor that supplies no family cannot be
+// proven same or different; it is treated as independent but the assumption
+// is named in the reasons so the receipt stays honest.
+function reviewerIndependence(reviewer, implementer) {
+  if (!isPlainObject(reviewer)) {
+    return { independent: false, reason: 'no reviewer available' };
+  }
+  const reviewerFamily = boundedId(reviewer.modelFamily) ?? boundedId(reviewer.family);
+  const reviewerModel = boundedId(reviewer.model) ?? boundedId(reviewer.id) ?? boundedId(reviewer.name);
+  const implementerFamily = isPlainObject(implementer)
+    ? (boundedId(implementer.modelFamily) ?? boundedId(implementer.family))
+    : null;
+  const implementerModel = isPlainObject(implementer)
+    ? (boundedId(implementer.model) ?? boundedId(implementer.id) ?? boundedId(implementer.name))
+    : null;
+  if (reviewerModel && implementerModel && reviewerModel === implementerModel) {
+    return { independent: false, reason: 'reviewer is the implementer re-reading its own diff — not independent' };
+  }
+  if (reviewerFamily && implementerFamily && reviewerFamily === implementerFamily) {
+    return { independent: false, reason: 'same-model-family reviewer is not independent review' };
+  }
+  return {
+    independent: true,
+    reason: reviewerFamily
+      ? 'different-model-family reviewer available'
+      : 'reviewer family unproven — assuming independent',
+  };
+}
+
+// ─── maintainer overrides ───────────────────────────────────────────────────
+// `crossCheck.{role|model}×{project}` bounded overrides, per ARCH §Config:
+// enum-only, shipped ON. A bound leaf is {depth|minDepth|maxDepth}; an entry
+// may also be a project map {projectId|'*': bound}. byRole wins over byModel;
+// a project-named leaf wins over the '*' leaf of the same entry. Unknown
+// shapes are ignored with a reason — a maintainer typo must never crash the
+// route nor invent a depth outside the enum.
+function boundLeaf(entry) {
+  if (!isPlainObject(entry)) return null;
+  if (Object.keys(entry).some((key) => BOUND_KEYS.has(key))) return entry;
+  return null;
+}
+
+function resolveOverrideBound(overrides, { role = null, model = null, project = null }) {
+  if (!isPlainObject(overrides) || overrides.enabled === false) return null;
+  const maps = [
+    ['role', role, overrides.byRole],
+    ['model', model, overrides.byModel],
+  ];
+  for (const [kind, name, map] of maps) {
+    if (!name || !isPlainObject(map)) continue;
+    const entry = map[name];
+    if (entry === undefined) continue;
+    const direct = boundLeaf(entry);
+    if (direct) {
+      return { bound: direct, label: `${kind} "${name}"` };
+    }
+    if (isPlainObject(entry)) {
+      const projectLeaf = project ? boundLeaf(entry[project]) : null;
+      const starLeaf = boundLeaf(entry['*']);
+      const picked = projectLeaf ?? starLeaf;
+      if (picked) {
+        return {
+          bound: picked,
+          label: `${kind} "${name}"${projectLeaf ? ` project "${project}"` : ''}`,
+        };
+      }
+    }
+    return { bound: null, label: `${kind} "${name}"` };
+  }
+  // A bare bound ({depth:…} / {minDepth:…} / {maxDepth:…}) applies directly.
+  const direct = boundLeaf(overrides);
+  if (direct) return { bound: direct, label: 'crossCheck' };
+  return null;
+}
+
+// ─── resolver ───────────────────────────────────────────────────────────────
+
+export function resolveCrossCheckDepth({
+  riskFloor = null,
+  rigor = null,
+  implementerReliability = null,
+  evidenceQuality = null,
+  reviewer = undefined,
+  implementer = null,
+  runnable = true,
+  role = null,
+  model = null,
+  project = null,
+  overrides = null,
+} = {}) {
+  const reasons = [];
+  const risk = normalizeRisk(riskFloor, rigor);
+  const reliability = normalizeReliability(implementerReliability);
+  const evidence = normalizeEvidenceQuality(evidenceQuality);
+
+  if (implementerReliability == null
+    || (typeof implementerReliability === 'string'
+      && RELIABILITY_ALIASES[implementerReliability.trim().toLowerCase()] === undefined)) {
+    reasons.push(
+      'implementerReliability unresolved — defaulting to project-baseline neutral '
+      + '("unknown"); reliability is a joined outcome signal, never a model-name verdict',
+    );
+  }
+
+  let depth = null;
+  let decidingRow = null;
+  for (const row of CROSS_CHECK_MATRIX) {
+    if ((row.risk === 'any' || row.risk === risk)
+      && (row.reliability === 'any' || row.reliability === reliability)
+      && (row.evidence === 'any' || row.evidence === evidence)) {
+      depth = row.depth;
+      decidingRow = row;
+      break;
+    }
+  }
+
+  if (depth) {
+    const index = CROSS_CHECK_MATRIX.indexOf(decidingRow) + 1;
+    reasons.push(
+      `matrix row ${index}: risk=${decidingRow.risk === 'any' ? risk : decidingRow.risk} × `
+      + `reliability=${decidingRow.reliability === 'any' ? reliability : decidingRow.reliability} × `
+      + `evidence=${decidingRow.evidence === 'any' ? evidence : decidingRow.evidence} → ${decidingRow.depth}`,
+    );
+    if (decidingRow.risk === 'high') {
+      reasons.push('high change-risk overrides implementer reliability — mandatory review regardless of track record');
+    }
+    if (decidingRow.evidence === 'missing-hooks') {
+      reasons.push(
+        'engine cannot produce a needed receipt class (missing hooks) — runnable '
+        + 'checks where possible + honest stated limit; INCONCLUSIVE if nothing runnable',
+      );
+    }
+  } else {
+    depth = RELIABILITY_RESIDUAL[reliability] ?? 'runnable';
+    reasons.push(
+      `no verbatim matrix row for risk=${risk} × reliability=${reliability} × evidence=${evidence} — `
+      + `residual rule resolves ${depth} (needs-oversight still earns a review round; `
+      + 'trusted/baseline never drops below runnable)',
+    );
+  }
+
+  // Reviewer independence only demotes the review-round depth: the matrix
+  // chose it for the signal, but without a different-family reviewer a
+  // same-family or self re-read is not independent review. 'escalate' is a
+  // mandatory hand-off — it never silently downgrades; the reason names the
+  // missing reviewer so the consumer escalates to a human or another lane.
+  const independence = reviewerIndependence(reviewer, implementer);
+  if (depth === 'review-round' && !independence.independent) {
+    reasons.push(`${independence.reason} — review-round demoted to runnable checks + stated limit`);
+    depth = 'runnable';
+    if (runnable === false) {
+      reasons.push('nothing runnable — report INCONCLUSIVE');
+    }
+  } else if (depth === 'review-round') {
+    reasons.push(independence.reason);
+  } else if (depth === 'escalate' && !independence.independent) {
+    reasons.push(
+      `${independence.reason} — escalate stands: mandatory review requires a `
+      + 'different-family reviewer or human sign-off, never a silent downgrade',
+    );
+  }
+
+  // Maintainer overrides bound the resolved depth last. A 'depth' pin wins;
+  // minDepth/maxDepth clamp within the enum. Invalid bound values are ignored
+  // with a named reason — schema validation in runtimeConfig.js rejects them
+  // at parse time; this guard covers programmatic callers.
+  const resolved = resolveOverrideBound(overrides, { role, model, project });
+  if (resolved && resolved.bound) {
+    const bound = resolved.bound;
+    let applied = null;
+    if (typeof bound.depth === 'string' && CROSS_CHECK_DEPTHS.includes(bound.depth)) {
+      depth = bound.depth;
+      applied = `depth=${bound.depth}`;
+    } else {
+      if (typeof bound.maxDepth === 'string'
+        && CROSS_CHECK_DEPTHS.includes(bound.maxDepth)
+        && depthIndex(depth) > depthIndex(bound.maxDepth)) {
+        depth = bound.maxDepth;
+        applied = `maxDepth=${bound.maxDepth}`;
+      }
+      if (typeof bound.minDepth === 'string'
+        && CROSS_CHECK_DEPTHS.includes(bound.minDepth)
+        && depthIndex(depth) < depthIndex(bound.minDepth)) {
+        depth = bound.minDepth;
+        applied = applied ? `${applied} + minDepth=${bound.minDepth}` : `minDepth=${bound.minDepth}`;
+      }
+    }
+    if (applied) {
+      reasons.push(`crossCheck override (${resolved.label}) applied: ${applied} → ${depth}`);
+    } else {
+      reasons.push(`crossCheck override (${resolved.label}) present but no enum bound applied`);
+    }
+  } else if (resolved) {
+    reasons.push(`crossCheck override (${resolved.label}) has no valid enum bound — ignored`);
+  } else if (isPlainObject(overrides) && Object.keys(overrides).some(
+    (key) => !CROSS_CHECK_SECTION_KEYS.has(key) && !BOUND_KEYS.has(key),
+  )) {
+    reasons.push('crossCheck override keys unrecognized — ignored');
+  }
+
+  return { depth, reasons };
+}