@ngockhoale/ukit 3.0.7 → 3.0.9

package/src/core/observability/evaluation/experimentPlan.js

@@ -0,0 +1,95 @@
+/**
+ * experimentPlan — pure staged controlled-experiment planner (GAP-c).
+ *
+ * Maps a KB optimization entry + a `computeGateComparison` GateComparison to
+ * staged rollout ACTIONS over the seam ladder. The planner EMITS intent only:
+ * it never mutates config, never calls killSwitch/resolveSeamConfig, and never
+ * touches fs. Execution (if any) is a separate operator-owned act.
+ *
+ * Rules:
+ * - gate must be a real GateComparison (verdict in pass|non-inferior|unknown);
+ *   anything else → TypeError (a fabricated gate can never plan a promotion).
+ * - abort flag (operator rollback_criterion met) → kill 'abort-requested'.
+ * - gate.forbiddenFailures > 0 → kill 'forbidden-failures' prepended.
+ * - verdict !== 'pass' → hold (reason = verdict). 'non-inferior' means the
+ *   variant FAILED the pre-registered gate.
+ * - verdict 'pass' + non-empty controlled_rollout.evidence_refs → one promote
+ *   action per seam in stage-rank order (shadow → canary → default), each
+ *   carrying requires_evidence_refs:true. Missing refs → hold
+ *   'missing-controlled-rollout-evidence': promotion never fires on the
+ *   quality signal alone.
+ */
+
+import { SEAM_MIN_STAGE } from '../rollout.js';
+
+export const ROLLOUT_ACTIONS = Object.freeze(['promote', 'hold', 'kill']);
+
+const GATE_VERDICTS = new Set(['pass', 'non-inferior', 'unknown']);
+
+const STAGE_RANK = { shadow: 1, canary: 2, default: 3 };
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isNonEmptyStringList(value) {
+  return (
+    Array.isArray(value) &&
+    value.length > 0 &&
+    value.every((v) => typeof v === 'string' && v.length > 0)
+  );
+}
+
+/**
+ * @param {{optimization?: object, gate?: object, abort?: boolean}} input
+ * @returns {{actions: object[]}} frozen action list
+ */
+export function planControlledRollout(input = {}) {
+  const { optimization, gate, abort } = isPlainObject(input) ? input : {};
+
+  if (!isPlainObject(gate) || !GATE_VERDICTS.has(gate.verdict)) {
+    throw new TypeError(
+      'experimentPlan: gate must be a GateComparison with verdict in pass|non-inferior|unknown',
+    );
+  }
+
+  const actions = [];
+
+  if (abort === true) {
+    actions.push({ type: 'kill', reason: 'abort-requested' });
+  }
+  if (gate.forbiddenFailures > 0) {
+    actions.push({ type: 'kill', reason: 'forbidden-failures' });
+  }
+
+  if (gate.verdict !== 'pass') {
+    actions.push({ type: 'hold', reason: gate.verdict });
+    return { actions: Object.freeze(actions) };
+  }
+
+  if (actions.length > 0) {
+    // pass + forbiddenFailures is unreachable from real computeGateComparison
+    // output (forbidden → non-inferior hard gate); defend the shape anyway.
+    return { actions: Object.freeze(actions) };
+  }
+
+  const rollout = isPlainObject(optimization) ? optimization.controlled_rollout : undefined;
+  const evidenceRefs = isPlainObject(rollout) ? rollout.evidence_refs : undefined;
+  if (!isNonEmptyStringList(evidenceRefs)) {
+    return {
+      actions: Object.freeze([{ type: 'hold', reason: 'missing-controlled-rollout-evidence' }]),
+    };
+  }
+
+  // Order from the shared seam contract (read-only): each seam promotes at the
+  // stage it unlocks, lowest stage rank first.
+  const seams = Object.entries(SEAM_MIN_STAGE)
+    .map(([seam, stage]) => ({ seam, stage }))
+    .sort((a, b) => STAGE_RANK[a.stage] - STAGE_RANK[b.stage] || a.seam.localeCompare(b.seam));
+
+  for (const { seam, stage } of seams) {
+    actions.push({ type: 'promote', seam, stage, requires_evidence_refs: true });
+  }
+
+  return { actions: Object.freeze(actions) };
+}

