@ngockhoale/ukit 3.3.2 → 3.4.0

package/src/index/routeResolver.js

@@ -0,0 +1,915 @@
+// routeResolver.js — shared route resolver (C84 TASK-004, BL-006).
+//
+// One resolver computes the rich route fields for both router surfaces: the
+// in-process canonical path (taskRouting.js → this module) and the installed
+// hook path (skill-router.sh → route-resolver.mjs via pathToFileURL). Before
+// this module the hook re-implemented the pipeline and emitted zero
+// rigor/fastPath/riskFloor/resumable/decision-shadow fields — the router
+// split-brain documented in GAP M03 / GTA §2 KEY FINDING.
+//
+// This module is deterministic and performs no IO beyond the config object the
+// caller hands in — run-log/ledger IO (resumable-run emit, decision-plane
+// receipts) stays in the route helpers.
+//
+// Mirror parity: template_project/.claude/ukit/index/route-resolver.mjs carries
+// the identical logic with literal copies of the tables imported below (the
+// mirror cannot import src/). Both twins are locked by
+// tests/consistency/routeResolverParity.test.js.
+
+import crypto from 'node:crypto';
+
+import { buildRouteSignalText } from './languageTools.js';
+import { normalizeHistorySignals } from './sessionHistoryExtractor.js';
+import { isSharedImpactFile } from './impactCatalog.js';
+import {
+  EXECUTION_CONTRACTS,
+  EXECUTION_MODE_ORDER,
+  MODEL_TIER_BY_CONTRACT,
+  ROUTE_EFFORTS,
+  buildExecutionContract,
+  resolveModelTier,
+} from '../core/executionContracts.js';
+
+export {
+  buildExecutionContract,
+  resolveModelTier,
+  isSharedImpactFile,
+  ROUTE_EFFORTS,
+};
+
+// --- M01.1: additive ResolvedTaskRoute v1 (docs/pstack/CONTRACTS.md C01) -------------------
+// Emitted only when `routing.routeSchema.stage` (runtime config, default "off") is not
+// "off". All fields are additive on top of the existing routeSummary shape — legacy
+// top-level fields are never removed or renamed, so older consumers keep working.
+export const ROUTE_VERSION = 1;
+export const ROUTE_CONTRACT_VERSION = 1;
+export const ROUTE_SCHEMA_STAGES = new Set(['off', 'shadow', 'canary', 'default']);
+export const ROUTE_INTENT_KINDS = new Set(['informational', 'delivery', 'mutation', 'investigation', 'review']);
+export const ROUTE_MUTABILITIES = new Set(['read-only', 'mutating', 'mixed']);
+export const ROUTE_RIGOR_LEVELS = new Set(['R0', 'R1', 'R2', 'R3', 'R4']);
+export const ROUTE_MODEL_TIERS = new Set(['lite', 'code', 'smart']);
+export const ROUTE_RISK_FLOORS = new Set(['none', 'high-risk']);
+// SPEC §5 FR-003: fixed table order — codes are emitted and printed in this order.
+// The first six raise the floor to 'high-risk'; the last two are informational only.
+export const ROUTE_RISK_REASON_CODES = Object.freeze([
+  'security-sensitive',
+  'shared-impact',
+  'public-contract',
+  'schema-change',
+  'destructive-action',
+  'cross-engine',
+  'established-precedent',
+  'explicit-local-target',
+]);
+const ROUTE_RISK_FLOOR_RAISING_CODES = new Set(ROUTE_RISK_REASON_CODES.slice(0, 6));
+const ROUTE_RISK_ENGINES = ['claude code', 'codex', 'omp'];
+
+// FR-004 (M01.3'): Fast Path eligibility vocabulary. The suppressed list is fixed
+// text per SPEC — deliberately not configurable. Reasons are the informational
+// risk codes (the last two ROUTE_RISK_REASON_CODES entries) present on the route.
+const FAST_PATH_MODES = new Set(['tiny-fix', 'local-fix']);
+const FAST_PATH_SUPPRESSED = Object.freeze(['design', 'smart', 'subagents', 'broad-verify']);
+const FAST_PATH_REASON_CODES = new Set(ROUTE_RISK_REASON_CODES.slice(6));
+
+// 'informational' is a real router emission (no completion contract) even though it is
+// not part of the seven-lane EXECUTION_MODE_ORDER ladder.
+export const ROUTE_EXECUTION_MODES = [...EXECUTION_MODE_ORDER, 'informational'];
+const ROUTE_ESCALATION_CEILING = 'review-release';
+const ROUTE_GOAL_MAX_LENGTH = 240;
+
+// Decision-shadow families — the deterministic descriptor attached to resolver
+// output (and the question list the helper path's shadow hook batches). Kept
+// next to the stage resolvers so hook and helper resolve the same stage map.
+// BL-017 (SPEC FR-005): extended families — playbook-select, review-trigger,
+// cross-check-depth, laneDeepening, verificationDepth. They ship at the
+// inherited decision-plane stage (shadow) via resolveDecisionFamilyStage —
+// no runtimeConfig schema change.
+const DECISION_SHADOW_EXTENDED_FAMILIES = [
+  'playbook-select',
+  'review-trigger',
+  'cross-check-depth',
+  'laneDeepening',
+  'verificationDepth',
+  // BL-019 (SPEC FR-001): measured-vs-static tier A/B — same inherited
+  // shadow stage via resolveDecisionFamilyStage, no config schema change.
+  'tier-selection',
+];
+const DECISION_SHADOW_FAMILIES = [
+  'route',
+  'rigor',
+  'resume',
+  'verify',
+  ...DECISION_SHADOW_EXTENDED_FAMILIES,
+];
+// Stage keys treat absence as "off" (MIGRATION_ROLLBACK named-keys table). Unknown or
+// malformed values degrade to "off" — the conservative reading that keeps the route
+// byte-identical to the pre-M01.1 shape.
+export function resolveRouteSchemaStage(config = null) {
+  const stage = config?.routing?.routeSchema?.stage;
+  return ROUTE_SCHEMA_STAGES.has(stage) ? stage : 'off';
+}
+
+// FR-002: generic stage resolver — every routing.<key>.stage shares the same
+// absent/malformed → 'off' contract. resolveRouteSchemaStage stays as the
+// routeSchema-specific spelling of this helper.
+export function resolveRouteStage(config = null, key) {
+  const stage = config?.routing?.[key]?.stage;
+  return ROUTE_SCHEMA_STAGES.has(stage) ? stage : 'off';
+}
+
+// Same absent/malformed → 'off' contract as the routing.* stage resolvers; the
+// stage key lives under continuity.resumableRun (TASK-001 config block).
+export function resolveResumableRunStage(config = null) {
+  const stage = config?.continuity?.resumableRun?.stage;
+  return ROUTE_SCHEMA_STAGES.has(stage) ? stage : 'off';
+}
+
+// decisionPlane stage contract as routing.* stages. `decisionPlane.enabled === false`
+// is the global emergency disable and reads as 'off' regardless of stage keys.
+export function resolveDecisionPlaneStage(config = null) {
+  const plane = config?.decisionPlane;
+  if (!plane || typeof plane !== 'object' || plane.enabled === false) return 'off';
+  return ROUTE_SCHEMA_STAGES.has(plane.stage) ? plane.stage : 'off';
+}
+
+// Per-family override wins over the global stage; absence inherits it.
+export function resolveDecisionFamilyStage(config = null, family) {
+  const globalStage = resolveDecisionPlaneStage(config);
+  const override = config?.decisionPlane?.families?.[family]?.stage;
+  return ROUTE_SCHEMA_STAGES.has(override) ? override : globalStage;
+}
+
+// Route-side shadow questions — mirror of the DECISION_REGISTRY entries owned
+// by taskRouting outside the preflight bundle (src/decision/registry.js).
+// Candidates are protocol-local labels, not user-facing prose.
+export const ROUTE_SHADOW_QUESTIONS = Object.freeze([
+  {
+    decisionKey: 'route.intent-kind.v1',
+    family: 'route',
+    kind: 'choice',
+    instruction: 'Intent kind for the route: informational | mutation | investigation | review | delivery.',
+    candidates: ['informational', 'mutation', 'investigation', 'review', 'delivery'],
+  },
+  {
+    decisionKey: 'route.rigor.v1',
+    family: 'rigor',
+    kind: 'score',
+    instruction: 'R0-R4 rigor recommendation inside deterministic floors.',
+    candidates: ['r0', 'r1', 'r2', 'r3', 'r4'],
+  },
+  {
+    decisionKey: 'resume.next-action.v1',
+    family: 'resume',
+    kind: 'choice',
+    instruction: 'Next resumable action at the continuation boundary.',
+    // deriveNextAction vocabulary (read from source); the rescue-bias override
+    // 'execute-current-milestone' can overwrite nextActionType post-derivation —
+    // baseline compare then scores 'disagree', which is a real signal, not noise.
+    candidates: [
+      'ask-user-confirmation',
+      'run-primary-verification',
+      'run-fallback-verification',
+      'pull-indexed-context',
+      'read-skill-instructions',
+      'inspect-structure',
+    ],
+  },
+  {
+    decisionKey: 'verify.depth.v1',
+    family: 'verify',
+    kind: 'choice',
+    instruction: 'Verification depth among allowed levels.',
+    candidates: ['sanity', 'targeted', 'impact', 'full'],
+  },
+  // BL-017 (SPEC FR-005): the five adopted question families — each a
+  // deterministic candidate set, shipped at the inherited `shadow` stage via
+  // resolveDecisionFamilyStage (no runtimeConfig schema change).
+  {
+    decisionKey: 'playbook.select.v1',
+    family: 'playbook-select',
+    kind: 'choice',
+    instruction: 'Which playbook row should claim this route — a builtin playbookId, or none.',
+    // Built-in playbookId vocabulary (playbook-registry rows whose id is
+    // non-null) + 'none' for unrouted/ambiguous prompts. Deterministic set;
+    // project/user playbooks still resolve via the registry, not this question.
+    candidates: [
+      'small-feature',
+      'feature-implementation',
+      'bug-fix',
+      'investigation',
+      'runtime-forensics',
+      'refactor',
+      'performance',
+      'architecture-decision',
+      'prototype',
+      'migration',
+      'verification',
+      'skill-evaluation',
+      'session-pickup',
+      'autonomous-run',
+      'release',
+      'none',
+    ],
+  },
+  {
+    decisionKey: 'review.trigger.v1',
+    family: 'review-trigger',
+    kind: 'choice',
+    instruction: 'Pre-Stop review-policy action for this route.',
+    // BL-015 five-action enum (evaluateReviewPolicy output vocabulary).
+    candidates: [
+      'finish',
+      'run-targeted-check',
+      'independent-review',
+      'escalate',
+      'inconclusive',
+    ],
+  },
+  {
+    decisionKey: 'crosscheck.depth.v1',
+    family: 'cross-check-depth',
+    kind: 'choice',
+    instruction: 'Adaptive cross-check depth for this route.',
+    // ARCH §Adaptive Cross-Check depth matrix output enum (BL-016).
+    candidates: ['none', 'runnable', 'review-round', 'escalate'],
+  },
+  {
+    decisionKey: 'lane.deepening.v1',
+    family: 'laneDeepening',
+    kind: 'choice',
+    instruction: 'Execution lane after fix-loop escalation deepening.',
+    // ROUTE_EXECUTION_MODES lane vocabulary — BL-018 consumes this question as
+    // the escalation call-out path.
+    candidates: [
+      'tiny-fix',
+      'local-fix',
+      'local-build',
+      'shared-edit',
+      'map-impact',
+      'find-cause',
+      'review-release',
+    ],
+  },
+  {
+    decisionKey: 'verification.depth.v1',
+    family: 'verificationDepth',
+    kind: 'choice',
+    instruction: 'Verification depth for this route.',
+    // ARCH task-contract verificationDepth enum (BL-016 consumer / BL-018
+    // escalation verification lane).
+    candidates: ['none', 'runnable', 'review-round', 'escalate'],
+  },
+  // BL-019 (SPEC FR-001): measured-vs-static tier A/B — the shadow model
+  // scores its pick against the effective baseline (measuredTier or the
+  // static modelTier). 'static' is the "keep the deterministic map" option.
+  {
+    decisionKey: 'tier.selection.v1',
+    family: 'tier-selection',
+    kind: 'choice',
+    instruction: 'Model tier for this route under the measured-reliability map.',
+    candidates: ['lite', 'code', 'smart', 'static'],
+  },
+  // NOT wired — recorded per migration-backlog review:
+  //   capability.impact.v1 — noul kind; no threshold baseline exists on
+  //     routeSummary (capabilityPolicy.recommended is unpopulated upstream), so
+  //     the question has no comparison value.
+  //   learn.candidate-class.v1 — reserved for the memoryV2 `decision` plane
+  //     (memoryFlags.js), not the route boundary.
+]);
+
+// Only families whose resolved stage is not 'off' get a question.
+export function buildShadowDecisionQuestions(config = null) {
+  return ROUTE_SHADOW_QUESTIONS
+    .filter((q) => resolveDecisionFamilyStage(config, q.family) !== 'off')
+    .map(({ family, ...question }) => question);
+}
+
+// FR-003 (M01.2'): derive the additive riskFloor from hard signals. Codes are
+// collected in ROUTE_RISK_REASON_CODES table order; the floor is 'high-risk' iff
+// any of the first six (floor-raising) codes fired — informational codes never
+// raise it. Detectors read the normalized signal text (same source the mode
+// ladder uses) plus the raw target path and context preview.
+export function deriveRiskFloor({
+  promptText = '',
+  commandText = '',
+  targetFile = null,
+  executionMode = null,
+  activeSkillIds = [],
+  contextPreview = null,
+  riskSignals = [],
+} = {}) {
+  const signalText = buildRouteSignalText(promptText, commandText);
+  const target = String(targetFile || '');
+  const skillIds = Array.isArray(activeSkillIds) ? activeSkillIds : [];
+  const codes = [];
+  if (
+    /\b(auth|security|token|permission|secret|credential|password|vulnerab|exploit|xss|injection)\b/i.test(signalText)
+    || skillIds.includes('discover-security')
+  ) {
+    codes.push('security-sensitive');
+  }
+  if (isSharedImpactFile(targetFile) || executionMode === 'shared-edit' || executionMode === 'map-impact') {
+    codes.push('shared-impact');
+  }
+  if (
+    /(^|\/)(package\.json|manifests\/|.*\.d\.ts$|(^|\/)api\/|openapi|swagger)/i.test(target)
+    || /\b(public api|breaking change|api contract|semver)\b/i.test(signalText)
+  ) {
+    codes.push('public-contract');
+  }
+  if (
+    /(^|\/)(migrations?|db|database|prisma|schema)/i.test(target)
+    || /\b(migration|migrate|schema|alter table|add column|drop column)\b/i.test(signalText)
+  ) {
+    codes.push('schema-change');
+  }
+  if (/\b(delete|drop|truncate|destroy|wipe|uninstall|rm -rf|purge)\b/i.test(signalText)) {
+    codes.push('destructive-action');
+  }
+  const engineHits = ROUTE_RISK_ENGINES.filter(
+    (name) => new RegExp(`\\b${name}\\b`, 'i').test(signalText),
+  ).length;
+  if (
+    /\bcross[- ]engine\b|\ball engines\b/i.test(signalText)
+    || engineHits >= 2
+    || /^template_project\/\.(claude|codex|omp)\//i.test(target)
+  ) {
+    codes.push('cross-engine');
+  }
+  if ((contextPreview?.analogFiles?.length ?? 0) > 0 || (contextPreview?.styleFiles?.length ?? 0) > 0) {
+    codes.push('established-precedent');
+  }
+  if (target && !isSharedImpactFile(targetFile)) {
+    codes.push('explicit-local-target');
+  }
+  // TASK-004: externally supplied risk signals merge into the same table order —
+  // invalid codes are ignored, duplicates collapse.
+  const merged = [
+    ...codes,
+    ...(Array.isArray(riskSignals) ? riskSignals : [])
+      .filter((code) => ROUTE_RISK_REASON_CODES.includes(code)),
+  ];
+  const orderedCodes = [...new Set(merged)]
+    .sort((a, b) => ROUTE_RISK_REASON_CODES.indexOf(a) - ROUTE_RISK_REASON_CODES.indexOf(b));
+  return {
+    floor: orderedCodes.some((code) => ROUTE_RISK_FLOOR_RAISING_CODES.has(code)) ? 'high-risk' : 'none',
+    codes: orderedCodes,
+  };
+}
+
+// Route-line segment (FR-003): on 'high-risk' only the floor-raising codes print;
+// on 'none' the informational codes do. Empty list → no segment at all.
+export function formatRiskFloorSegment(riskFloor = null) {
+  if (!riskFloor) {
+    return null;
+  }
+  const printed = riskFloor.floor === 'high-risk'
+    ? riskFloor.codes.filter((code) => ROUTE_RISK_FLOOR_RAISING_CODES.has(code))
+    : riskFloor.codes;
+  return printed.length > 0 ? `risk=${riskFloor.floor}(${printed.join(',')})` : null;
+}
+
+// FR-001 (M01.2' limits fragment): compile the contract's numeric budget keys
+// into an advisory map. Only finite numbers survive — a non-numeric or missing
+// key is simply absent. Zero is a real budget ("no read passes"), never
+// filtered. Same key set as the ceremonyBudget.limits builder below.
+export function deriveCeremonyLimits(executionContract = null) {
+  if (executionContract === null || typeof executionContract !== 'object') {
+    return {};
+  }
+  return Object.fromEntries(
+    ['maxReadPasses', 'maxContextPulls', 'maxReadPassesBeforeReassess']
+      .filter((key) => Number.isFinite(executionContract[key]))
+      .map((key) => [key, executionContract[key]]),
+  );
+}
+
+// Route-line segment (FR-002): fixed reads,ctx,reassess order; only present
+// keys print. Empty/absent map → null so the segment never appears.
+export function formatLimitsSegment(limits = null) {
+  if (limits === null || typeof limits !== 'object') {
+    return null;
+  }
+  const parts = [
+    ['reads', 'maxReadPasses'],
+    ['ctx', 'maxContextPulls'],
+    ['reassess', 'maxReadPassesBeforeReassess'],
+  ]
+    .filter(([, key]) => Number.isFinite(limits[key]))
+    .map(([label, key]) => `${label}:${limits[key]}`);
+  return parts.length > 0 ? `limits=${parts.join(',')}` : null;
+}
+
+// FR-004 (M01.3'): Fast Path eligibility predicate. Returns null when no riskFloor
+// was supplied — eligibility must never be derived without the floor check, so a
+// missing floor means "not computed", not "none". Eligible iff the lane is
+// tiny-fix/local-fix, exactly one local target is known, the floor is 'none',
+// a bounded verification path exists (targeted commands or the tiny-fix
+// 'minimal-or-targeted' contract policy), and the target is not shared-impact.
+export function deriveFastPath({
+  executionMode = null,
+  targetFile = null,
+  riskFloor = null,
+  verificationRecommendation = null,
+  contextPreview = null,
+} = {}) {
+  if (!riskFloor) {
+    return null;
+  }
+  const reasons = (riskFloor.codes ?? []).filter((code) => FAST_PATH_REASON_CODES.has(code));
+  const hasLocalTarget = Boolean(targetFile) || contextPreview?.primaryTargets?.length === 1;
+  const hasBoundedVerification = (verificationRecommendation?.commands?.length ?? 0) > 0
+    || buildExecutionContract(executionMode)?.verificationPolicy === 'minimal-or-targeted';
+  const eligible = FAST_PATH_MODES.has(executionMode)
+    && hasLocalTarget
+    && riskFloor.floor === 'none'
+    && hasBoundedVerification
+    && !isSharedImpactFile(targetFile);
+  return {
+    eligible,
+    suppressed: eligible ? [...FAST_PATH_SUPPRESSED] : [],
+    reasons,
+  };
+}
+
+// Route-line segment (FR-004): emitted only for eligible routes — ineligible
+// routes keep the routeSummary.fastPath field for telemetry but stay silent.
+export function formatFastPathSegment(fastPath = null) {
+  if (!fastPath?.eligible) {
+    return null;
+  }
+  const reasons = fastPath.reasons?.length ? ` (${fastPath.reasons.join(',')})` : '';
+  return `fastPath=on | suppress: ${FAST_PATH_SUPPRESSED.join(',')}${reasons}`;
+}
+
+// A bare delivery command ("push this to git", "đẩy bộ này lên git") performs no
+// repository mutation the ledger could ever receipt. With no edit/review/debug/build
+// signal present, routing it to an investigation lane fabricates write debt and the
+// completion gate then demands an edit that cannot exist. Extracted from
+// deriveExecutionMode so the C01 intent.kind mapping can reuse the identical predicate
+// (delivery-only → 'delivery') instead of duplicating the regexes.
+export function isDeliveryOnlyRequest({ signalText = '', scores = {}, targetFile = null } = {}) {
+  const signalRaw = String(signalText || '').toLowerCase();
+  const deliveryWordSignal = /\bgit\s+push\b/.test(signalRaw)
+    || /\bpush\b[^\n]{0,60}\b(?:git|github|gitlab|remote|origin|repo)\b/.test(signalRaw)
+    || /\b(?:git|github|gitlab|remote|origin|repo)\b[^\n]{0,60}\bpush\b/.test(signalRaw)
+    || /\bday\b(?:\s+\S+){0,3}?\s+len\b/.test(signalRaw);
+  return deliveryWordSignal
+    && scores.editCertainty === 0
+    && !scores.implementSignal
+    && !scores.reviewSignal
+    && !scores.debugSignal
+    && !scores.failureSignal
+    && !scores.impactSignal
+    && !scores.buildSignal
+    && !scores.directTransformSignal
+    && !scores.smallFixSignal
+    && !scores.sharedRisk
+    && !targetFile;
+}
+
+// @decision-point route.intent-kind.v1 — intent kind is a registered
+// consequential decision (DECISION_REGISTRY); this deterministic mapping is
+// its fallback policy implementation.
+// CONTRACTS.md "Intent vocabulary mapping": taskType informs mode priors, not
+// intent.kind; intentMode maps to kind as question/explanation → informational,
+// ship/deliver → delivery, code change → mutation, root-cause/diagnosis →
+// investigation, review/audit → review.
+function deriveRouteIntentKind({ executionMode = null, intentMode = null, deliveryOnly = false } = {}) {
+  if (executionMode === 'find-cause') return 'investigation';
+  if (executionMode === 'review-release') return 'review';
+  if (executionMode === 'informational') return deliveryOnly ? 'delivery' : 'informational';
+  if (executionMode) return 'mutation';
+  if (intentMode === 'review-specific') return 'review';
+  if (intentMode === 'debug-specific') return 'investigation';
+  if (intentMode === 'implement-specific' || intentMode === 'docs-specific') return 'mutation';
+  return 'informational';
+}
+
+// Existing read-only vs mutating classification: only the informational lane carries
+// no write debt; every contract lane is mutating.
+function deriveRouteMutability(executionMode = null) {
+  return executionMode && executionMode !== 'informational' ? 'mutating' : 'read-only';
+}
+
+function compactRouteGoal(text = '') {
+  const goal = String(text || '').trim();
+  if (!goal) return null;
+  return goal.length > ROUTE_GOAL_MAX_LENGTH ? `${goal.slice(0, ROUTE_GOAL_MAX_LENGTH)}…` : goal;
+}
+
+function unique(values) {
+  return [...new Set(values.filter(Boolean))];
+}
+
+// Completion contract for a lane. Informational routes carry no completion debt;
+// every contract lane returns the still-missing evidence classes plus a reason.
+export function buildCompletionState({ executionMode = null, verificationRecommendation = null } = {}) {
+  if (!executionMode || executionMode === 'informational') {
+    return null;
+  }
+
+  const contract = buildExecutionContract(executionMode);
+  const missingEvidence = [...(contract?.completionEvidence ?? [])];
+  const requiresVerification = missingEvidence.includes('verification-evidence');
+  if (
+    requiresVerification
+    && verificationRecommendation
+    && !(verificationRecommendation.commands?.length || verificationRecommendation.fallbackCommands?.length)
+  ) {
+    missingEvidence.push('verification-plan');
+  }
+
+  let reason = 'completion evidence is still required';
+  if (['tiny-fix', 'local-fix', 'local-build', 'shared-edit'].includes(executionMode)) {
+    reason = 'implement request has not produced an edit yet';
+  } else if (executionMode === 'review-release') {
+    reason = 'review/release evidence is still required before final claim';
+  } else if (executionMode === 'map-impact') {
+    reason = 'impact evidence is still required before safe completion claim';
+  }
+
+  return {
+    claimAllowed: false,
+    missingEvidence,
+    reason,
+  };
+}
+
+// Builds the additive C01 groups for one resolved route. rigor stays null until
+// M01.2 derives it; ceremonyBudget/capabilityPolicy are empty shaped objects M02/M01.2
+// populate; escalation.current mirrors the selected mode.
+export function buildResolvedRouteFields({
+  routingContext = {},
+  activeSkillIds = [],
+  executionMode = null,
+  executionContract = null,
+  completionState = null,
+  riskFloor = null,
+  escalationTriggers = [],
+} = {}) {
+  // Decision table v2 (FR-001/FR-002): tier + effort resolve together from the
+  // contract lane and the additive riskFloor. The router cannot observe host
+  // binding capabilities, so the emitted pair is advisory text by definition.
+  const tierDecision = resolveModelTier({ executionMode, riskFloor });
+  const signalText = buildRouteSignalText(routingContext.promptText, routingContext.commandText);
+  const deliveryOnly = isDeliveryOnlyRequest({
+    signalText,
+    scores: routingContext.executionScores ?? {},
+    targetFile: routingContext.targetFile ?? null,
+  });
+  return {
+    routeVersion: ROUTE_VERSION,
+    intent: {
+      kind: deriveRouteIntentKind({
+        executionMode,
+        intentMode: routingContext.intentMode ?? null,
+        deliveryOnly,
+      }),
+      mutability: deriveRouteMutability(executionMode),
+      goal: compactRouteGoal(routingContext.lastExplicitUserPromptText ?? routingContext.promptText),
+      doneConditions: [],
+    },
+    execution: {
+      mode: executionMode,
+      rigor: null,
+      riskFloor: riskFloor?.floor ?? null,
+      phase: null,
+      contractVersion: ROUTE_CONTRACT_VERSION,
+      modelTier: tierDecision.tier,
+      effort: tierDecision.effort,
+    },
+    evidence: {
+      observations: [],
+      riskSignals: riskFloor?.codes ?? [],
+      activationReasons: [],
+      suppressionReasons: [],
+      completionRequirements: unique(completionState?.missingEvidence ?? []),
+    },
+    ceremonyBudget: {
+      policyVersion: ROUTE_CONTRACT_VERSION,
+      rigor: null,
+      limits: riskFloor
+        ? Object.fromEntries(
+            ['maxReadPasses', 'maxContextPulls', 'maxReadPassesBeforeReassess']
+              .filter((key) => typeof executionContract?.[key] === 'number')
+              .map((key) => [key, executionContract[key]]),
+          )
+        : {},
+      consumed: {},
+      exceptions: [],
+    },
+    capabilityPolicy: {
+      policyVersion: ROUTE_CONTRACT_VERSION,
+      required: [],
+      recommended: [],
+      suppressed: [],
+      activeSkillIds: unique(activeSkillIds),
+    },
+    escalation: {
+      current: { mode: executionMode, rigor: null },
+      ceiling: ROUTE_ESCALATION_CEILING,
+      triggers: unique(escalationTriggers),
+      history: [],
+    },
+  };
+}
+
+// Plain-JS validator for the additive C01 groups. Returns { valid, errors }; it never
+// throws and never inspects legacy fields — old consumers may carry anything else.
+export function validateResolvedRoute(route = null) {
+  const errors = [];
+  const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+  if (!isObject(route)) {
+    return { valid: false, errors: ['route must be an object.'] };
+  }
+  if (route.routeVersion !== ROUTE_VERSION) {
+    errors.push(`routeVersion must be ${ROUTE_VERSION}.`);
+  }
+  if (!isObject(route.intent)) {
+    errors.push('intent must be an object.');
+  } else {
+    if (!ROUTE_INTENT_KINDS.has(route.intent.kind)) {
+      errors.push(`intent.kind must be one of: ${[...ROUTE_INTENT_KINDS].join(', ')}.`);
+    }
+    if (!ROUTE_MUTABILITIES.has(route.intent.mutability)) {
+      errors.push(`intent.mutability must be one of: ${[...ROUTE_MUTABILITIES].join(', ')}.`);
+    }
+    if (route.intent.goal !== null && typeof route.intent.goal !== 'string') {
+      errors.push('intent.goal must be a string or null.');
+    }
+    if (!Array.isArray(route.intent.doneConditions)) {
+      errors.push('intent.doneConditions must be an array.');
+    }
+  }
+  if (!isObject(route.execution)) {
+    errors.push('execution must be an object.');
+  } else {
+    if (route.execution.mode !== null && !ROUTE_EXECUTION_MODES.includes(route.execution.mode)) {
+      errors.push(`execution.mode must be null or one of: ${ROUTE_EXECUTION_MODES.join(', ')}.`);
+    }
+    if (route.execution.rigor !== null && !ROUTE_RIGOR_LEVELS.has(route.execution.rigor)) {
+      errors.push(`execution.rigor must be null or one of: ${[...ROUTE_RIGOR_LEVELS].join(', ')}.`);
+    }
+    if (route.execution.riskFloor !== null && !ROUTE_RISK_FLOORS.has(route.execution.riskFloor)) {
+      errors.push(`execution.riskFloor must be null or one of: ${[...ROUTE_RISK_FLOORS].join(', ')}.`);
+    }
+    if (route.execution.contractVersion !== ROUTE_CONTRACT_VERSION) {
+      errors.push(`execution.contractVersion must be ${ROUTE_CONTRACT_VERSION}.`);
+    }
+    if (route.execution.modelTier !== null && !ROUTE_MODEL_TIERS.has(route.execution.modelTier)) {
+      errors.push(`execution.modelTier must be null or one of: ${[...ROUTE_MODEL_TIERS].join(', ')}.`);
+    }
+    if (route.execution.effort !== null && route.execution.effort !== undefined
+      && !ROUTE_EFFORTS.has(route.execution.effort)) {
+      errors.push(`execution.effort must be null or one of: ${[...ROUTE_EFFORTS].join(', ')}.`);
+    }
+  }
+  if (!isObject(route.evidence)) {
+    errors.push('evidence must be an object.');
+  } else {
+    for (const key of ['observations', 'riskSignals', 'activationReasons', 'suppressionReasons', 'completionRequirements']) {
+      if (!Array.isArray(route.evidence[key])) {
+        errors.push(`evidence.${key} must be an array.`);
+      }
+    }
+    if (Array.isArray(route.evidence.riskSignals)
+      && route.evidence.riskSignals.some(
+        (code) => typeof code !== 'string' || !ROUTE_RISK_REASON_CODES.includes(code),
+      )) {
+      errors.push(`evidence.riskSignals entries must be one of: ${ROUTE_RISK_REASON_CODES.join(', ')}.`);
+    }
+  }
+  if (!isObject(route.ceremonyBudget)) {
+    errors.push('ceremonyBudget must be an object.');
+  } else {
+    if (route.ceremonyBudget.rigor !== null && !ROUTE_RIGOR_LEVELS.has(route.ceremonyBudget.rigor)) {
+      errors.push(`ceremonyBudget.rigor must be null or one of: ${[...ROUTE_RIGOR_LEVELS].join(', ')}.`);
+    }
+    if (!isObject(route.ceremonyBudget.limits)) {
+      errors.push('ceremonyBudget.limits must be an object.');
+    }
+    if (!isObject(route.ceremonyBudget.consumed)) {
+      errors.push('ceremonyBudget.consumed must be an object.');
+    }
+    if (!Array.isArray(route.ceremonyBudget.exceptions)) {
+      errors.push('ceremonyBudget.exceptions must be an array.');
+    }
+  }
+  if (!isObject(route.capabilityPolicy)) {
+    errors.push('capabilityPolicy must be an object.');
+  } else {
+    for (const key of ['required', 'recommended', 'suppressed', 'activeSkillIds']) {
+      if (!Array.isArray(route.capabilityPolicy[key])) {
+        errors.push(`capabilityPolicy.${key} must be an array.`);
+      }
+    }
+  }
+  if (!isObject(route.escalation)) {
+    errors.push('escalation must be an object.');
+  } else {
+    if (!isObject(route.escalation.current)) {
+      errors.push('escalation.current must be an object.');
+    } else {
+      if (route.escalation.current.mode !== null && !ROUTE_EXECUTION_MODES.includes(route.escalation.current.mode)) {
+        errors.push(`escalation.current.mode must be null or one of: ${ROUTE_EXECUTION_MODES.join(', ')}.`);
+      }
+      if (route.escalation.current.rigor !== null && !ROUTE_RIGOR_LEVELS.has(route.escalation.current.rigor)) {
+        errors.push(`escalation.current.rigor must be null or one of: ${[...ROUTE_RIGOR_LEVELS].join(', ')}.`);
+      }
+    }
+    if (!Array.isArray(route.escalation.triggers)) {
+      errors.push('escalation.triggers must be an array.');
+    }
+    if (!Array.isArray(route.escalation.history)) {
+      errors.push('escalation.history must be an array.');
+    }
+  }
+  return { valid: errors.length === 0, errors };
+}
+
+// Compact serialization whitelist (C01 compatibility rule): adapter/runtime consumers
+// get a bounded view that may omit verbose evidence but never mode, rigor, required
+// completion evidence, or escalation state. Returns null for legacy (stage-off)
+// summaries so compact output stays byte-identical when the schema stage is off.
+export function compactResolvedRoute(routeSummary = null) {
+  if (!routeSummary || typeof routeSummary !== 'object' || routeSummary.routeVersion == null) {
+    return null;
+  }
+  return {
+    routeVersion: routeSummary.routeVersion,
+    intent: routeSummary.intent ?? null,
+    execution: routeSummary.execution ?? null,
+    evidence: {
+      completionRequirements: unique(routeSummary.evidence?.completionRequirements ?? []),
+    },
+    ceremonyBudget: routeSummary.ceremonyBudget ?? null,
+    capabilityPolicy: routeSummary.capabilityPolicy ?? null,
+    escalation: routeSummary.escalation ?? null,
+  };
+}
+
+// The logical task boundary is the explicit user prompt — a new prompt means a
+// new task, so the persisted record resets instead of merging stale plans.
+// Hashed: prompt text never persists (C10 redaction contract).
+export function resumableTaskBoundary(routingContext = {}) {
+  const text = String(
+    routingContext.lastExplicitUserPromptText ?? routingContext.promptText ?? '',
+  ).trim();
+  return text
+    ? crypto.createHash('sha256').update(text).digest('hex').slice(0, 32)
+    : 'no-prompt';
+}
+
+// TASK-007 (BL-009): the escalation-trigger projection the playbook registry's
+// discriminators consume — the floor-raising risk codes that fired, in
+// ROUTE_RISK_REASON_CODES table order. Extracted so both the resolver and the
+// registry derive the identical trigger set from one riskFloor result.
+export function deriveEscalationTriggers(riskFloor = null) {
+  return Array.isArray(riskFloor?.codes)
+    ? riskFloor.codes.filter((code) => ROUTE_RISK_FLOOR_RAISING_CODES.has(code))
+    : [];
+}
+
+// --- TASK-004 (BL-006): the shared resolver entry point -----------------------
+// One call derives the full deterministic field set both router surfaces emit:
+// the helper path folds it into routeSummary inside buildRouteSummary, the hook
+// path merges it into skill-router-state.json + route-audit entries. Same
+// input → same output on every lane — that is the split-brain fix.
+//
+// rigor stays the deterministic rigor level the route emits — null today (no
+// R-derivation exists yet); both paths now agree on null instead of the hook
+// silently omitting the field. `resolved` carries the C01 groups when
+// routeSchema.stage != 'off'. `decisionShadow` is the resolved stage map — the
+// helper's async receipt still rides routeSummary.decisionPlane separately.
+// `resumable` is the deterministic C10 boundary descriptor; the run-record IO
+// stays in emitResumableRun on the helper path.
+export function deriveRouteFields({
+  promptText = '',
+  commandText = '',
+  targetFile = null,
+  intentMode = null,
+  taskType = null,
+  executionMode = null,
+  riskSignals = [],
+  activeSkillIds = [],
+  verificationRecommendation = null,
+  contextPreview = null,
+  executionScores = {},
+  lastExplicitUserPromptText = null,
+  // BL-013: precomputed bounded session-history struct (the caller runs the
+  // extractor — resolution itself stays IO-free). Normalized into the
+  // counters/enums-only shape; non-struct input stays null so the field is
+  // additive-nullable on the route record.
+  historySignals = null,
+  config = null,
+} = {}) {
+  const routingContext = {
+    promptText,
+    commandText,
+    targetFile,
+    intentMode,
+    taskType,
+    executionMode,
+    executionScores,
+    lastExplicitUserPromptText,
+  };
+
+  // FR-003 (M01.2'): riskFloor is emitted whenever ANY of rigor/fastPath/
+  // escalation stages is on — fastPath/escalation consumers read it even when
+  // routeSchema is off. All three off → null, byte-identical route.
+  const riskStageOn = ['rigor', 'fastPath', 'escalation']
+    .some((key) => resolveRouteStage(config, key) !== 'off');
+  const riskFloor = riskStageOn
+    ? deriveRiskFloor({
+        promptText,
+        commandText,
+        targetFile,
+        executionMode,
+        activeSkillIds,
+        contextPreview,
+        riskSignals,
+      })
+    : null;
+
+  // FR-004 (M01.3'): fastPath is emitted whenever its own stage is on — the
+  // field is always set then (eligible or not) so telemetry/harness can read it.
+  const fastPathStage = resolveRouteStage(config, 'fastPath');
+  const fastPath = fastPathStage !== 'off'
+    ? {
+        eligible: false,
+        suppressed: [],
+        reasons: [],
+        ...deriveFastPath({
+          executionMode,
+          targetFile,
+          riskFloor,
+          verificationRecommendation,
+          contextPreview,
+        }),
+        stage: fastPathStage,
+      }
+    : null;
+
+  // Deterministic escalation triggers: the floor-raising codes that fired.
+  // TASK-007's playbook discriminator reads these; history/state-driven
+  // escalation stays in the route helpers.
+  const escalationTriggers = deriveEscalationTriggers(riskFloor);
+
+  // M01.1 C01 groups — present only when routing.routeSchema.stage != 'off'.
+  const executionContract = buildExecutionContract(executionMode);
+  const completionState = buildCompletionState({
+    executionMode,
+    verificationRecommendation,
+  });
+  const resolved = resolveRouteSchemaStage(config) !== 'off'
+    ? buildResolvedRouteFields({
+        routingContext,
+        activeSkillIds,
+        executionMode,
+        executionContract,
+        completionState,
+        riskFloor,
+        escalationTriggers,
+      })
+    : null;
+
+  // M04.1: the deterministic half of the resumable-run emit — stage + task
+  // boundary. The C10 record IO stays in emitResumableRun; the hook surfaces
+  // the identical boundary so ledger rows can correlate both paths.
+  const resumable = {
+    stage: resolveResumableRunStage(config),
+    taskBoundary: resumableTaskBoundary(routingContext),
+  };
+
+  // M07: the resolved decision-plane stage map. The async shadow receipt never
+  // travels through the resolver — only the deterministic stage descriptor.
+  // SPEC §8 names this output key `decisionShadowFields`; consumers surface it
+  // as `decisionShadow`.
+  const decisionShadowFields = {
+    stage: resolveDecisionPlaneStage(config),
+    familyStages: Object.fromEntries(
+      DECISION_SHADOW_FAMILIES.map((family) => [
+        family,
+        resolveDecisionFamilyStage(config, family),
+      ]),
+    ),
+  };
+
+  // BL-013 merge call-site: the bounded counters/enums struct rides the route
+  // record additively — emitted into route state on both surfaces and into the
+  // decisions.tsv feature packet by the route helpers. Null when the caller
+  // has no transcript or supplies a non-struct value.
+  const historySignalsField = normalizeHistorySignals(historySignals);
+
+  return {
+    rigor: resolved?.execution?.rigor ?? null,
+    fastPath,
+    riskFloor,
+    resumable,
+    escalationTriggers,
+    decisionShadowFields,
+    historySignals: historySignalsField,
+    resolved,
+  };
+}