qa-engineer 0.9.1 → 0.10.0

package/packages/engine/lib/analysis/taxonomy.mjs

@@ -0,0 +1,109 @@
+// The canonical QA failure taxonomy and its deterministic classifier.
+//
+// Classification maps observed signals to one of a closed set of failure classes.
+// It is rule-based and conservative: when no rule matches with sufficient signal,
+// the result is UNKNOWN. Unknown is preferable to incorrect.
+//
+// Ported from qa_analysis/taxonomy.py with the rule order preserved exactly —
+// order *is* the logic here (see the note on the first two rules) — and held to
+// identical output by scripts/check-engine-parity.mjs.
+
+export const ASSERTION = 'assertion-failure';
+export const LOCATOR = 'locator-failure';
+export const TIMEOUT = 'timeout';
+export const NETWORK = 'network';
+export const AUTH = 'authentication';
+export const AUTHORIZATION = 'authorization';
+export const ENVIRONMENT = 'environment';
+export const CONFIGURATION = 'configuration';
+export const INFRASTRUCTURE = 'infrastructure';
+export const TEST_DATA = 'test-data';
+export const APPLICATION_BUG = 'application-bug';
+export const FRAMEWORK = 'framework-failure';
+export const FLAKY = 'flaky';
+export const UNKNOWN = 'unknown';
+
+export const CLASSES = new Set([
+  ASSERTION, LOCATOR, TIMEOUT, NETWORK, AUTH, AUTHORIZATION, ENVIRONMENT,
+  CONFIGURATION, INFRASTRUCTURE, TEST_DATA, APPLICATION_BUG, FRAMEWORK,
+  FLAKY, UNKNOWN,
+]);
+
+// Ordered rules: [classification, pattern, confidence, reason].
+//
+// Order encodes priority, and the first two rules exist because modern runners
+// print a timeout budget in *every* assertion failure. Playwright's message for a
+// plain text mismatch ends with "Timeout: 5000ms" even though nothing timed out,
+// so a naive timeout rule captures assertion and locator failures alike and sends
+// the reader to raise a timeout — the one action guaranteed not to help. The
+// patterns below are derived from real captured runner output.
+//
+// The discriminators, from that output:
+//   element missing  -> "Error: element(s) not found"   (no Received: value)
+//   value mismatch   -> "Expected: X" + "Received: Y"   (element was resolved)
+//   real timeout     -> a timeout with neither of the above
+const RULES = [
+  [LOCATOR, /(no such element|element(?:\(s\))?\s+not\s+(?:found|visible|attached)|locator.*(?:resolved to 0|not found)|waiting for (?:locator|selector)|unable to locate element)/i, 0.8,
+    'Error indicates the target element could not be found or resolved.'],
+  // A concrete expected-vs-received comparison is an assertion result, not a
+  // time budget: the runner resolved the target and compared values.
+  [ASSERTION, /expected:.*received:/is, 0.8,
+    'Error shows a concrete expected-versus-received comparison, so the assertion did not hold.'],
+  [TIMEOUT, /(timeout|timed out|exceeded .*ms|deadline exceeded)/i, 0.75,
+    'Error indicates an operation exceeded its time budget.'],
+  [AUTH, /(401 unauthorized|authentication failed|invalid (?:credentials|token)|login failed|not authenticated)/i, 0.85,
+    'Error indicates an authentication failure — the identity could not be established.'],
+  [AUTHORIZATION, /(403 forbidden|permission denied|access denied|not authorized|forbidden\b|insufficient (?:permission|privilege))/i, 0.85,
+    'Error indicates an authorization failure — the identity lacked permission.'],
+  [NETWORK, /(ECONNREFUSED| ENOTFOUND|net::ERR|connection (?:refused|reset)|5\d\d (?:internal server error|bad gateway|service unavailable)|fetch failed)/i, 0.8,
+    'Error indicates a network or upstream service failure.'],
+  [ASSERTION, /(assertion|expect(?:ed)?\b|toBe|toEqual|toHaveText|toBeVisible|AssertionError|expected .* (?:to|but))/i, 0.7,
+    'Error indicates an assertion did not hold.'],
+  [TEST_DATA, /(duplicate key|constraint violation|no rows|seed data|fixture .*(?:missing|not found)|invalid test data)/i, 0.7,
+    'Error indicates a test-data problem.'],
+  [CONFIGURATION, /(cannot find module|config(?:uration)? (?:error|not found)|missing (?:config|environment variable)|unknown option)/i, 0.7,
+    'Error indicates a configuration problem.'],
+  [ENVIRONMENT, /(base ?url|env(?:ironment)? .*(?:not set|missing)|ECONNREFUSED .*localhost|dev server)/i, 0.6,
+    'Error indicates an environment problem such as a missing base URL or unreachable local service.'],
+  [INFRASTRUCTURE, /(out of memory|OOM|disk (?:full|space)|browser .*(?:crash|closed unexpectedly)|worker .*(?:died|crashed))/i, 0.7,
+    'Error indicates an infrastructure problem such as a crash or resource exhaustion.'],
+  [FRAMEWORK, /(internal error|unexpected error in (?:playwright|selenium|cypress|webdriver)|driver .*mismatch)/i, 0.6,
+    'Error indicates a fault in the test framework or driver itself.'],
+];
+
+/**
+ * Classify a failure from its error message and optional HTTP status.
+ *
+ * Returns `{classification, confidence, reason}`. Never guesses: an unrecognized
+ * signal yields UNKNOWN at low confidence with an honest reason.
+ */
+export function classify(message, httpStatus = null) {
+  const text = message || '';
+
+  // A concrete HTTP status is stronger evidence than message text.
+  if (httpStatus !== null && httpStatus !== undefined) {
+    if (httpStatus === 401) {
+      return { classification: AUTH, confidence: 0.9, reason: 'HTTP 401 indicates an authentication failure.' };
+    }
+    if (httpStatus === 403) {
+      return { classification: AUTHORIZATION, confidence: 0.9, reason: 'HTTP 403 indicates an authorization failure.' };
+    }
+    if (httpStatus >= 500 && httpStatus <= 599) {
+      return {
+        classification: NETWORK,
+        confidence: 0.85,
+        reason: `HTTP ${httpStatus} indicates an upstream server failure.`,
+      };
+    }
+  }
+
+  for (const [classification, pattern, confidence, reason] of RULES) {
+    if (pattern.test(text)) return { classification, confidence, reason };
+  }
+
+  return {
+    classification: UNKNOWN,
+    confidence: 0.2,
+    reason: 'No classification rule matched the available signals; manual review needed.',
+  };
+}

