@ngockhoale/ukit 3.0.3 → 3.0.4

package/src/decision/shadow.js

@@ -0,0 +1,281 @@
+/**
+ * shadow.js (TASK-004 / M07)
+ *
+ * Shadow evaluator for the UNIC Decision Agent (SPEC §5 FR-008/FR-009,
+ * UNIC_DECISION_SPEC §15). Runs the atomic preflight batch through the
+ * decision client, compares answers against the deterministic baseline
+ * (decision-table-v2 via buildFallbackPreflight), and emits a REDACTED
+ * receipt — decision keys, probability bands, outcome/latency classes,
+ * fallback codes, agreement counts. The receipt never carries state text,
+ * prompts, source, or secrets.
+ *
+ * Stage contract (decisionPlane.stage, absence = 'off'):
+ *   off             → returns null before any client/transport work (zero cost)
+ *   shadow          → receipt only; deterministic policy stays authoritative
+ *   canary/default  → receipt + validated preflight bundle; blocked/invalid
+ *                     answers degrade to the deterministic fallback bundle
+ * `decisionPlane.enabled === false` is the global emergency disable → null.
+ *
+ * The evaluator never throws: transport outages, malformed responses, and
+ * sensitive-state blocks all surface as typed receipt outcomes so the caller
+ * can fall back to the deterministic route with one bounded diagnostic.
+ */
+
+import { resolveConfigStage } from '../core/runtimeConfig.js';
+import { createDecisionClient, resolveCheckpoint } from './client.js';
+import { classifyLanguage } from './protocol.js';
+import { serializeStatePacket } from './statePacket.js';
+import {
+  PREFLIGHT_DECISION_KEYS,
+  buildPreflightBatch,
+  validatePreflightAnswers,
+  applyPreflight,
+  buildFallbackPreflight,
+} from './preflight.js';
+
+function decisionPlane(config) {
+  const dp = config?.decisionPlane ?? config ?? {};
+  return dp && typeof dp === 'object' ? dp : {};
+}
+
+// Confidence → band. Receipts carry bands, never raw volatile probabilities.
+function probabilityBand(confidence) {
+  if (!Number.isFinite(confidence)) return 'unknown';
+  if (confidence < 0.25) return 'low';
+  if (confidence < 0.5) return 'moderate';
+  if (confidence < 0.75) return 'high';
+  return 'very-high';
+}
+
+// Normalize an agent answer into the same units as the deterministic baseline
+// bundle field it is compared against (score → legend label, capability set
+// label → member list, lease label → integer).
+function answerBaselineValue(answer, candidateMap) {
+  switch (answer.decisionKey) {
+    case 'preflight.rigor.v1': {
+      const legend = candidateMap?.rigor ?? [];
+      return legend[answer.value - 1] ?? null;
+    }
+    case 'preflight.capabilities.v1':
+      return candidateMap?.capabilities?.[answer.value] ?? null;
+    case 'preflight.lease.v1':
+      return Number(answer.value);
+    default:
+      return answer.value;
+  }
+}
+
+function baselineValue(decisionKey, baseline) {
+  switch (decisionKey) {
+    case 'preflight.execution-lane.v1': return baseline.executionLane;
+    case 'preflight.model-role.v1': return baseline.executionModelRole;
+    case 'preflight.reasoning-effort.v1': return baseline.reasoningEffort;
+    case 'preflight.rigor.v1':
+      return typeof baseline.rigor === 'string' ? baseline.rigor.toLowerCase() : baseline.rigor;
+    case 'preflight.capabilities.v1': return baseline.activeCapabilities ?? [];
+    case 'preflight.verification-depth.v1': return baseline.verificationDepth;
+    case 'preflight.lease.v1': return baseline.lease?.granted ?? null;
+    default: return undefined;
+  }
+}
+
+function valuesEqual(a, b) {
+  if (Array.isArray(a) || Array.isArray(b)) {
+    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
+    const sa = [...a].map(String).sort();
+    const sb = [...b].map(String).sort();
+    return sa.every((v, i) => v === sb[i]);
+  }
+  return a === b;
+}
+
+// Per-key agreement of the agent answers with the deterministic baseline.
+// Invalid/missing answers count as 'no-answer', never as disagreement.
+// Only keys actually asked in the batch are scored — buildPreflightBatch drops
+// undecidable questions, and counting them as no-answer would skew the
+// agreement signal with questions the agent never saw.
+function computeAgreement(answers, baseline, candidateMap, askedKeys = PREFLIGHT_DECISION_KEYS) {
+  const agreement = { agree: 0, differ: 0, noAnswer: 0, differingKeys: [] };
+  const byKey = new Map(
+    (Array.isArray(answers) ? answers : [])
+      .filter((a) => a && typeof a.decisionKey === 'string')
+      .map((a) => [a.decisionKey, a]),
+  );
+  for (const key of askedKeys) {
+    const answer = byKey.get(key);
+    if (!answer || answer.validationStatus !== 'valid') {
+      agreement.noAnswer += 1;
+      continue;
+    }
+    const expected = baselineValue(key, baseline);
+    const actual = answerBaselineValue(answer, candidateMap);
+    if (valuesEqual(actual, expected)) {
+      agreement.agree += 1;
+    } else {
+      agreement.differ += 1;
+      agreement.differingKeys.push(key);
+    }
+  }
+  return agreement;
+}
+
+// The evaluator consumes the resolved-route (C01) shape. A legacy summary
+// (routeSchema stage off) lacks the execution/intent groups — normalize the
+// minimal fields so the batch still builds deterministic candidates.
+function normalizeRoute(route) {
+  if (route?.execution && typeof route.execution === 'object') return route;
+  return {
+    intent: { kind: route?.intent?.kind ?? null },
+    execution: {
+      mode: route?.executionMode ?? null,
+      rigor: route?.execution?.rigor ?? null,
+      riskFloor: route?.riskFloor?.floor ?? null,
+      modelTier: route?.execution?.modelTier ?? null,
+    },
+    capabilityPolicy: route?.capabilityPolicy ?? {},
+    evidence: route?.evidence ?? {},
+  };
+}
+
+/**
+ * Run the decision-plane shadow evaluation for one route.
+ *
+ * @param {{route?: object, config?: object, transport?: Function,
+ *          hostCapabilities?: object, env?: object, projectRoot?: string,
+ *          homeDir?: string, now?: Function, deadlineMs?: number}} args
+ *   transport: fetch-compatible injection point (tests); defaults to fetch.
+ *   hostCapabilities: host capability map; defaults to
+ *     config.decisionPlane.hostCapabilities ({} when undeclared).
+ * @returns {Promise<null|{receipt: object, preflight: object|null}>}
+ *   null at stage 'off'/disabled; otherwise the redacted receipt plus the
+ *   applied/fallback preflight bundle for canary+ stages (null at shadow).
+ */
+export async function runShadowDecisions({
+  route = {},
+  config = {},
+  transport,
+  hostCapabilities = null,
+  env,
+  projectRoot,
+  homeDir,
+  now,
+  deadlineMs,
+} = {}) {
+  const dp = decisionPlane(config);
+  const stage = resolveConfigStage({ decisionPlane: dp }, 'decisionPlane.stage');
+  // Zero-cost exits first: no client construction, no transport, no batch.
+  if (stage === 'off' || dp.enabled === false) return null;
+
+  const hosts = hostCapabilities ?? dp.hostCapabilities ?? {};
+  const normalizedRoute = normalizeRoute(route);
+
+  const { batch, candidateMap } = buildPreflightBatch({
+    route: normalizedRoute,
+    hostCapabilities: hosts,
+    config,
+  });
+  // Reclassify over the same input the client uses (state + question text) so
+  // the batch record's checkpoint matches the one the client resolves —
+  // classifying state-only can mislabel a multilingual batch as english.
+  const questionText = (batch.questions ?? [])
+    .map((q) => `${q.decisionKey} ${q.instruction} ${(q.candidates ?? []).join(' ')}`)
+    .join(' ');
+  const languageClass = classifyLanguage(`${serializeStatePacket(batch.statePacket)} ${questionText}`);
+  batch.languageClass = languageClass;
+  batch.checkpoint = resolveCheckpoint(languageClass, config);
+  if (Number.isFinite(deadlineMs)) batch.deadlineMs = deadlineMs;
+
+  const baseline = buildFallbackPreflight({
+    route: normalizedRoute,
+    hostCapabilities: hosts,
+    config,
+  });
+
+  const client = createDecisionClient({
+    config,
+    transport,
+    now,
+    projectRoot,
+    homeDir,
+    env,
+  });
+
+  let result;
+  try {
+    result = await client.requestBatch(batch);
+  } catch {
+    // The client never throws for transport-level failures; anything that
+    // still escapes is an internal fault — same bounded fallback shape.
+    result = { status: 'unavailable', fallbackCode: 'shadow-error', answers: [] };
+  }
+  const answers = Array.isArray(result?.answers) ? result.answers : [];
+
+  const probabilityBands = {};
+  for (const answer of answers) {
+    // Only canonical keys land in the receipt — model-authored unknown
+    // tool-call names must never become receipt keys (they ride
+    // routeSummary.decisionPlane into printed diagnostics).
+    if (typeof answer?.decisionKey === 'string' && PREFLIGHT_DECISION_KEYS.includes(answer.decisionKey)) {
+      probabilityBands[answer.decisionKey] = probabilityBand(answer.confidence);
+    }
+  }
+  for (const key of PREFLIGHT_DECISION_KEYS) {
+    if (!(key in probabilityBands)) probabilityBands[key] = 'unknown';
+  }
+
+  const okOutcomes = new Set(['accepted', 'partial', 'abstained']);
+  const outcomeClass = result?.status ?? 'unavailable';
+  const receipt = {
+    receiptVersion: 1,
+    stage,
+    batchId: result?.batchId ?? batch.batchId,
+    decisionKeys: [...PREFLIGHT_DECISION_KEYS],
+    probabilityBands,
+    outcomeClass,
+    checkpoint: result?.checkpoint ?? batch.checkpoint ?? null,
+    latencyClass: result?.latencyClass ?? 'unknown',
+    fallbackCode: result?.fallbackCode ?? (okOutcomes.has(outcomeClass) ? null : outcomeClass),
+    agreement: computeAgreement(
+      answers,
+      baseline,
+      candidateMap,
+      (batch.questions ?? [])
+        .map((q) => q?.decisionKey)
+        .filter((k) => typeof k === 'string'),
+    ),
+  };
+
+  // canary/default: validate the answer set cross-field and apply the bundle
+  // atomically. A blocked bundle is never half-applied — the deterministic
+  // fallback bundle (decision-table-v2) takes its place.
+  let preflight = null;
+  if (stage === 'canary' || stage === 'default') {
+    if (outcomeClass === 'accepted' || outcomeClass === 'partial') {
+      const validated = validatePreflightAnswers(answers, {
+        hostCapabilities: hosts,
+        riskFloor: normalizedRoute?.execution?.riskFloor ?? null,
+        candidateMap,
+        config,
+        batch,
+      });
+      if (validated.status === 'validated') {
+        // No host binding exists at routing time — applyPreflight records the
+        // attempt and keeps the bundle 'validated' without acknowledgement.
+        const { preflight: applied } = applyPreflight(validated.bundle, {
+          host: hosts?.host ?? null,
+        });
+        preflight = applied;
+      } else {
+        preflight = buildFallbackPreflight({
+          route: normalizedRoute,
+          hostCapabilities: hosts,
+          config,
+        });
+      }
+    } else {
+      preflight = baseline;
+    }
+  }
+
+  return { receipt, preflight };
+}

