@ngockhoale/ukit 3.3.2 → 3.4.0

package/template_project/.claude/ukit/index/session-history-extractor.mjs

@@ -0,0 +1,362 @@
+// session-history-extractor.mjs — parity-locked mirror of
+// src/index/sessionHistoryExtractor.js (BL-013). Mirrors never import src/;
+// tests/consistency/sessionHistoryParity.test.js locks the export surface and
+// asserts identical extraction on shared fixtures. Keep logic identical.
+//
+// Reads the transcript tail (<=16KiB by default) carried on hook/bridge payloads
+// (`transcriptPath`, ukit-bridge.js:217,228) and emits bounded counters/enums:
+//
+//   { priorAttemptCount, sameSymptomReask, correctionEvents, fixLoopCount,
+//     degraded, reason? }
+//
+// Detection is deliberately heuristic + bounded (SPEC §14):
+//   * Route markers — any tail entry carrying `requestKey`/`routeFingerprint`
+//     (top-level or nested under route/ukit/metadata/message) is a prior route
+//     record; markers matching the current requestKey OR routeFingerprint count
+//     as prior attempts, and a failure-valued outcome counts a fix-loop round.
+//   * Re-ask — a user entry after the last matched marker (or >=2 matched
+//     markers) means the same route was asked again.
+//   * Corrections — explicit correction markers (`ukit-correction`/`correction`
+//     kinds) plus bounded correction phrasing in user text.
+//
+// Contracts (SPEC FR-001 + §10):
+//   * NEVER THROWS. Missing/unreadable transcript → zeroed struct with
+//     degraded:true + reason; malformed lines are skipped, never fatal.
+//   * BOUNDED: tail-only read (<=maxBytes, hard ceiling 4MiB like
+//     transcript-tail.mjs), counters clamp at 99, ≤50ms wall budget.
+//   * PRIVACY: output is counters/enums only — no transcript text may ever
+//     reach route state, decisions.tsv, or any receipt through this module.
+//
+// Two entry points share one classifier: extractHistorySignals (sync) for
+// callers outside deadline-guarded hook blocks, extractHistorySignalsAsync for
+// the hook path where every fs call must be async (BUG-C21-04 posture — a
+// stalled mount must not park the event loop under an armed deadline).
+
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+
+// SPEC §14: the history extraction bound is a 16KiB tail. The ceiling mirrors
+// transcript-tail.mjs's hard cap so one number describes a UKit tail scan.
+export const DEFAULT_HISTORY_MAX_BYTES = 16 * 1024;
+const HISTORY_MAX_BYTES_CEILING = 4 * 1024 * 1024;
+
+const COUNTER_MAX = 99;
+
+// Outcome fields probed on markers, in priority order. A marker without an
+// outcome field counts as an attempt but never as a failed round.
+const OUTCOME_FIELDS = ['outcome', 'verdict', 'status', 'result'];
+const FAILURE_PATTERN = /fail|error|timeout|abort|crash|block/i;
+
+// Object containers probed for marker keys — top-level plus the bounded nests
+// writers may use. `message` is included so stamped user-prompt entries
+// ({type:'user', message:{content, ukit:{requestKey}}}) still match.
+const MARKER_PROBE_KEYS = ['ukit', 'route', 'routeRecord', 'routeMeta', 'metadata', 'meta', 'message'];
+
+const USER_ENTRY_TYPES = new Set(['user', 'human']);
+const CORRECTION_TYPES = new Set(['ukit-correction', 'correction', 'user-correction']);
+
+// Bounded correction phrasing — explicit pushback patterns only; frustration
+// noise stays out of the counter by design (GAP M12 failure-mode note).
+const CORRECTION_PATTERN = /\b(?:no[,.!]?\s+that'?s|that'?s not|not what i|wrong|you (?:said|did|were|meant)|still (?:fail|failing|broken|wrong|crash|not working)|didn'?t work|incorrect|try again)\b/i;
+
+// User message text is scanned only this far — long pasted diffs/logs in a
+// user entry never extend the classification surface.
+const USER_TEXT_SCAN_CHARS = 4096;
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function nonEmptyString(value) {
+  return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+
+function boundedCap(maxBytes) {
+  const requested = Number.isFinite(maxBytes) && maxBytes > 0
+    ? Math.floor(maxBytes)
+    : DEFAULT_HISTORY_MAX_BYTES;
+  return Math.min(requested, HISTORY_MAX_BYTES_CEILING);
+}
+
+function degradedResult(reason) {
+  return {
+    priorAttemptCount: 0,
+    sameSymptomReask: false,
+    correctionEvents: 0,
+    fixLoopCount: 0,
+    degraded: true,
+    reason,
+  };
+}
+
+function zeroedResult() {
+  return {
+    priorAttemptCount: 0,
+    sameSymptomReask: false,
+    correctionEvents: 0,
+    fixLoopCount: 0,
+    degraded: false,
+  };
+}
+
+function clampCounter(value) {
+  const count = Number.isFinite(value) ? Math.max(0, Math.floor(value)) : 0;
+  return Math.min(count, COUNTER_MAX);
+}
+
+// --- bounded tail read -------------------------------------------------------
+
+// A tail read almost certainly starts mid-record: drop everything before the
+// first complete line. Malformed or non-object lines are skipped — consumers
+// count only well-formed bounded events.
+function tailTextToEntries(text, truncated) {
+  let payload = text;
+  if (truncated) {
+    const firstBreak = payload.indexOf('\n');
+    payload = firstBreak >= 0 ? payload.slice(firstBreak + 1) : '';
+  }
+  const entries = [];
+  for (const line of payload.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      const parsed = JSON.parse(trimmed);
+      if (isPlainObject(parsed)) entries.push(parsed);
+    } catch {
+      // partial/corrupt line — skipped, never fatal
+    }
+  }
+  return entries;
+}
+
+async function readTailEntriesAsync(filePath, cap) {
+  const stat = await fsp.stat(filePath);
+  if (!stat.isFile()) {
+    throw new Error('not-a-file');
+  }
+  if (stat.size <= 0) {
+    return { entries: [], bytesRead: 0 };
+  }
+  const start = Math.max(0, stat.size - cap);
+  const length = Math.min(cap, stat.size);
+  const buffer = Buffer.allocUnsafe(length);
+  const handle = await fsp.open(filePath, 'r');
+  let bytesRead = 0;
+  try {
+    const result = await handle.read(buffer, 0, length, start);
+    bytesRead = result.bytesRead;
+  } finally {
+    try { await handle.close(); } catch {}
+  }
+  return {
+    entries: tailTextToEntries(buffer.toString('utf8', 0, bytesRead), start > 0),
+    bytesRead,
+  };
+}
+
+function readTailEntriesSync(filePath, cap) {
+  const stat = fs.statSync(filePath);
+  if (!stat.isFile()) {
+    throw new Error('not-a-file');
+  }
+  if (stat.size <= 0) {
+    return { entries: [], bytesRead: 0 };
+  }
+  const start = Math.max(0, stat.size - cap);
+  const length = Math.min(cap, stat.size);
+  const buffer = Buffer.allocUnsafe(length);
+  const fd = fs.openSync(filePath, 'r');
+  let bytesRead = 0;
+  try {
+    bytesRead = fs.readSync(fd, buffer, 0, length, start);
+  } finally {
+    try { fs.closeSync(fd); } catch {}
+  }
+  return {
+    entries: tailTextToEntries(buffer.toString('utf8', 0, bytesRead), start > 0),
+    bytesRead,
+  };
+}
+
+// --- bounded classification --------------------------------------------------
+
+// Probe order for marker keys + outcomes: the entry itself first, then the
+// bounded nests. Returns the first non-empty string found.
+function probeField(entry, names) {
+  if (!isPlainObject(entry)) return null;
+  for (const name of names) {
+    const direct = nonEmptyString(entry[name]);
+    if (direct) return direct;
+  }
+  for (const nestKey of MARKER_PROBE_KEYS) {
+    const nested = entry[nestKey];
+    if (!isPlainObject(nested)) continue;
+    for (const name of names) {
+      const value = nonEmptyString(nested[name]);
+      if (value) return value;
+    }
+  }
+  return null;
+}
+
+function markerKeysOf(entry) {
+  const requestKey = probeField(entry, ['requestKey']);
+  const routeFingerprint = probeField(entry, ['routeFingerprint', 'fingerprint']);
+  return requestKey || routeFingerprint ? { requestKey, routeFingerprint } : null;
+}
+
+function markerOutcome(entry) {
+  return probeField(entry, OUTCOME_FIELDS);
+}
+
+function isFailedOutcome(outcome) {
+  return typeof outcome === 'string' && FAILURE_PATTERN.test(outcome);
+}
+
+function isCorrectionMarker(entry) {
+  if (!isPlainObject(entry)) return false;
+  if (CORRECTION_TYPES.has(entry.type)) return true;
+  if (entry.event === 'correction' || entry.kind === 'correction') return true;
+  if (isPlainObject(entry.event) && entry.event.kind === 'correction') return true;
+  if (isPlainObject(entry.ukit) && entry.ukit.kind === 'correction') return true;
+  return false;
+}
+
+function isUserEntry(entry) {
+  if (!isPlainObject(entry)) return false;
+  if (USER_ENTRY_TYPES.has(entry.type)) return true;
+  if (isPlainObject(entry.message) && entry.message.role === 'user') return true;
+  return false;
+}
+
+// Bounded user text: string content, or the text blocks of a content array.
+// Tool-result/thinking blocks are ignored — only user-authored text feeds the
+// correction heuristic.
+function userTextOf(entry) {
+  if (!isUserEntry(entry)) return null;
+  const content = entry.message?.content ?? entry.text ?? entry.content;
+  let text = '';
+  if (typeof content === 'string') {
+    text = content;
+  } else if (Array.isArray(content)) {
+    text = content
+      .map((block) => (isPlainObject(block) && block.type === 'text' ? String(block.text ?? '') : ''))
+      .filter(Boolean)
+      .join('\n');
+  }
+  return text ? text.slice(0, USER_TEXT_SCAN_CHARS) : null;
+}
+
+function computeHistorySignals(entries, { routeFingerprint = null, requestKey = null } = {}) {
+  const result = zeroedResult();
+  let attempts = 0;
+  let failedAttempts = 0;
+  let corrections = 0;
+  let lastMatchedIndex = -1;
+  let userAfterLastMatch = false;
+
+  entries.forEach((entry, index) => {
+    const marker = markerKeysOf(entry);
+    if (marker) {
+      const matches = Boolean(
+        (marker.requestKey && requestKey && marker.requestKey === requestKey)
+        || (marker.routeFingerprint && routeFingerprint && marker.routeFingerprint === routeFingerprint),
+      );
+      if (matches) {
+        attempts += 1;
+        lastMatchedIndex = index;
+        if (isFailedOutcome(markerOutcome(entry))) {
+          failedAttempts += 1;
+        }
+      }
+    }
+
+    const userText = userTextOf(entry);
+    if (isCorrectionMarker(entry) || (userText !== null && CORRECTION_PATTERN.test(userText))) {
+      corrections += 1;
+    }
+
+    if (lastMatchedIndex >= 0 && index > lastMatchedIndex && userText !== null) {
+      userAfterLastMatch = true;
+    }
+  });
+
+  result.priorAttemptCount = clampCounter(attempts);
+  result.fixLoopCount = clampCounter(failedAttempts);
+  result.correctionEvents = clampCounter(corrections);
+  // A re-ask on the same route shape: either the route resolved more than once
+  // in the tail, or a user prompt followed the last matched attempt (the
+  // current prompt is appended before the hook runs).
+  result.sameSymptomReask = attempts > 0 && (attempts >= 2 || userAfterLastMatch);
+  return result;
+}
+
+// --- public contract ---------------------------------------------------------
+
+// Coerce arbitrary input into the historySignals route-field shape. Non-object
+// input yields null so callers can emit the additive nullable field honestly.
+export function normalizeHistorySignals(value) {
+  if (!isPlainObject(value)) return null;
+  const normalized = {
+    priorAttemptCount: clampCounter(value.priorAttemptCount),
+    sameSymptomReask: Boolean(value.sameSymptomReask),
+    correctionEvents: clampCounter(value.correctionEvents),
+    fixLoopCount: clampCounter(value.fixLoopCount),
+    degraded: Boolean(value.degraded),
+  };
+  const reason = nonEmptyString(value.reason);
+  if (reason) normalized.reason = reason.slice(0, 120);
+  return normalized;
+}
+
+// SPEC §8: extractHistorySignals({transcriptPath, routeFingerprint, requestKey,
+// maxBytes?}) → bounded counters, never throws. Sync reader — the ≤50ms wall
+// budget assumes a healthy filesystem; deadline-guarded hook code must use the
+// async twin so a stalled mount cannot park the event loop.
+export function extractHistorySignals({
+  transcriptPath,
+  routeFingerprint = null,
+  requestKey = null,
+  maxBytes,
+} = {}) {
+  try {
+    const normalizedPath = nonEmptyString(transcriptPath);
+    if (!normalizedPath) {
+      return degradedResult('missing-transcript-path');
+    }
+    let tail;
+    try {
+      tail = readTailEntriesSync(normalizedPath, boundedCap(maxBytes));
+    } catch {
+      return degradedResult('transcript-unreadable');
+    }
+    return computeHistorySignals(tail.entries, { routeFingerprint, requestKey });
+  } catch {
+    return degradedResult('extract-failed');
+  }
+}
+
+// Async twin of extractHistorySignals — identical classification, fsp-based
+// bounded read for deadline-guarded hook code (skill-router.sh).
+export async function extractHistorySignalsAsync({
+  transcriptPath,
+  routeFingerprint = null,
+  requestKey = null,
+  maxBytes,
+} = {}) {
+  try {
+    const normalizedPath = nonEmptyString(transcriptPath);
+    if (!normalizedPath) {
+      return degradedResult('missing-transcript-path');
+    }
+    let tail;
+    try {
+      tail = await readTailEntriesAsync(normalizedPath, boundedCap(maxBytes));
+    } catch {
+      return degradedResult('transcript-unreadable');
+    }
+    return computeHistorySignals(tail.entries, { routeFingerprint, requestKey });
+  } catch {
+    return degradedResult('extract-failed');
+  }
+}

package/template_project/.claude/ukit/index/tier-selection.mjs

@@ -0,0 +1,309 @@
+// tier-selection.mjs — installed mirror of src/index/tierSelection.js.
+// Measured reliability → tier selection (C86 BL-019, SPEC FR-001 §5/§7/§8/§14).
+//
+// modelTier stops being purely static: the route-audit ↔ exec-ledger join
+// (BL-003/004/007) produces measured per-(execution-mode, tier) reliability,
+// every route logs the measured pick vs the static pick as a `tier-selection`
+// shadow receipt, and the measured map becomes authoritative ONLY when the
+// promotion gates pass (≥50 joined routes, ≥60% agreement, disagreements skew
+// cheaper, no verdict regression). Thin data → the static map stays.
+//
+// Boundary rules (SPEC §14, ARCH §Safety Boundary):
+//   * Tier names only — 'lite'|'code'|'smart'. A model ID in the artifact is
+//     dropped at read time so it can never reach a route field or receipt.
+//   * `modelRoles` config is never written — the measured map is derived state
+//     under .ukit/storage/cache/, not user configuration.
+//   * handoff-model-guard.sh enforcement is unchanged (not touched here).
+//
+// Mirror parity: template_project/.claude/ukit/index/tier-selection.mjs
+// carries the identical logic (the mirror cannot import src/). Both twins are
+// locked by tests/consistency/tierSelectionParity.test.js.
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+// Provider-neutral cost-tier vocabulary — literal mirror of the
+// lite→code→smart ladder in src/core/executionContracts.js (MODEL_TIER_ORDER).
+export const MEASURED_TIER_ORDER = Object.freeze(['lite', 'code', 'smart']);
+
+// Derived cache artifact (SPEC §7): metrics/diagnostics writes, router reads.
+export const TIER_MAP_PATH_REL = path.join('.ukit', 'storage', 'cache', 'tier-map.json');
+
+// Executor-decided defaults (task Discussion): a conservative reliability
+// floor so a cheap-but-flaky tier never displaces a reliable one, and a 24h
+// artifact TTL so a stale promote cannot silently own routing forever.
+const DEFAULT_RELIABILITY_FLOOR = 0.8;
+const TIER_MAP_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+
+const PROMOTION_REASONS = Object.freeze({
+  thin: 'joined<50',
+  agreement: 'agreement<0.6',
+  skew: 'disagreements-not-cheaper',
+});
+
+function tierName(value) {
+  return MEASURED_TIER_ORDER.includes(value) ? value : null;
+}
+
+// One joined row is either the {audit, ledger} pair collectRouteOutcomes
+// emits or a flat {executionMode, modelTier, writeSucceeded} row — both are
+// normalized here so callers never have to care which shape arrived.
+function normalizeJoinedRow(row) {
+  if (!row || typeof row !== 'object' || Array.isArray(row)) return null;
+  const audit = row.audit && typeof row.audit === 'object' ? row.audit : row;
+  const ledger = row.ledger && typeof row.ledger === 'object' ? row.ledger : row;
+  // An empty object is not a joined row — nothing identifiable to count.
+  if (Object.keys(audit).length === 0) return null;
+  return { audit, ledger };
+}
+
+// SPEC §8: deriveTierStats(joinedRows) → { byModeTier, joinedRoutes }.
+// byModeTier is "<mode>|<tier>"-keyed; `routes` counts joined rows where the
+// route ran on that tier, `successes` counts writeSucceeded === true (the
+// ledger outcome the existing byMode buckets already count), `reliability`
+// is successes/routes. Rows without a provider-neutral tier name are counted
+// in joinedRoutes (coverage) but never land in a tier bucket — a model ID
+// must not create a pseudo-tier.
+export function deriveTierStats(joinedRows = []) {
+  const byModeTier = {};
+  const rows = Array.isArray(joinedRows) ? joinedRows : [];
+  let joinedRoutes = 0;
+  for (const raw of rows) {
+    const normalized = normalizeJoinedRow(raw);
+    if (!normalized) continue;
+    joinedRoutes += 1;
+    const mode = typeof normalized.audit.executionMode === 'string'
+      ? normalized.audit.executionMode
+      : null;
+    const tier = tierName(normalized.audit.modelTier);
+    if (!mode || !tier) continue;
+    const key = `${mode}|${tier}`;
+    const bucket = byModeTier[key] ??= { routes: 0, successes: 0, reliability: 0 };
+    bucket.routes += 1;
+    if (normalized.ledger.writeSucceeded === true) bucket.successes += 1;
+    bucket.reliability = bucket.successes / bucket.routes;
+  }
+  return { byModeTier, joinedRoutes };
+}
+
+// SPEC §8: resolveMeasuredTier({executionMode, staticTier, stats,
+// reliabilityFloor?}) → tier name | null. Cheapest tier whose measured
+// reliability for that mode meets the floor; null when the data is thin or
+// absent. `staticTier` rides the signature per SPEC but does not bias the
+// pick — the measured table decides on its own.
+export function resolveMeasuredTier({
+  executionMode = null,
+  staticTier = null,
+  stats = null,
+  reliabilityFloor = DEFAULT_RELIABILITY_FLOOR,
+} = {}) {
+  if (!executionMode || !stats || typeof stats !== 'object') return null;
+  const floor = Number.isFinite(reliabilityFloor)
+    ? reliabilityFloor
+    : DEFAULT_RELIABILITY_FLOOR;
+  const byModeTier = stats.byModeTier ?? {};
+  for (const tier of MEASURED_TIER_ORDER) {
+    const bucket = byModeTier[`${executionMode}|${tier}`];
+    if (bucket && bucket.routes >= 1 && bucket.reliability >= floor) {
+      return tier;
+    }
+  }
+  return null;
+}
+
+// SPEC §8/§14: evaluateTierPromotion({stats, staticMap, minJoined?=50,
+// minAgreement?=0.60}) → {decision, agreement, cheaperShare, regressionFree,
+// reasons[], byMode, joinedRoutes}.
+//
+// Promote only when ALL gates pass:
+//   * joined ≥ minJoined (default 50 joined route↔outcome rows);
+//   * agreement ≥ minAgreement — the measured pick equals the static pick for
+//     ≥60% of modes where a pick exists;
+//   * disagreements skew cheaper — measured picks that differ must be a
+//     lower rung (cheaperShare = cheaper/disagreements > 0.5; zero
+//     disagreements passes as perfectly agreeing);
+//   * regressionFree — no mode where the measured pick's measured
+//     reliability is lower than the static pick's measured reliability
+//     (a tier-verdict regression, verdict = writeSucceeded reliability).
+// `byMode` carries the measured pick per mode for the artifact; modes with
+// no pick fall back to static at read time.
+export function evaluateTierPromotion({
+  stats = null,
+  staticMap = {},
+  minJoined = 50,
+  minAgreement = 0.60,
+  reliabilityFloor = DEFAULT_RELIABILITY_FLOOR,
+} = {}) {
+  const byModeTier = stats?.byModeTier ?? {};
+  const joinedRoutes = Number.isFinite(stats?.joinedRoutes) ? stats.joinedRoutes : 0;
+  const modes = Object.keys(staticMap && typeof staticMap === 'object' ? staticMap : {});
+  const byMode = {};
+
+  let compared = 0;
+  let agreed = 0;
+  let disagreements = 0;
+  let cheaper = 0;
+  const regressedModes = [];
+
+  for (const mode of modes) {
+    const staticTier = staticMap[mode];
+    const measured = resolveMeasuredTier({
+      executionMode: mode,
+      staticTier,
+      stats,
+      reliabilityFloor,
+    });
+    if (measured !== null) byMode[mode] = measured;
+    if (!tierName(staticTier) || measured === null) continue;
+    compared += 1;
+    if (measured === staticTier) {
+      agreed += 1;
+      continue;
+    }
+    disagreements += 1;
+    const measuredIdx = MEASURED_TIER_ORDER.indexOf(measured);
+    const staticIdx = MEASURED_TIER_ORDER.indexOf(staticTier);
+    if (measuredIdx !== -1 && staticIdx !== -1 && measuredIdx < staticIdx) {
+      cheaper += 1;
+    }
+    const measuredRel = byModeTier[`${mode}|${measured}`]?.reliability;
+    const staticRel = byModeTier[`${mode}|${staticTier}`]?.reliability;
+    if (Number.isFinite(measuredRel) && Number.isFinite(staticRel) && measuredRel < staticRel) {
+      regressedModes.push(mode);
+    }
+  }
+
+  const agreement = compared > 0 ? agreed / compared : 0;
+  const cheaperShare = disagreements > 0 ? cheaper / disagreements : 1;
+  const regressionFree = regressedModes.length === 0;
+
+  const reasons = [];
+  if (!(joinedRoutes >= minJoined)) reasons.push(PROMOTION_REASONS.thin);
+  if (!(agreement >= minAgreement)) reasons.push(PROMOTION_REASONS.agreement);
+  if (!(cheaperShare > 0.5)) reasons.push(PROMOTION_REASONS.skew);
+  for (const mode of regressedModes) reasons.push(`regression:${mode}`);
+
+  return {
+    decision: reasons.length === 0 ? 'promote' : 'hold',
+    agreement,
+    cheaperShare,
+    regressionFree,
+    reasons,
+    byMode,
+    joinedRoutes,
+  };
+}
+
+// SPEC §7: { version: 1, derivedAt, joinedRoutes, agreement, decision,
+// byMode: {<mode>: <tier>} } — plus cheaperShare/reasons for the metrics
+// rollup (additive, bounded enums/numbers only).
+export function buildTierMapArtifact({
+  stats = null,
+  staticMap = {},
+  minJoined = 50,
+  minAgreement = 0.60,
+  now = () => new Date(),
+} = {}) {
+  const evaluation = evaluateTierPromotion({ stats, staticMap, minJoined, minAgreement });
+  return {
+    version: 1,
+    derivedAt: now().toISOString(),
+    joinedRoutes: evaluation.joinedRoutes,
+    agreement: evaluation.agreement,
+    decision: evaluation.decision,
+    byMode: evaluation.byMode,
+    cheaperShare: evaluation.cheaperShare,
+    regressionFree: evaluation.regressionFree,
+    reasons: evaluation.reasons,
+  };
+}
+
+// Atomic tmp+rename write — same discipline as route-audit/state writes so a
+// reader never sees a torn artifact. Advisory: a write failure returns
+// {written:false}, never throws (metrics must stay read-mostly-safe).
+export async function writeTierMap(projectRoot, artifact) {
+  try {
+    const filePath = path.join(projectRoot, TIER_MAP_PATH_REL);
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    const tempPath = `${filePath}.tmp-${process.pid}-${crypto.randomBytes(6).toString('hex')}`;
+    try {
+      await fs.writeFile(tempPath, JSON.stringify(artifact, null, 2), 'utf8');
+      await fs.rename(tempPath, filePath);
+    } catch (error) {
+      try { await fs.rm(tempPath, { force: true }); } catch { /* best effort */ }
+      throw error;
+    }
+    return { written: true, path: filePath };
+  } catch (error) {
+    return { written: false, error: error?.message ?? String(error) };
+  }
+}
+
+// SPEC §8: loadTierMap(projectRoot) → TierMap|null. Absent, corrupt, wrong
+// version, invalid decision, or stale (derivedAt older than the 24h TTL) →
+// null so the static map stays authoritative. byMode values are filtered to
+// the tier vocabulary — anything else (e.g. a model ID) is dropped so it can
+// never reach a route field or receipt.
+export async function loadTierMap(projectRoot, { now = () => Date.now() } = {}) {
+  try {
+    const filePath = path.join(projectRoot, TIER_MAP_PATH_REL);
+    const doc = JSON.parse(await fs.readFile(filePath, 'utf8'));
+    if (!doc || typeof doc !== 'object' || doc.version !== 1) return null;
+    if (doc.decision !== 'promote' && doc.decision !== 'hold') return null;
+    const derivedAtMs = Date.parse(doc.derivedAt ?? '');
+    if (!Number.isFinite(derivedAtMs)) return null;
+    if (now() - derivedAtMs > TIER_MAP_MAX_AGE_MS) return null;
+    const byMode = {};
+    if (doc.byMode && typeof doc.byMode === 'object') {
+      for (const [mode, tier] of Object.entries(doc.byMode)) {
+        const name = tierName(tier);
+        if (name) byMode[mode] = name;
+      }
+    }
+    return {
+      version: 1,
+      derivedAt: doc.derivedAt,
+      joinedRoutes: Number.isFinite(doc.joinedRoutes) ? doc.joinedRoutes : 0,
+      agreement: Number.isFinite(doc.agreement) ? doc.agreement : 0,
+      decision: doc.decision,
+      byMode,
+      ...(Number.isFinite(doc.cheaperShare) ? { cheaperShare: doc.cheaperShare } : {}),
+      ...(Array.isArray(doc.reasons) ? { reasons: doc.reasons.filter((r) => typeof r === 'string') } : {}),
+    };
+  } catch {
+    return null;
+  }
+}
+
+// Route-side emission (SPEC §5 FR-001): folds the persisted measured map into
+// a route summary. Sets the additive `measuredTier` field (nullable — null
+// when data is thin or promotion is off) and, ONLY when the persisted map
+// says 'promote' AND a pick exists for this mode, overrides the authoritative
+// executionContract.modelTier with the measured tier. Never throws; absent or
+// invalid input leaves the static map authoritative.
+//
+// Returns { map, staticTier, measuredPick, promoted } — `measuredPick` is the
+// raw map pick (logged on the A/B receipt even on hold), `promoted` whether
+// the measured pick took over modelTier.
+export async function applyMeasuredTier({
+  projectRoot = process.cwd(),
+  routeSummary = null,
+  tierMap = undefined,
+} = {}) {
+  const map = tierMap !== undefined ? tierMap : await loadTierMap(projectRoot);
+  if (!routeSummary || typeof routeSummary !== 'object') {
+    return { map, staticTier: null, measuredPick: null, promoted: false };
+  }
+  const executionMode = routeSummary.executionMode ?? null;
+  const staticTier = routeSummary.executionContract?.modelTier ?? null;
+  const pick = map?.byMode?.[executionMode] ?? null;
+  const measuredPick = tierName(pick);
+  const promoted = map?.decision === 'promote' && measuredPick !== null;
+
+  routeSummary.measuredTier = promoted ? measuredPick : null;
+  if (promoted && routeSummary.executionContract && typeof routeSummary.executionContract === 'object') {
+    routeSummary.executionContract.modelTier = measuredPick;
+  }
+  return { map, staticTier, measuredPick, promoted };
+}