package/packages/engine/lib/analysis/xml.mjs

@@ -0,0 +1,153 @@
+// A dependency-free XML reader for the subset the pack's artifacts use.
+//
+// Node has no built-in XML parser, and taking one as a dependency is ruled out:
+// this code is bundled into skills that run in other people's repositories, where
+// every dependency is attack surface and an install burden (ADR-0009). So the
+// subset we actually need is parsed here — element tags, attributes, text,
+// nesting, comments, CDATA, and the five predefined entities.
+//
+// Deliberately NOT supported, because no artifact the pack reads uses them:
+// namespaces (a prefixed tag is treated as an opaque name), DTD entity
+// definitions, and processing instructions beyond being skipped. Anything
+// unsupported raises — the parser never guesses its way past a document it does
+// not understand, because a fabricated parse becomes a fabricated test result.
+
+const ENTITIES = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'" };
+
+export class XmlError extends Error {}
+
+function decode(text) {
+  if (!text.includes('&')) return text;
+  return text.replace(/&(#x?[0-9a-fA-F]+|[a-zA-Z]+);/g, (whole, body) => {
+    if (body[0] === '#') {
+      const code = body[1] === 'x' || body[1] === 'X'
+        ? parseInt(body.slice(2), 16)
+        : parseInt(body.slice(1), 10);
+      return Number.isFinite(code) && code >= 0 && code <= 0x10ffff
+        ? String.fromCodePoint(code)
+        : whole;
+    }
+    return Object.prototype.hasOwnProperty.call(ENTITIES, body) ? ENTITIES[body] : whole;
+  });
+}
+
+/**
+ * Parse an XML document into a node tree.
+ *
+ * A node is `{ tag, attrs, children, text }`. Text is the concatenation of the
+ * element's own character data, matching what `xml.etree` exposes closely enough
+ * for the artifacts the pack reads (which never mix text and children
+ * meaningfully).
+ *
+ * @param {string} source
+ * @returns {{tag: string, attrs: Record<string,string>, children: object[], text: string}}
+ */
+export function parseXml(source) {
+  if (typeof source !== 'string') throw new XmlError('XML source must be a string');
+
+  let cursor = 0;
+  const root = { tag: null, attrs: {}, children: [], text: '' };
+  const stack = [root];
+  const top = () => stack[stack.length - 1];
+
+  // Reported against the position of the offending markup, not the cursor: when a
+  // mismatched close tag is found, the cursor still sits at the end of the last
+  // *good* tag, so using it points a reader at the wrong line of a large report.
+  const fail = (why, at = cursor) => {
+    const line = source.slice(0, at).split('\n').length;
+    throw new XmlError(`${why} (line ${line})`);
+  };
+
+  while (cursor < source.length) {
+    const open = source.indexOf('<', cursor);
+    if (open === -1) {
+      top().text += decode(source.slice(cursor));
+      break;
+    }
+    if (open > cursor) top().text += decode(source.slice(cursor, open));
+
+    if (source.startsWith('<?', open)) {
+      const end = source.indexOf('?>', open);
+      if (end === -1) fail('unterminated processing instruction', open);
+      cursor = end + 2;
+      continue;
+    }
+    if (source.startsWith('<!--', open)) {
+      const end = source.indexOf('-->', open);
+      if (end === -1) fail('unterminated comment', open);
+      cursor = end + 3;
+      continue;
+    }
+    if (source.startsWith('<![CDATA[', open)) {
+      const end = source.indexOf(']]>', open);
+      if (end === -1) fail('unterminated CDATA section', open);
+      // CDATA is literal: no entity decoding.
+      top().text += source.slice(open + 9, end);
+      cursor = end + 3;
+      continue;
+    }
+    if (source.startsWith('<!', open)) {
+      const end = source.indexOf('>', open);
+      if (end === -1) fail('unterminated declaration', open);
+      cursor = end + 1;
+      continue;
+    }
+
+    const close = source.indexOf('>', open);
+    if (close === -1) fail('unterminated tag', open);
+    const raw = source.slice(open + 1, close);
+    if (raw.length === 0) fail('empty tag', open);
+
+    if (raw[0] === '/') {
+      const name = raw.slice(1).trim();
+      if (stack.length === 1) fail(`closing tag </${name}> with no open element`, open);
+      const node = stack.pop();
+      if (node.tag !== name) fail(`expected </${node.tag}> but found </${name}>`, open);
+      cursor = close + 1;
+      continue;
+    }
+
+    const selfClosing = raw.endsWith('/');
+    const body = selfClosing ? raw.slice(0, -1) : raw;
+    const firstSpace = body.search(/\s/);
+    const tag = (firstSpace === -1 ? body : body.slice(0, firstSpace)).trim();
+    if (!tag) fail('empty tag name', open);
+
+    const attrs = {};
+    if (firstSpace !== -1) {
+      const attrSource = body.slice(firstSpace);
+      // Quoted values only. An unquoted attribute value is not valid XML, and
+      // accepting one would mean guessing where it ends.
+      const pattern = /([^\s=/]+)\s*=\s*("([^"]*)"|'([^']*)')/g;
+      let match;
+      let consumed = 0;
+      while ((match = pattern.exec(attrSource)) !== null) {
+        attrs[match[1]] = decode(match[3] ?? match[4] ?? '');
+        consumed = match.index + match[0].length;
+      }
+      if (attrSource.slice(consumed).trim().length > 0) {
+        fail(`unparsable attributes in <${tag}>: ${attrSource.slice(consumed).trim()}`, open);
+      }
+    }
+
+    const node = { tag, attrs, children: [], text: '' };
+    top().children.push(node);
+    if (!selfClosing) stack.push(node);
+    cursor = close + 1;
+  }
+
+  if (stack.length !== 1) fail(`unclosed element <${top().tag}>`);
+  if (root.children.length === 0) throw new XmlError('document has no root element');
+  if (root.children.length > 1) throw new XmlError('document must have exactly one root element');
+  return root.children[0];
+}
+
+/** First child element with this tag, or null — `Element.find` in xml.etree. */
+export function find(node, tag) {
+  return node.children.find((child) => child.tag === tag) ?? null;
+}
+
+/** Every child element with this tag — `Element.findall` in xml.etree. */
+export function findAll(node, tag) {
+  return node.children.filter((child) => child.tag === tag);
+}