package/src/core/observability/evaluation/findings.js

@@ -0,0 +1,99 @@
+/**
+ * findings.js (TASK-002, SPEC §2 G6-FR04) — evaluator findings validator.
+ *
+ *   validateEvaluatorFindings(payload) → { findings[], rejected[] }
+ *
+ * Advisory-only boundary between the optional AI evaluator and the rest
+ * of the pipeline: an evaluator's opinion can never be promoted to fact
+ * or policy. Every accepted finding is re-shaped by construction to
+ *   { claim, evidence_refs, confidence, alternatives?, decision:
+ *   'unsupported', applied: false }
+ * and frozen — caller-injected `decision`/`applied`/`promoted` fields are
+ * never propagated.
+ *
+ * Evidence gate: a candidate without a non-empty `claim` (non-empty
+ * string) or a non-empty `evidence_refs` (all-string array) is moved to
+ * `rejected[]` with `{ candidate_index, reason }` — never silently
+ * dropped. Out-of-enum confidence coerces to 'unknown'; `alternatives`
+ * carries over as advisory hints (strings only). Malformed payloads
+ * (non-object, non-array, or a non-array `findings` field) reject the
+ * whole payload with `candidate_index: null`.
+ *
+ * Pure module: no fs, no clock, no model calls; never throws on data.
+ */
+
+export const FINDING_CONFIDENCE = Object.freeze([
+  'high',
+  'medium',
+  'low',
+  'unknown',
+]);
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isNonEmptyString(value) {
+  return typeof value === 'string' && value.length > 0;
+}
+
+function isStringList(value) {
+  return Array.isArray(value) && value.length > 0 && value.every(isNonEmptyString);
+}
+
+function candidates(payload) {
+  if (Array.isArray(payload)) return payload;
+  if (isPlainObject(payload) && Array.isArray(payload.findings)) {
+    return payload.findings;
+  }
+  return null;
+}
+
+/**
+ * Validate evaluator-returned findings. `payload` may be either
+ * `{ findings: [...] }` or a bare findings array — both accept the same
+ * candidate shape.
+ */
+export function validateEvaluatorFindings(payload) {
+  const list = candidates(payload);
+  if (list === null) {
+    return {
+      findings: [],
+      rejected: [{ candidate_index: null, reason: 'malformed-payload' }],
+    };
+  }
+
+  const findings = [];
+  const rejected = [];
+
+  for (let i = 0; i < list.length; i += 1) {
+    const candidate = isPlainObject(list[i]) ? list[i] : {};
+    if (!isNonEmptyString(candidate.claim)) {
+      rejected.push({ candidate_index: i, reason: 'missing-claim' });
+      continue;
+    }
+    if (!isStringList(candidate.evidence_refs)) {
+      rejected.push({ candidate_index: i, reason: 'missing-evidence-refs' });
+      continue;
+    }
+
+    const finding = {
+      claim: candidate.claim,
+      evidence_refs: [...candidate.evidence_refs],
+      confidence: FINDING_CONFIDENCE.includes(candidate.confidence)
+        ? candidate.confidence
+        : 'unknown',
+    };
+    if (Array.isArray(candidate.alternatives)) {
+      const alternatives = candidate.alternatives.filter(isNonEmptyString);
+      if (alternatives.length > 0) finding.alternatives = alternatives;
+    }
+    // Advisory-only by construction: evaluator decision/applied fields
+    // are never read; the output shape is fixed.
+    finding.decision = 'unsupported';
+    finding.applied = false;
+    findings.push(Object.freeze(finding));
+  }
+
+  return { findings, rejected };
+}

package/src/core/observability/evaluation/optimizationKnowledge.js