package/src/decision/statePacket.js

@@ -0,0 +1,165 @@
+/**
+ * statePacket.js (TASK-002 / M07)
+ *
+ * C13 decision state packet (docs/pstack/UNIC_DECISION_SPEC.md §6): a compact,
+ * deterministic serialization of approved features — never raw conversation
+ * text. The sensitive-value gate runs BEFORE serialization/transport; a
+ * positive detection yields `blocked-sensitive`, never a redacted-after-send.
+ */
+
+import {
+  scanText,
+  isSensitiveDataGateEnabled,
+  loadSensitiveAllowlist,
+} from '../core/sensitiveValueScanner.js';
+
+// Whitelisted C13 fields (UNIC_DECISION_SPEC §6). Anything else — prompts,
+// source excerpts, diffs, command payloads, paths, secrets — is dropped.
+const ALLOWED_FIELDS = new Set([
+  'stateVersion',
+  'taskClass',
+  'intentSignals',
+  'targetClass',
+  'execution',
+  'riskSignals',
+  'evidenceCodes',
+  'capabilityAvailability',
+  'candidateLabels',
+  'constraints',
+  'priorDecisionRefs',
+  'summary',
+]);
+
+const MAX_CODE_LENGTH = 64;
+const MAX_SUMMARY_LENGTH = 280;
+const MAX_ARRAY_ITEMS = 24;
+
+function sanitizeValue(value, key) {
+  if (typeof value === 'string') {
+    return value.slice(0, key === 'summary' ? MAX_SUMMARY_LENGTH : MAX_CODE_LENGTH);
+  }
+  if (typeof value === 'number') {
+    return Number.isFinite(value) ? value : undefined;
+  }
+  if (typeof value === 'boolean') return value;
+  if (Array.isArray(value)) {
+    const items = value
+      .slice(0, MAX_ARRAY_ITEMS)
+      .map((v) => sanitizeValue(v, key))
+      .filter((v) => v !== undefined);
+    return items;
+  }
+  if (value && typeof value === 'object') {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+      // '__proto__' assignment would mutate out's prototype instead of storing
+      // the key — silently dropping the value and polluting the packet shape.
+      if (k === '__proto__') continue;
+      const clean = sanitizeValue(v, k);
+      if (clean !== undefined) out[k] = clean;
+    }
+    return out;
+  }
+  return undefined;
+}
+
+/**
+ * Build a C13 state packet from approved fields. Unknown fields are dropped;
+ * values are bounded to short stable codes.
+ *
+ * @param {object} fields
+ * @returns {object} packet with stateVersion:1
+ */
+export function buildStatePacket(fields = {}) {
+  const packet = { stateVersion: 1 };
+  if (!fields || typeof fields !== 'object') return packet;
+  for (const [key, value] of Object.entries(fields)) {
+    if (!ALLOWED_FIELDS.has(key) || key === 'stateVersion') continue;
+    const clean = sanitizeValue(value, key);
+    if (clean !== undefined) packet[key] = clean;
+  }
+  return packet;
+}
+
+// Sorted-key serialization — identical logical packets produce identical bytes
+// (state fingerprints depend on it).
+function stableStringify(value) {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(',')}]`;
+  const keys = Object.keys(value).sort();
+  return `{${keys
+    .map((k) => `${JSON.stringify(k)}:${stableStringify(value[k])}`)
+    .join(',')}}`;
+}
+
+/**
+ * Serialize a packet deterministically.
+ * @param {object|string} packet
+ * @returns {string}
+ */
+export function serializeStatePacket(packet) {
+  return typeof packet === 'string' ? packet : stableStringify(packet);
+}
+
+/**
+ * Deterministic token estimator: a ~4-chars/token heuristic with a
+ * conservative byte backstop (ceil(bytes/3)) that dominates for dense ASCII —
+ * the safe direction is overestimation (UNIC_DECISION_SPEC §6).
+ *
+ * @param {object|string} packet packet or serialized text
+ * @returns {number} estimated token count
+ */
+export function estimateTokens(packet) {
+  const text = serializeStatePacket(packet);
+  const chars = text.length;
+  const bytes = Buffer.byteLength(text, 'utf8');
+  return Math.max(Math.ceil(chars / 4), Math.ceil(bytes / 3));
+}
+
+const DEFAULT_LIMITS = { multilingual: 1024, english: 512 };
+
+/**
+ * Assert the packet fits the token budget for its language class.
+ * 'english' → 512; 'multilingual'/'unknown' → 1024 (config-overridable).
+ * Throws an Error with code 'state-too-large' — never silently truncates.
+ *
+ * @param {object|string} packet
+ * @param {'english'|'multilingual'|'unknown'} languageClass
+ * @param {{multilingual?: number, english?: number}} [limits]
+ * @returns {number} the estimated token count
+ */
+export function assertStateBudget(packet, languageClass, limits = DEFAULT_LIMITS) {
+  const budget =
+    languageClass === 'english'
+      ? (limits?.english ?? DEFAULT_LIMITS.english)
+      : (limits?.multilingual ?? DEFAULT_LIMITS.multilingual);
+  const tokens = estimateTokens(packet);
+  if (tokens > budget) {
+    const err = new Error(`state-too-large: ${tokens} tokens exceeds ${budget}`);
+    err.code = 'state-too-large';
+    throw err;
+  }
+  return tokens;
+}
+
+/**
+ * Run the sensitive-value gate over the serialized packet. Fail-closed: any
+ * positive detection returns `blocked-sensitive` with labels only — the secret
+ * value is never carried in the result.
+ *
+ * @param {object|string} packet
+ * @param {{config?: object}} [options] runtime config (gate toggle + allowlist)
+ * @returns {{status:'ok', serialized:string, tokens:number}
+ *         | {status:'blocked-sensitive', labels:string[]}}
+ */
+export function redactStatePacket(packet, { config } = {}) {
+  const serialized = serializeStatePacket(packet);
+  const scan = scanText(serialized, {
+    gateEnabled: isSensitiveDataGateEnabled(config),
+    allowlistHashes: loadSensitiveAllowlist(config),
+  });
+  if (scan.hasSecret) {
+    return { status: 'blocked-sensitive', labels: scan.labels };
+  }
+  return { status: 'ok', serialized, tokens: estimateTokens(serialized) };
+}

package/src/diagnostics/failurePatterns.js

@@ -50,7 +50,8 @@ function normalizeSignature(command) {
 
 // Extract failure events from one parsed ledger. A failure event is a receipt with
 // `success === false` on a verification-ish kind carrying a `command`, OR (when the
-// ledger declares `verificationFailed === true`) any receipt carrying a `command`.
+// ledger declares `verificationFailed === true`) any FAILED receipt carrying a
+// `command` — a succeeded receipt is never a failure event.
 function failureCommands(ledger) {
   if (!isObject(ledger) || !Array.isArray(ledger.receipts)) return [];
   const out = [];

package/src/diagnostics/ledgerFiles.js

@@ -43,5 +43,7 @@ export async function listLedgerFiles(dir, limit) {
     }
   }));
   withMtime.sort((a, b) => b.mtimeMs - a.mtimeMs);
-  return withMtime.slice(0, Math.max(0, limit)).map((f) => f.name);
+  // `Math.max(0, undefined)` is NaN and slice(0, NaN) is [] — an omitted limit
+  // silently returned nothing. Omitted limit means "all files".
+  return withMtime.slice(0, Math.max(0, limit ?? Infinity)).map((f) => f.name);
 }

package/src/diagnostics/routeOutcomes.js

@@ -4,9 +4,9 @@
 
 import fs from 'node:fs/promises';
 import path from 'node:path';
+import { listLedgerFiles } from './ledgerFiles.js';
 
 const UNCLASSIFIED = '(unclassified)';
-const LEDGER_EXCLUDE = new Set(['gate-crash-counter.json']);
 
 function zeroedResult(extra = {}) {
   return {
@@ -37,34 +37,6 @@ function emptyBucket() {
   };
 }
 
-async function listLedgerFiles(ledgerDir, limitLedgers) {
-  let dirents;
-  try {
-    dirents = await fs.readdir(ledgerDir, { withFileTypes: true });
-  } catch {
-    return [];
-  }
-  const candidates = [];
-  for (const dirent of dirents) {
-    if (!dirent.isFile()) continue;
-    const name = dirent.name;
-    if (!name.endsWith('.json')) continue;
-    if (LEDGER_EXCLUDE.has(name)) continue;
-    if (name.includes('.journal') || name.includes('.quarantine')) continue;
-    candidates.push(name);
-  }
-  const withMtime = await Promise.all(candidates.map(async (name) => {
-    try {
-      const stat = await fs.stat(path.join(ledgerDir, name));
-      return { name, mtimeMs: stat.mtimeMs };
-    } catch {
-      return { name, mtimeMs: 0 };
-    }
-  }));
-  withMtime.sort((a, b) => b.mtimeMs - a.mtimeMs);
-  return withMtime.slice(0, Math.max(0, limitLedgers)).map((entry) => entry.name);
-}
-
 async function readJson(filePath) {
   try {
     return JSON.parse(await fs.readFile(filePath, 'utf8'));

package/src/index/buildIndex.js

@@ -249,7 +249,10 @@ export async function buildCodeIndex({ rootDir = process.cwd(), changedFiles = n
     ]);
     canReuseParsedArtifacts = previousSymbolsArtifact?.schemaVersion === INDEX_SCHEMA_VERSION
       && previousImportsArtifact?.schemaVersion === INDEX_SCHEMA_VERSION
-      && previousCallsArtifact?.schemaVersion === INDEX_SCHEMA_VERSION;
+      && previousCallsArtifact?.schemaVersion === INDEX_SCHEMA_VERSION
+      && Array.isArray(previousSymbolsArtifact.items)
+      && Array.isArray(previousImportsArtifact.items)
+      && Array.isArray(previousCallsArtifact.items);
 
     if (canReuseParsedArtifacts) {
       const previousSymbolsByPath = groupBy(previousSymbolsArtifact.items ?? [], (item) => item.filePath);
@@ -306,7 +309,8 @@ export async function buildCodeIndex({ rootDir = process.cwd(), changedFiles = n
     ? await readArtifactIfExists(absoluteRoot, INDEX_ARTIFACTS.testsMap)
     : null;
   const canReuseTestsMap = canReuseTestsMapCandidate
-    && previousTestsMapArtifact?.schemaVersion === INDEX_SCHEMA_VERSION;
+    && previousTestsMapArtifact?.schemaVersion === INDEX_SCHEMA_VERSION
+    && Array.isArray(previousTestsMapArtifact.items);
   const testsMap = canReuseTestsMap
     ? previousTestsMapArtifact.items
     : buildTestsMap(fileRecords);
@@ -315,6 +319,7 @@ export async function buildCodeIndex({ rootDir = process.cwd(), changedFiles = n
     ? await readArtifactIfExists(absoluteRoot, INDEX_ARTIFACTS.hotspots)
     : null;
   const canReuseHotspots = previousHotspotsArtifact?.schemaVersion === INDEX_SCHEMA_VERSION
+    && Array.isArray(previousHotspotsArtifact.items)
     && areBugIndexSnapshotsEqual(previousHotspotsArtifact?.sourceSnapshot, bugIndexSnapshot);
   const hotspots = canReuseHotspots
     ? previousHotspotsArtifact.items
@@ -329,8 +334,9 @@ export async function buildCodeIndex({ rootDir = process.cwd(), changedFiles = n
     : null;
   const canReuseArchetypes = canReuseArchetypesCandidate
     && previousArchetypesArtifact?.schemaVersion === INDEX_SCHEMA_VERSION
-    && previousArchetypesArtifact?.items?.length === codeFiles.length
-    && (previousArchetypesArtifact.items ?? []).every((item) => currentCodePaths.has(item.filePath));
+    && Array.isArray(previousArchetypesArtifact.items)
+    && previousArchetypesArtifact.items.length === codeFiles.length
+    && previousArchetypesArtifact.items.every((item) => currentCodePaths.has(item.filePath));
 
   // Reuse cached archetypes only when every indexed code file is unchanged
   const archetypes = canReuseArchetypes
@@ -356,6 +362,7 @@ export async function buildCodeIndex({ rootDir = process.cwd(), changedFiles = n
   };
   const canReuseRelations = canReuseGraphArtifactsCandidate
     && previousRelationsArtifact?.schemaVersion === INDEX_SCHEMA_VERSION
+    && Array.isArray(previousRelationsArtifact.items)
     && areStringArraysEqual(previousRelationsArtifact?.sourceSnapshot?.styleFiles, styleFilePaths)
     && arePathSnapshotsEqual(
       previousRelationsArtifact?.sourceSnapshot?.importAliasSnapshot,
@@ -363,6 +370,7 @@ export async function buildCodeIndex({ rootDir = process.cwd(), changedFiles = n
     );
   const canReuseAnalogs = canReuseGraphArtifactsCandidate
     && previousAnalogsArtifact?.schemaVersion === INDEX_SCHEMA_VERSION
+    && Array.isArray(previousAnalogsArtifact.items)
     && areStringArraysEqual(previousAnalogsArtifact?.sourceSnapshot?.styleFiles, styleFilePaths)
     && arePathSnapshotsEqual(
       previousAnalogsArtifact?.sourceSnapshot?.importAliasSnapshot,
@@ -948,11 +956,13 @@ async function tryIncrementalIndexUpdate({ absoluteRoot, indexDir, changedPaths,
   // expensive work being avoided is discovery and re-parsing, not these pure
   // transformations, so their output stays identical to a clean rebuild.
   const canReuseTestsMap = haveStableTrackedFileIdentities(filesArtifact.items, mergedFileRecords)
-    && testsMapArtifact?.schemaVersion === INDEX_SCHEMA_VERSION;
+    && testsMapArtifact?.schemaVersion === INDEX_SCHEMA_VERSION
+    && Array.isArray(testsMapArtifact.items);
   const testsMap = canReuseTestsMap ? testsMapArtifact.items : buildTestsMap(mergedFileRecords);
 
   const bugIndexSnapshot = await readBugIndexSnapshot(absoluteRoot);
   const canReuseHotspots = hotspotsArtifact?.schemaVersion === INDEX_SCHEMA_VERSION
+    && Array.isArray(hotspotsArtifact.items)
     && areBugIndexSnapshotsEqual(hotspotsArtifact?.sourceSnapshot, bugIndexSnapshot);
   const hotspots = canReuseHotspots ? hotspotsArtifact.items : await buildHotspots(absoluteRoot, bugIndexSnapshot);
 
@@ -964,9 +974,10 @@ async function tryIncrementalIndexUpdate({ absoluteRoot, indexDir, changedPaths,
   const canReuseArchetypes = parsedFiles.length === 0
     && !recordsChanged
     && archetypesArtifact?.schemaVersion === INDEX_SCHEMA_VERSION
+    && Array.isArray(archetypesArtifact.items)
     && codeFiles.every((file) => previousCodePaths.has(file.filePath))
-    && archetypesArtifact?.items?.length === archetypes.length
-    && (archetypesArtifact.items ?? []).every((item) => currentCodePaths.has(item?.filePath));
+    && archetypesArtifact.items.length === archetypes.length
+    && archetypesArtifact.items.every((item) => currentCodePaths.has(item?.filePath));
   const archetypeItems = canReuseArchetypes ? archetypesArtifact.items : archetypes;
 
   const needsAliasContext = importsNeedAliasContext(imports);
@@ -984,7 +995,8 @@ async function tryIncrementalIndexUpdate({ absoluteRoot, indexDir, changedPaths,
     && areStringArraysEqual(relationsArtifact?.sourceSnapshot?.styleFiles, styleFilePaths)
     && arePathSnapshotsEqual(relationsArtifact?.sourceSnapshot?.importAliasSnapshot, styleSnapshot.importAliasSnapshot);
   const canReuseAnalogs = canReuseRelations
-    && analogsArtifact?.schemaVersion === INDEX_SCHEMA_VERSION;
+    && analogsArtifact?.schemaVersion === INDEX_SCHEMA_VERSION
+    && Array.isArray(analogsArtifact.items);
 
   let relations = relationsArtifact.items;
   let analogs = analogsArtifact?.items ?? null;
@@ -1639,7 +1651,7 @@ function extractImports(filePath, content) {
   const stripped = stripCommentsStringAware(content);
   const imports = [];
 
-  for (const match of stripped.matchAll(/(?:^|[;\n])\s*import\s+(?:[^'";]+?\s+from\s+)?['"]([^'"]+)['"]/g)) {
+  for (const match of stripped.matchAll(/(?:^|[;\n])\s*import\s*(?:[^'";]+?\s*from\s*)?['"]([^'"]+)['"]/g)) {
     imports.push({
       from: filePath,
       to: match[1],
@@ -1663,7 +1675,7 @@ function extractImports(filePath, content) {
     });
   }
 
-  for (const match of stripped.matchAll(/(?:^|[;\n])\s*export\s+(?:type\s+)?\{[^}]+\}\s+from\s+['"]([^'"]+)['"]/g)) {
+  for (const match of stripped.matchAll(/(?:^|[;\n])\s*export\s+(?:type\s+)?\{[^}]+\}\s*from\s*['"]([^'"]+)['"]/g)) {
     imports.push({
       from: filePath,
       to: match[1],
@@ -1671,7 +1683,7 @@ function extractImports(filePath, content) {
     });
   }
 
-  for (const match of stripped.matchAll(/(?:^|[;\n])\s*export\s+\*(?:\s+as\s+[A-Za-z_$][A-Za-z0-9_$]*)?\s+from\s+['"]([^'"]+)['"]/g)) {
+  for (const match of stripped.matchAll(/(?:^|[;\n])\s*export\s+\*(?:\s+as\s+[A-Za-z_$][A-Za-z0-9_$]*)?\s*from\s*['"]([^'"]+)['"]/g)) {
     imports.push({
       from: filePath,
       to: match[1],

package/src/index/impactContext.js

@@ -4,6 +4,7 @@ import path from 'node:path';
 import { getArtifactPath, INDEX_ARTIFACTS } from './paths.js';
 import { classifyImpactRisk, findMirrorCounterparts } from './impactCatalog.js';
 import { inferRelatedTestsFromArtifacts, loadRelatedTestArtifacts } from './relatedTests.js';
+import { importsNeedAliasContext, loadImportAliasContext, resolveImportSpecifier } from './importResolution.js';
 
 const DEFAULT_IMPACT_LIMITS = {
   maxCallers: 8,
@@ -86,9 +87,10 @@ export async function resolveImpactContext({
   const normalizedChangedFiles = unique(changedFiles.map(normalizePath));
   const normalizedChangedSymbols = unique(changedSymbols.map((symbol) => String(symbol ?? '').trim()));
 
-  const [callsArtifact, importsArtifact, relatedArtifacts] = await Promise.all([
+  const [callsArtifact, importsArtifact, filesArtifact, relatedArtifacts] = await Promise.all([
     readArtifact(absoluteRoot, INDEX_ARTIFACTS.calls),
     readArtifact(absoluteRoot, INDEX_ARTIFACTS.imports),
+    readArtifact(absoluteRoot, INDEX_ARTIFACTS.files),
     loadRelatedTestArtifacts({ rootDir: absoluteRoot }),
   ]);
 
@@ -140,9 +142,26 @@ export async function resolveImpactContext({
 
   const importers = [];
   const dependencies = [];
+  // Non-relative specifiers (aliases like `@/x`, `~/x`, tsconfig paths) resolve
+  // through the same machinery the index builder uses; relative specifiers keep
+  // the candidate-list match so a changed file absent from files.json (e.g. a
+  // brand-new file) still counts.
+  const indexedFileSet = new Set((filesArtifact.items ?? []).map((item) => item.filePath));
+  const importAliasContext = importsNeedAliasContext(importItems)
+    ? await loadImportAliasContext({ rootDir: absoluteRoot }).catch(() => null)
+    : null;
   for (const imp of importItems) {
     const from = normalizePath(imp.from);
-    const targets = resolveImportTarget(from, imp.to) ?? [];
+    const specifier = String(imp.to ?? '').trim();
+    const targets = specifier.startsWith('.')
+      ? resolveImportTarget(from, specifier)
+      : [resolveImportSpecifier({
+          rootDir: absoluteRoot,
+          fromFilePath: from,
+          specifier,
+          indexedFileSet,
+          aliasContext: importAliasContext,
+        })].filter(Boolean);
     const matched = targets.find((candidate) => changedFileSet.has(normalizePath(candidate)));
 
     if (matched) {