package/packages/engine/lib/analysis/zip.mjs

@@ -0,0 +1,107 @@
+// A dependency-free ZIP reader for the entries the pack needs to read.
+//
+// Node has no archive API, and a dependency is ruled out for code that runs in
+// other people's repositories (ADR-0009). Playwright writes its trace as a zip of
+// newline-delimited JSON, so the central directory is walked here and each entry
+// inflated with the built-in `zlib`.
+//
+// Supported: stored (method 0) and deflated (method 8) entries — the only two a
+// zip writer produces in practice, and the only two Playwright emits. Anything
+// else raises by name rather than returning empty bytes, because a silently empty
+// trace reads as "nothing happened" instead of "could not be read".
+
+import fs from 'node:fs';
+import zlib from 'node:zlib';
+
+const EOCD_SIGNATURE = 0x06054b50;
+const CENTRAL_SIGNATURE = 0x02014b50;
+const MAX_COMMENT = 0xffff;
+
+export class ZipError extends Error {}
+
+/**
+ * Every entry in the archive: `[{name, method, compressedSize, size, offset}]`.
+ *
+ * Read from the central directory, which is authoritative — the per-entry local
+ * headers may carry zeroed sizes when the writer streamed the file.
+ */
+export function listEntries(buffer) {
+  const eocd = findEndOfCentralDirectory(buffer);
+  const count = buffer.readUInt16LE(eocd + 10);
+  let cursor = buffer.readUInt32LE(eocd + 16);
+  const entries = [];
+
+  for (let index = 0; index < count; index += 1) {
+    if (cursor + 46 > buffer.length || buffer.readUInt32LE(cursor) !== CENTRAL_SIGNATURE) {
+      throw new ZipError(`central directory entry ${index} is malformed`);
+    }
+    const method = buffer.readUInt16LE(cursor + 10);
+    const compressedSize = buffer.readUInt32LE(cursor + 20);
+    const size = buffer.readUInt32LE(cursor + 24);
+    const nameLength = buffer.readUInt16LE(cursor + 28);
+    const extraLength = buffer.readUInt16LE(cursor + 30);
+    const commentLength = buffer.readUInt16LE(cursor + 32);
+    const offset = buffer.readUInt32LE(cursor + 42);
+    const name = buffer.subarray(cursor + 46, cursor + 46 + nameLength).toString('utf8');
+    entries.push({ name, method, compressedSize, size, offset });
+    cursor += 46 + nameLength + extraLength + commentLength;
+  }
+  return entries;
+}
+
+/** The bytes of one entry, inflated if it was deflated. */
+export function readEntry(buffer, entry) {
+  if (entry.offset + 30 > buffer.length) {
+    throw new ZipError(`entry ${entry.name} points past the end of the archive`);
+  }
+  const nameLength = buffer.readUInt16LE(entry.offset + 26);
+  const extraLength = buffer.readUInt16LE(entry.offset + 28);
+  const start = entry.offset + 30 + nameLength + extraLength;
+  const raw = buffer.subarray(start, start + entry.compressedSize);
+
+  if (entry.method === 0) return raw;
+  if (entry.method === 8) {
+    try {
+      return zlib.inflateRawSync(raw);
+    } catch (error) {
+      throw new ZipError(`entry ${entry.name} could not be inflated: ${error.message}`);
+    }
+  }
+  throw new ZipError(`entry ${entry.name} uses unsupported compression method ${entry.method}`);
+}
+
+/** Is this a readable ZIP archive? Locates the end-of-central-directory record. */
+export function isZip(buffer) {
+  try {
+    findEndOfCentralDirectory(buffer);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Open a zip file and hand back `{entries, read}`. */
+export function openZip(path) {
+  let buffer;
+  try {
+    buffer = fs.readFileSync(path);
+  } catch (error) {
+    throw new ZipError(`could not read ${path}: ${error.message}`);
+  }
+  const entries = listEntries(buffer);
+  return { entries, read: (entry) => readEntry(buffer, entry) };
+}
+
+/**
+ * The record is last in the file, possibly followed by a comment, so the tail is
+ * scanned backwards. Trusting the first four bytes instead would accept a
+ * truncated archive whose header still reads `PK\x03\x04`.
+ */
+function findEndOfCentralDirectory(buffer) {
+  if (buffer.length < 22) throw new ZipError('too short to be a zip archive');
+  const earliest = Math.max(0, buffer.length - 22 - MAX_COMMENT);
+  for (let cursor = buffer.length - 22; cursor >= earliest; cursor -= 1) {
+    if (buffer.readUInt32LE(cursor) === EOCD_SIGNATURE) return cursor;
+  }
+  throw new ZipError('no end-of-central-directory record: not a zip archive');
+}

package/packages/engine/lib/diagnostics/engine.mjs

@@ -0,0 +1,165 @@
+// The diagnostic engine — the one place failure reasoning happens.
+//
+// Orchestrates the analysis platform and the diagnostics modules into a single
+// diagnosis: per-failure root cause, prioritization, a reconstructed timeline, and
+// ranked recommendations. qa-debug presents the diagnosis; qa-fix turns it into
+// repair plans; qa-report aggregates diagnoses. None of them re-implements this.
+
+import * as taxonomy from '../analysis/taxonomy.mjs';
+
+import { analyze } from './root-cause.mjs';
+import { prioritize } from './prioritization.mjs';
+import { planRepair } from './repair.mjs';
+import { buildTimeline } from './timeline.mjs';
+import { validateDiagnosis } from './internal-contracts.mjs';
+
+const PRIORITY_RANK = { P1: 3, P2: 2, P3: 1 };
+
+// Classifications that block a release when they are the cause of a failure.
+const RELEASE_BLOCKING = new Set([
+  taxonomy.APPLICATION_BUG, taxonomy.NETWORK, taxonomy.INFRASTRUCTURE,
+  taxonomy.AUTH, taxonomy.AUTHORIZATION,
+]);
+
+/**
+ * Produce a full diagnosis from the available results.
+ *
+ * `{entries, timeline, recommendations}`, where each entry combines a root cause
+ * with its prioritization and affected tests.
+ */
+export function diagnose(executionResult, { analysisResult = null } = {}) {
+  const signals = deriveSignals(executionResult, analysisResult);
+  const findings = (analysisResult ?? {}).findings ?? [];
+
+  const entries = signals.map((signal) => {
+    const rootCause = analyze(signal);
+    const blocking = RELEASE_BLOCKING.has(rootCause.classification);
+    return {
+      rootCause,
+      priority: prioritize(rootCause, { blocking }),
+      affectedTests: signal.affectedTests ?? [],
+    };
+  });
+
+  // Highest priority first, then highest confidence. Python's `sort(reverse=True)`
+  // on a tuple key is a stable descending sort, so equal keys keep insertion order
+  // — reproduced by comparing in reverse and falling back to the original index.
+  const decorated = entries.map((entry, index) => ({ entry, index }));
+  decorated.sort((a, b) => {
+    const rank = (PRIORITY_RANK[b.entry.priority.priority] ?? 0) - (PRIORITY_RANK[a.entry.priority.priority] ?? 0);
+    if (rank !== 0) return rank;
+    const confidence = b.entry.rootCause.confidence - a.entry.rootCause.confidence;
+    if (confidence !== 0) return confidence;
+    // Insertion order for ties. Python's `sort(reverse=True)` is stable, so equal
+    // keys keep the order they arrived in — reversing the tie-break too would put
+    // two equally-ranked locator failures back to front.
+    return a.index - b.index;
+  });
+
+  const diagnosis = {
+    entries: decorated.map(({ entry }) => entry),
+    timeline: buildTimeline(executionResult, findings),
+    recommendations: recommendations(decorated.map(({ entry }) => entry)),
+  };
+  // Mechanical seam enforcement: a diagnosis must match the internal contract.
+  return validateDiagnosis(diagnosis);
+}
+
+/**
+ * Turn a diagnosis into repair plans (for qa-fix).
+ *
+ * One plan per entry; non-repairable causes yield an escalation plan. Never
+ * produces code.
+ */
+export function planRepairs(diagnosis) {
+  return diagnosis.entries.map((entry) => ({
+    ...planRepair(entry.rootCause, entry.affectedTests),
+    priority: entry.priority.priority,
+  }));
+}
+
+/**
+ * Aggregate a diagnosis for qa-report: totals, breakdown by classification, the
+ * top-priority findings, and a deterministic release-readiness call.
+ */
+export function summarize(executionResult, diagnosis) {
+  const tests = (executionResult ?? {}).tests ?? {};
+  const byClassification = {};
+  for (const entry of diagnosis.entries) {
+    const cls = entry.rootCause.classification;
+    byClassification[cls] = (byClassification[cls] ?? 0) + 1;
+  }
+
+  return {
+    totals: tests,
+    byClassification,
+    topPriority: diagnosis.entries.filter((entry) => entry.priority.priority === 'P1'),
+    releaseReadiness: releaseReadiness(executionResult, diagnosis),
+  };
+}
+
+/** Derive failure signals, preferring the analysis platform's findings. */
+function deriveSignals(executionResult, analysisResult) {
+  const findings = (analysisResult ?? {}).findings ?? [];
+  if (findings.length > 0) {
+    return findings.map((finding) => ({
+      message: finding.reason ?? '',
+      classification: finding.classification,
+      confidence: finding.confidence,
+      reason: finding.reason,
+      httpStatus: finding.httpStatus,
+      retries: finding.retries ?? 0,
+      finalStatus: finding.finalStatus,
+      evidence: finding.evidence ?? [],
+      affectedTests: finding.affectedTests ?? [],
+    }));
+  }
+
+  const signals = [];
+  for (const test of (executionResult ?? {}).executed ?? []) {
+    if (test.status === 'failed' || test.status === 'flaky') {
+      signals.push({
+        message: test.message ?? '',
+        retries: test.retries ?? 0,
+        finalStatus: test.status,
+        affectedTests: [test.title ?? ''],
+        evidence: [{
+          type: 'junit',
+          description: `${test.status}: ${test.title ?? ''}`,
+          source: test.file ?? 'execution-result',
+        }],
+      });
+    }
+  }
+  return signals;
+}
+
+/** Ranked, de-duplicated recommendations — highest priority first. */
+function recommendations(entries) {
+  const seen = new Set();
+  const ranked = [];
+  for (const entry of entries) {
+    const action = entry.rootCause.recommendation;
+    if (seen.has(action)) continue;
+    seen.add(action);
+    ranked.push({
+      action,
+      priority: entry.priority.priority,
+      owner: entry.rootCause.ownership,
+      classification: entry.rootCause.classification,
+    });
+  }
+  return ranked;
+}
+
+function releaseReadiness(executionResult, diagnosis) {
+  const failed = ((executionResult ?? {}).tests ?? {}).failed ?? 0;
+  if (failed === 0 && diagnosis.entries.length === 0) return 'ready';
+  const classes = new Set(diagnosis.entries.map((entry) => entry.rootCause.classification));
+  for (const blocking of RELEASE_BLOCKING) {
+    if (classes.has(blocking)) return 'not-ready';
+  }
+  // `classes <= {UNKNOWN}` in Python: every class is unknown (or there are none).
+  if ([...classes].every((cls) => cls === taxonomy.UNKNOWN)) return 'insufficient-data';
+  return 'ready-with-risks';
+}

package/packages/engine/lib/diagnostics/internal-contracts.mjs

@@ -0,0 +1,50 @@
+// Validate internal Analysis → Diagnostics seam payloads.
+//
+// Uses the dependency-free contract validator against the schemas under
+// shared/diagnostics/schemas/internal/.
+//
+// The schemas must be reachable in both layouts this code runs in: beside the
+// engine when it ships inside the package, and at the canonical repository path
+// during development. Missing schemas raise InternalContractError naming the
+// locations tried, rather than a bare ENOENT from deep inside a diagnosis.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { validate } from '../analysis/contracts.mjs';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+
+const SCHEMA_DIRS = [path.join(here, 'schemas', 'internal')];
+
+export class InternalContractError extends Error {}
+
+/** The directory holding the internal schemas, whichever layout applies. */
+export function schemaDir() {
+  for (const candidate of SCHEMA_DIRS) {
+    if (fs.existsSync(candidate) && fs.statSync(candidate).isDirectory()) return candidate;
+  }
+  throw new InternalContractError(
+    `internal schemas not found; tried: ${SCHEMA_DIRS.join(', ')}. ` +
+      'A package that ships the engine must carry diagnostics/schemas/internal/.',
+  );
+}
+
+function load(name) {
+  const file = path.join(schemaDir(), name);
+  if (!fs.existsSync(file)) throw new InternalContractError(`internal schema missing: ${file}`);
+  return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+
+function require_(payload, schemaName) {
+  const errors = validate(payload, load(schemaName));
+  if (errors.length > 0) {
+    throw new InternalContractError(`${schemaName}: ${errors.join('; ')}`);
+  }
+  return payload;
+}
+
+export const validateAnalysisResult = (payload) => require_(payload, 'analysis-result.schema.json');
+export const validateExecutionResultMin = (payload) => require_(payload, 'execution-result-min.schema.json');
+export const validateDiagnosis = (payload) => require_(payload, 'diagnosis.schema.json');

package/packages/engine/lib/diagnostics/prioritization.mjs

@@ -0,0 +1,99 @@
+// Deterministic finding prioritization.
+//
+// Assigns every finding a severity, priority, the three impacts, an owner, and an
+// estimated effort — by a fixed algorithm, so the same finding always ranks the
+// same way. Priority is not a feeling; it is a function of severity, confidence,
+// and business impact.
+
+import * as taxonomy from '../analysis/taxonomy.mjs';
+
+// Base severity per classification (before confidence adjustment).
+const SEVERITY = {
+  [taxonomy.APPLICATION_BUG]: 'high',
+  [taxonomy.INFRASTRUCTURE]: 'high',
+  [taxonomy.NETWORK]: 'high',
+  [taxonomy.AUTH]: 'high',
+  [taxonomy.AUTHORIZATION]: 'high',
+  [taxonomy.ASSERTION]: 'medium',
+  [taxonomy.LOCATOR]: 'medium',
+  [taxonomy.TIMEOUT]: 'medium',
+  [taxonomy.TEST_DATA]: 'medium',
+  [taxonomy.CONFIGURATION]: 'medium',
+  [taxonomy.ENVIRONMENT]: 'medium',
+  [taxonomy.FRAMEWORK]: 'medium',
+  [taxonomy.FLAKY]: 'medium',
+  [taxonomy.UNKNOWN]: 'low',
+};
+
+// Where the impact predominantly lands, per classification.
+const IMPACT = {
+  [taxonomy.APPLICATION_BUG]: { business: 'high', technical: 'high', testing: 'low' },
+  [taxonomy.NETWORK]: { business: 'high', technical: 'high', testing: 'medium' },
+  [taxonomy.AUTH]: { business: 'high', technical: 'medium', testing: 'medium' },
+  [taxonomy.AUTHORIZATION]: { business: 'high', technical: 'medium', testing: 'medium' },
+  [taxonomy.INFRASTRUCTURE]: { business: 'medium', technical: 'high', testing: 'high' },
+  [taxonomy.LOCATOR]: { business: 'low', technical: 'low', testing: 'high' },
+  [taxonomy.ASSERTION]: { business: 'medium', technical: 'medium', testing: 'medium' },
+  [taxonomy.TIMEOUT]: { business: 'low', technical: 'medium', testing: 'high' },
+  [taxonomy.TEST_DATA]: { business: 'low', technical: 'low', testing: 'high' },
+  [taxonomy.CONFIGURATION]: { business: 'low', technical: 'medium', testing: 'high' },
+  [taxonomy.ENVIRONMENT]: { business: 'low', technical: 'medium', testing: 'high' },
+  [taxonomy.FRAMEWORK]: { business: 'low', technical: 'medium', testing: 'high' },
+  [taxonomy.FLAKY]: { business: 'low', technical: 'low', testing: 'high' },
+  [taxonomy.UNKNOWN]: { business: 'low', technical: 'low', testing: 'medium' },
+};
+
+// Rough effort to resolve, per classification.
+const EFFORT = {
+  [taxonomy.LOCATOR]: 'low',
+  [taxonomy.ASSERTION]: 'low',
+  [taxonomy.CONFIGURATION]: 'low',
+  [taxonomy.ENVIRONMENT]: 'low',
+  [taxonomy.TEST_DATA]: 'medium',
+  [taxonomy.TIMEOUT]: 'medium',
+  [taxonomy.FLAKY]: 'medium',
+  [taxonomy.AUTH]: 'medium',
+  [taxonomy.AUTHORIZATION]: 'medium',
+  [taxonomy.FRAMEWORK]: 'medium',
+  [taxonomy.NETWORK]: 'high',
+  [taxonomy.INFRASTRUCTURE]: 'high',
+  [taxonomy.APPLICATION_BUG]: 'external',
+  [taxonomy.UNKNOWN]: 'unknown',
+};
+
+const RANK = { low: 1, medium: 2, high: 3 };
+const PRIORITY = { 1: 'P3', 2: 'P2', 3: 'P1', 4: 'P1' };
+
+/**
+ * Prioritize a root cause.
+ *
+ * Priority derives from severity, business impact, and confidence, and is escalated
+ * one step when the failure blocks a release.
+ */
+export function prioritize(rootCause, { blocking = false } = {}) {
+  const classification = rootCause.classification;
+  const confidence = 'confidence' in rootCause && rootCause.confidence !== undefined
+    ? rootCause.confidence
+    : 0.5;
+  const severity = SEVERITY[classification] ?? 'low';
+  const impact = IMPACT[classification] ?? IMPACT[taxonomy.UNKNOWN];
+
+  // Priority score: severity and business impact drive it; low confidence holds it
+  // back (an uncertain finding should not top the queue).
+  let score = RANK[severity];
+  if (impact.business === 'high') score += 1;
+  if (confidence < 0.5) score -= 1;
+  if (blocking) score += 1;
+  score = Math.max(1, Math.min(4, score));
+
+  return {
+    severity,
+    priority: PRIORITY[score],
+    businessImpact: impact.business,
+    technicalImpact: impact.technical,
+    testingImpact: impact.testing,
+    confidence,
+    owner: rootCause.ownership ?? 'needs-triage',
+    estimatedEffort: EFFORT[classification] ?? 'unknown',
+  };
+}