@@ -18,7 +18,8 @@
  *
  * Invariants (SPEC §12, DF-FR12):
  *   - `decision: 'promoted'` or `applied: true` REQUIRE
- *     `controlled_rollout.evidence_refs` — no promotion from token
+ *     `controlled_rollout.evidence_refs` AND a non-empty
+ *     `alternative_explanations` list — no promotion from token
  *     reduction alone; violating entries throw TypeError.
  *   - `decision: 'unsupported'` records can never carry `applied: true`.
  *   - This module writes ONLY inside `root` — no runtime config, no
@@ -110,6 +111,13 @@ export function createOptimizationStore({ root, clock } = {}) {
       throw new TypeError(
         'recordOptimization: decision promoted / applied requires controlled_rollout.evidence_refs',
       );
+    } else if (decision === 'promoted' || applied) {
+      const alternatives = stringList(entry.alternative_explanations);
+      if (alternatives.length === 0) {
+        throw new TypeError(
+          'recordOptimization: decision promoted / applied requires alternative_explanations',
+        );
+      }
     }
 
     const core = {
@@ -127,6 +135,7 @@ export function createOptimizationStore({ root, clock } = {}) {
       rollback_criterion:
         typeof entry.rollback_criterion === 'string' ? entry.rollback_criterion : null,
       supersedes: stringList(entry.supersedes),
+      alternative_explanations: stringList(entry.alternative_explanations),
       created_at: now(),
     };
 

package/src/core/observability/evaluation/perturbation.js

@@ -0,0 +1,273 @@
+/**
+ * perturbation.js (TASK-002, SPEC §2 G5-FR06/G5-FR07) — synthetic mutation harness.
+ *
+ *   mutateSummaries(summaries, { seed, plan? }) → { summaries, manifest }
+ *   detectPerturbations(mutatedSummaries, baselineSummaries, manifest)
+ *     → { injected, detected, missed[], details[] }
+ *
+ * Pure module: no fs, no clock, no unseeded randomness (mulberry32, same
+ * construction as the bench corpus generator). Mutations edit TraceSummary
+ * structures so the downstream pipeline sees a genuinely different trace;
+ * detection is measured through the REAL computeFingerprint /
+ * detectOpportunities path — never from the manifest alone.
+ *
+ * Mutation kinds (MUTATION_KINDS):
+ *   drop_record          — removes a span and raises drops.dropped_count>0
+ *   retry_inflation      — adds an attempt_index>1 model span and raises retries
+ *   cache_miss_spike     — adds cache misses (cache.observed, hit_rate recomputed)
+ *   orphan_span          — rewrites parent_span_id to an absent id
+ *   telemetry_incomplete — flips telemetry_complete=false
+ *
+ * Detection rule (per manifest entry): the mutated trace is detected when its
+ * fingerprint kind/count diverges from its own baseline, OR — once the trace
+ * is proven changed (hash divergence) — its opportunity cluster reports
+ * `inconclusive` (the honesty path telemetry_incomplete relies on) or a
+ * non-clean pattern. An unmutated trace claimed in the manifest cannot be
+ * detected: hash-identical traces have nothing to report.
+ */
+
+import { computeFingerprint } from '../analytics/fingerprints.js';
+import { detectOpportunities } from '../analytics/opportunities.js';
+
+export const MUTATION_KINDS = Object.freeze([
+  'drop_record',
+  'retry_inflation',
+  'cache_miss_spike',
+  'orphan_span',
+  'telemetry_incomplete',
+]);
+
+// Deterministic PRNG (mulberry32) — identical construction to the bench corpus.
+function mulberry32(seed) {
+  let a = seed >>> 0;
+  return function next() {
+    a |= 0;
+    a = (a + 0x6d2b79f5) | 0;
+    let t = Math.imul(a ^ (a >>> 15), 1 | a);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function num(value) {
+  return typeof value === 'number' && Number.isFinite(value) ? value : 0;
+}
+
+/**
+ * Candidate indices for a kind — a mutation must produce a genuinely
+ * different trace, so kinds with preconditions filter to eligible traces.
+ * Prefers traces not already mutated by this call.
+ */
+function candidateIndices(mutated, kind, used) {
+  const eligible = mutated
+    .map((s, idx) => ({ s, idx }))
+    .filter(({ s }) => {
+      if (!isPlainObject(s) || !Array.isArray(s.spans) || s.spans.length === 0) return false;
+      if (kind === 'telemetry_incomplete') return s.telemetry_complete === true;
+      return true;
+    })
+    .map(({ idx }) => idx);
+  const fresh = eligible.filter((idx) => !used.has(idx));
+  return fresh.length > 0 ? fresh : eligible;
+}
+
+function ensureCounters(summary) {
+  if (!isPlainObject(summary.retries)) summary.retries = {};
+  if (!isPlainObject(summary.drops)) summary.drops = {};
+  if (!isPlainObject(summary.drops.by_reason)) summary.drops.by_reason = {};
+  if (!isPlainObject(summary.cache)) summary.cache = {};
+  if (!isPlainObject(summary.coverage)) summary.coverage = {};
+}
+const MUTATORS = {
+  drop_record(summary) {
+    const idx = summary.spans.findIndex(
+      (s) => typeof s.parent_span_id === 'string' && s.parent_span_id.length > 0,
+    );
+    const i = idx >= 0 ? idx : 0;
+    const removed = summary.spans.splice(i, 1)[0] || null;
+    summary.drops.events = num(summary.drops.events) + 1;
+    summary.drops.dropped_count = num(summary.drops.dropped_count) + 1;
+    summary.drops.by_reason.synthetic_drop = num(summary.drops.by_reason.synthetic_drop) + 1;
+    summary.telemetry_complete = false;
+    summary.coverage.spans = summary.spans.length;
+    return { removed_span_id: removed ? removed.span_id : null };
+  },
+
+  retry_inflation(summary) {
+    const model =
+      summary.spans.find((s) => s.family === 'model') ||
+      summary.spans[summary.spans.length - 1] ||
+      null;
+    const maxAttempt = summary.spans.reduce(
+      (m, s) => (Number.isInteger(s.attempt_index) ? Math.max(m, s.attempt_index) : m),
+      0,
+    );
+    const attemptIndex = Math.max(2, maxAttempt + 1);
+    const clone = {
+      ...(model || {
+        parent_span_id: null,
+        family: 'model',
+        operation: null,
+        status: 'completed',
+        duration_ms: 0,
+      }),
+      span_id: `${model ? model.span_id : 'span'}-retry${attemptIndex}`,
+      attempt_index: attemptIndex,
+      status: 'completed',
+      start_record_id: `rec-${summary.trace_id}-retry${attemptIndex}-start`,
+      end_record_id: `rec-${summary.trace_id}-retry${attemptIndex}-end`,
+    };
+    summary.spans.push(clone);
+    summary.retries.retries = num(summary.retries.retries) + 1;
+    summary.retries.model_attempts = num(summary.retries.model_attempts) + 1;
+    summary.coverage.spans = summary.spans.length;
+    return { added_attempt_span: clone.span_id, attempt_index: attemptIndex };
+  },
+
+  cache_miss_spike(summary, rand) {
+    const added = 2 + Math.floor(rand() * 3); // 2..4 misses
+    summary.cache.observed = true;
+    summary.cache.hits = num(summary.cache.hits);
+    summary.cache.misses = num(summary.cache.misses) + added;
+    const lookups = summary.cache.hits + summary.cache.misses;
+    summary.cache.hit_rate = lookups > 0 ? summary.cache.hits / lookups : null;
+    return { misses_added: added };
+  },
+
+  orphan_span(summary) {
+    const idx = summary.spans.findIndex(
+      (s) => typeof s.parent_span_id === 'string' && s.parent_span_id.length > 0,
+    );
+    const i = idx >= 0 ? idx : 0;
+    const target = summary.spans[i];
+    const previous = target.parent_span_id ?? null;
+    target.parent_span_id = `absent-${target.span_id}`;
+    summary.coverage.orphan_spans = num(summary.coverage.orphan_spans) + 1;
+    return { span_id: target.span_id, previous_parent: previous };
+  },
+
+  telemetry_incomplete(summary) {
+    const previous = summary.telemetry_complete;
+    summary.telemetry_complete = false;
+    return { previous_telemetry_complete: previous };
+  },
+};
+
+/**
+ * @param {Array<object>} summaries — baseline TraceSummary objects (not mutated).
+ * @param {{ seed?: number, plan?: Array<{kind:string}> }} [options]
+ *   plan defaults to one mutation per MUTATION_KINDS entry.
+ * @returns {{ summaries: Array<object>, manifest: Array<object> }}
+ *   manifest entries: { mutation_id, trace_id, kind, detail }.
+ */
+export function mutateSummaries(summaries, { seed = 42, plan } = {}) {
+  if (!Array.isArray(summaries)) {
+    throw new TypeError('mutateSummaries: summaries must be an array of TraceSummary');
+  }
+  const effectivePlan = Array.isArray(plan) ? plan : MUTATION_KINDS.map((kind) => ({ kind }));
+  for (const entry of effectivePlan) {
+    if (!isPlainObject(entry) || !MUTATION_KINDS.includes(entry.kind)) {
+      throw new TypeError(
+        `mutateSummaries: plan entries need kind ∈ {${MUTATION_KINDS.join(', ')}}`,
+      );
+    }
+  }
+
+  const rand = mulberry32(seed);
+  const mutated = summaries.map((s) => JSON.parse(JSON.stringify(s)));
+  const manifest = [];
+  const used = new Set();
+
+  effectivePlan.forEach((entry, i) => {
+    const pickFrom = candidateIndices(mutated, entry.kind, used);
+    if (pickFrom.length === 0) return;
+    const targetIdx = pickFrom[Math.floor(rand() * pickFrom.length)];
+    used.add(targetIdx);
+    const summary = mutated[targetIdx];
+    ensureCounters(summary);
+    const detail = MUTATORS[entry.kind](summary, rand);
+    manifest.push({
+      mutation_id: `mut-${String(i + 1).padStart(3, '0')}`,
+      trace_id: typeof summary.trace_id === 'string' ? summary.trace_id : `idx-${targetIdx}`,
+      kind: entry.kind,
+      detail,
+    });
+  });
+
+  return { summaries: mutated, manifest };
+}
+
+/**
+ * Measure detection through the real pipeline: computeFingerprint for
+ * per-trace divergence vs baseline and detectOpportunities for cluster
+ * status over the mutated set.
+ *
+ * @param {Array<object>} mutatedSummaries
+ * @param {Array<object>} baselineSummaries
+ * @param {Array<object>} manifest — entries from mutateSummaries.
+ * @returns {{ injected:number, detected:number, missed:Array<object>, details:Array<object> }}
+ */
+export function detectPerturbations(mutatedSummaries, baselineSummaries, manifest) {
+  if (!Array.isArray(mutatedSummaries) || !Array.isArray(baselineSummaries) || !Array.isArray(manifest)) {
+    throw new TypeError('detectPerturbations: summaries and manifest must be arrays');
+  }
+
+  const baselineByTrace = new Map();
+  for (const s of baselineSummaries) {
+    if (isPlainObject(s) && typeof s.trace_id === 'string') baselineByTrace.set(s.trace_id, s);
+  }
+  const mutatedByTrace = new Map();
+  for (const s of mutatedSummaries) {
+    if (isPlainObject(s) && typeof s.trace_id === 'string') mutatedByTrace.set(s.trace_id, s);
+  }
+
+  // Real pipeline — never read the manifest as evidence.
+  const opportunities = detectOpportunities(mutatedSummaries);
+  const oppByTrace = new Map();
+  for (const opp of opportunities) {
+    for (const ref of opp.trace_refs || []) {
+      if (!oppByTrace.has(ref)) oppByTrace.set(ref, opp);
+    }
+  }
+
+  const details = [];
+  for (const entry of manifest) {
+    const mutated = mutatedByTrace.get(entry.trace_id);
+    const baseline = baselineByTrace.get(entry.trace_id);
+    const via = [];
+    let opportunity = null;
+    if (mutated && baseline) {
+      const fm = computeFingerprint(mutated);
+      const fb = computeFingerprint(baseline);
+      const changed = fm.hash !== fb.hash;
+      if (fm.kind !== fb.kind || fm.count !== fb.count) via.push('fingerprint');
+      opportunity = oppByTrace.get(entry.trace_id) || null;
+      if (changed && opportunity) {
+        if (opportunity.status === 'inconclusive') via.push('inconclusive');
+        else if (opportunity.fingerprint && opportunity.fingerprint.kind !== 'clean') {
+          via.push('opportunity');
+        }
+      }
+    }
+    details.push({
+      mutation_id: entry.mutation_id,
+      trace_id: entry.trace_id,
+      kind: entry.kind,
+      detected: via.length > 0,
+      via,
+      opportunity,
+    });
+  }
+
+  const missed = details.filter((d) => !d.detected);
+  return {
+    injected: manifest.length,
+    detected: details.length - missed.length,
+    missed,
+    details,
+  };
+}

package/src/core/observability/evaluation/replay.js

@@ -25,6 +25,8 @@
  * deterministically; explicit canonical values always win.
  */
 
+import { SEMANTIC_REGISTRY } from '../schema/registry.js';
+
 export const REPLAY_TAGS = Object.freeze(['POLICY', 'CONTEXT', 'SIMULATED']);
 
 export const REPLAY_LIMITATIONS = Object.freeze({
@@ -92,7 +94,11 @@ function materializeRecord(raw, ctx, index) {
   }
   if (typeof record.monotonic_ns !== 'number') record.monotonic_ns = dtMs * 1e6;
   if (typeof record.importance !== 'string') record.importance = 'normal';
-  if (typeof record.privacy_class !== 'string') record.privacy_class = 'public';
+  if (typeof record.privacy_class !== 'string') {
+    // Default to the semantic registry's privacy floor so materialized
+    // records satisfy the contract; unregistered names fall back to public.
+    record.privacy_class = SEMANTIC_REGISTRY[record.semantic_name]?.privacy_class ?? 'public';
+  }
   if (!isPlainObject(record.payload)) record.payload = {};
   return record;
 }

package/src/core/observability/evaluation/scorecard.js

@@ -16,6 +16,10 @@
  *     forbidden, bounds }, latency, tokens, cohorts, provenance, fidelity,
  *     sample_size, verdict: 'pass'|'fail'|'inconclusive', cases }
  *
+ * `cohorts` blocks are keyed by `task_type` first (falling back to the
+ * case's `cohort` string, then 'unknown') so a mixed-task corpus can never
+ * hide a per-task regression inside a pooled aggregate (Simpson's-paradox
+ * guard, G5-FR05).
  * Everything here is offline and deterministic — no model calls, no IO, no
  * clock, no randomness outside the seeded bootstrap in compareScorecards.
  */
@@ -129,6 +133,9 @@ function evaluateCase(goldenCase, policyId) {
   const base = {
     case_id: replay.case_id,
     cohort: typeof goldenCase.cohort === 'string' ? goldenCase.cohort : 'default',
+    task_type: typeof goldenCase.task_type === 'string' && goldenCase.task_type.length > 0
+      ? goldenCase.task_type
+      : 'unknown',
     fidelity: { tag: replay.tag, limitations: replay.limitations },
   };
   if (!replay.ok) {
@@ -241,6 +248,18 @@ function cohortVerdict(results, minN) {
   return 'pass';
 }
 
+/**
+ * Stratification block key: `task_type` is the first-class axis; cases
+ * without one fall back to their declared `cohort` string, then 'unknown'.
+ * Mixed-task corpora never pool into a bare global block.
+ */
+function blockKeyOf(result) {
+  return typeof result.task_type === 'string' && result.task_type !== 'unknown'
+    ? result.task_type
+    : (typeof result.cohort === 'string' && result.cohort.length > 0
+      ? result.cohort
+      : 'unknown');
+}
 /**
  * @param {object} corpus — `{ cases: GoldenCase[], pre_registered?, metric_version? }`.
  * @param {string|object} policy — policy id (resolved against
@@ -275,8 +294,9 @@ export function evaluateVariant(corpus, policy) {
     if (typeof result.metrics.tokens_to_success === 'number') {
       tokenValues.push(result.metrics.tokens_to_success);
     }
-    if (!cohorts.has(result.cohort)) cohorts.set(result.cohort, []);
-    cohorts.get(result.cohort).push(result);
+    const blockKey = blockKeyOf(result);
+    if (!cohorts.has(blockKey)) cohorts.set(blockKey, []);
+    cohorts.get(blockKey).push(result);
   }
 
   const cohortReport = {};
@@ -396,7 +416,7 @@ export function compareScorecards(a, b, { seed = 42 } = {}) {
     const pairs = [];
     for (const [id, ca] of aById) {
       const cb = bById.get(id);
-      if (cb && ca.cohort === key && cb.cohort === key && ca.ok && cb.ok) pairs.push([ca, cb]);
+      if (cb && blockKeyOf(ca) === key && blockKeyOf(cb) === key && ca.ok && cb.ok) pairs.push([ca, cb]);
     }
     const tokens = metricDelta(pairs, 'tokens_to_success', seed);
     const time = metricDelta(pairs, 'time_to_success_ms', seed + 1);

package/src/core/observability/rollout.js

@@ -1,17 +1,20 @@
 /**
  * rollout.js (TASK-015, SPEC §5 DF-FR13 / §13) — per-seam staged rollout.
  *
- *   SEAM_MIN_STAGE = { recorder: 'shadow', projector: 'canary', evaluation: 'default' }
- *   resolveSeamStages(config) → { recorder, projector, evaluation }
+ *   SEAM_MIN_STAGE = { recorder: 'shadow', analytics: 'shadow',
+ *                      projector: 'canary', evaluation: 'default' }
+ *   resolveSeamStages(config) → { recorder, analytics, projector, evaluation }
  *   resolveSeamConfig(config, seam) → live config view bound to that seam
  *   killSwitch(config, seam?) → config
  *
  * The single global flag `observability.stage` promotes off → shadow →
  * canary → default; each seam activates at its own minimum stage, so the
- * ladder is: shadow records only, canary adds the support projection,
- * default adds the evaluation surface. A seam whose effective stage falls
- * below its minimum resolves to 'off' — the value existing consumers
- * (createRecorder, projectSupport) already treat as their kill switch.
+ * ladder is: shadow records only (and unlocks the derived analytics lane —
+ * rebuildIndex/renderStoreDigest over retained segments), canary adds the
+ * support projection, default adds the evaluation surface. A seam whose
+ * effective stage falls below its minimum resolves to 'off' — the value
+ * existing consumers (createRecorder, projectSupport) already treat as
+ * their kill switch.
  *
  * Per-seam overrides live at `observability.seams.<seam>.stage` and are
  * RESTRICTIVE-ONLY: the effective stage is min(global, override) clamped
@@ -38,10 +41,11 @@ import { resolveStage } from './emit/config.js';
 
 const STAGE_RANK = { off: 0, shadow: 1, canary: 2, default: 3 };
 
-export const SEAM_NAMES = Object.freeze(['recorder', 'projector', 'evaluation']);
+export const SEAM_NAMES = Object.freeze(['recorder', 'analytics', 'projector', 'evaluation']);
 
 export const SEAM_MIN_STAGE = Object.freeze({
   recorder: 'shadow',
+  analytics: 'shadow',
   projector: 'canary',
   evaluation: 'default',
 });