@yemi33/minions 0.1.2448 → 0.1.2449

package/engine/qa/visual-journey.js

@@ -0,0 +1,654 @@
+/**
+ * engine/qa/visual-journey.js — the DRAFT-phase visual-journey manifest
+ * (W-msb9kgs402813a97-b).
+ *
+ * Before this module, DRAFT's only structured output was
+ * `structuredCompletion.testFile`, so an API-only test file passed straight
+ * through `engine/qa/sessions.js#handleDraftComplete` into EXECUTE. A session
+ * that asked for screenshots or video could therefore reach a green qa-run
+ * having never opened a browser, and on a multi-project session it could
+ * silently ignore every co-service origin.
+ *
+ * The manifest is owned by the SESSION layer, NOT inferred from the drafted
+ * test file: a source-string scan of a runner-native test is a guess, and a
+ * guess cannot be a gate. The DRAFT agent DECLARES what it drafted in a
+ * single-use sidecar; the engine validates that declaration against the
+ * session's own spec and fails closed before EXECUTE is ever queued.
+ *
+ * Sidecar contract (modelled on engine/qa/runs.js#prepareResultSidecar /
+ * #consumeResultSidecar):
+ *
+ *   agents/<agentId>/qa-session-draft-result.json
+ *
+ * `prepareDraftResultSidecar` clears stale content at spawn time;
+ * `consumeDraftResultSidecar` does an atomic read-then-unlink and returns
+ * `{ ok: false, reason }` for missing / unreadable / malformed /
+ * session-id-mismatched files. Exactly-once, like every other Minions sidecar.
+ *
+ * Manifest shape:
+ *
+ *   {
+ *     "sessionId": "qas-...",
+ *     "journeys": [{
+ *       "id": "login",
+ *       "name": "Operator signs in and lands on the dashboard",
+ *       "kind": "browser" | "api",
+ *       "projects":   ["web"],
+ *       "services":   ["qa-session-qas-...", "qa-session-qas-...-api"],
+ *       "origins":    ["http://localhost:7346"],
+ *       "steps":      ["open /login", "submit credentials"],
+ *       "assertions": ["dashboard header is visible"],
+ *       "evidence":   { "screenshots": ["login.png"], "video": ["login.webm"] }
+ *     }]
+ *   }
+ *
+ * Every list is capped in length AND per-entry byte size, and the encoded
+ * manifest itself is byte-capped, so a runaway agent cannot inflate the
+ * session record.
+ *
+ * ── EXECUTE side (W-msb9kgs402813a97-c) ────────────────────────────────────
+ *
+ * The manifest is a PLAN; `validateEvidenceCoverage` at the bottom of this
+ * file is the PROOF. Before `engine/qa/sessions.js#handleExecuteComplete` is
+ * allowed to choose DONE, it checks the accepted manifest against what the
+ * qa-run actually produced: registered artifacts per requested capture type,
+ * those artifacts existing on disk (non-zero, inside the run's own artifacts
+ * dir), and per-journey `journeyCoverage` covering every project and
+ * managed-spawn the session owns. A green run that cannot show its evidence
+ * fails with `qa-session-evidence-incomplete` instead of closing the session.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const shared = require('../core/shared');
+
+const DRAFT_RESULT_SIDECAR_FILENAME = 'qa-session-draft-result.json';
+
+const JOURNEY_KINDS = Object.freeze({ BROWSER: 'browser', API: 'api' });
+const VALID_JOURNEY_KINDS = Object.freeze(new Set(Object.values(JOURNEY_KINDS)));
+
+// Which capture toggle demands which planned artifact extension, and which
+// registered artifact `type` values count as that kind of evidence at EXECUTE
+// time. Kept as data so a new capture type is one row, not a new branch in
+// either gate.
+const EVIDENCE_CONTRACT = Object.freeze({
+  screenshots: {
+    field: 'screenshots',
+    ext: '.png',
+    artifactTypes: Object.freeze(['screenshot', 'screenshots', 'image']),
+  },
+  video: {
+    field: 'video',
+    ext: '.webm',
+    artifactTypes: Object.freeze(['video', 'recording']),
+  },
+});
+
+// Failure class stamped on the session when the gate rejects. Operators grep
+// this out of engine.log, so it is a constant rather than an inline literal.
+const VISUAL_COVERAGE_FAILURE_CLASS = 'qa-session-draft-visual-coverage';
+
+// W-msb9kgs402813a97-c — the EXECUTE-side sibling: a green qa-run whose
+// evidence does not actually exist (or only covers one project) fails the
+// session with this class instead of transitioning it to done.
+const EVIDENCE_COVERAGE_FAILURE_CLASS = 'qa-session-evidence-incomplete';
+
+const LIMITS = Object.freeze({
+  journeysMax: 20,
+  idMaxBytes: 64,
+  nameMaxBytes: 200,
+  // projects / services / origins entries per journey
+  listMax: 20,
+  stepsMax: 50,
+  assertionsMax: 50,
+  // planned evidence entries per capture type per journey
+  evidenceMax: 20,
+  // per-entry cap for every string inside a list
+  entryMaxBytes: 500,
+  // whole-sidecar cap, checked before anything is walked
+  manifestMaxBytes: 64 * 1024,
+  agentIdMax: 128,
+});
+
+const _AGENT_ID_RE = /^[a-zA-Z0-9._-]+$/;
+
+function _isNonEmptyString(v) {
+  return typeof v === 'string' && v.length > 0;
+}
+
+function _bytes(str) {
+  return Buffer.byteLength(String(str), 'utf8');
+}
+
+// ── Sidecar ────────────────────────────────────────────────────────────────
+
+function draftResultSidecarPath(agentId) {
+  const segment = typeof agentId === 'string' ? agentId : '';
+  if (!segment || segment.length > LIMITS.agentIdMax || !_AGENT_ID_RE.test(segment)
+      || segment === '.' || segment === '..') {
+    throw new Error(`qa-visual-journey: invalid agent id for draft result sidecar: ${agentId}`);
+  }
+  return path.join(shared.MINIONS_DIR, 'agents', segment, DRAFT_RESULT_SIDECAR_FILENAME);
+}
+
+/**
+ * Clear any stale draft-result sidecar before a DRAFT dispatch starts.
+ *
+ * Load-bearing on the re-draft path: `editDraft` re-queues DRAFT for the SAME
+ * session id, so a leftover manifest from a previous attempt would pass the
+ * session-id check and be consumed as if it described the new draft.
+ */
+function prepareDraftResultSidecar(agentId, sessionId) {
+  if (!_isNonEmptyString(sessionId)) {
+    throw new Error(`qa-visual-journey: invalid session id for draft result sidecar: ${sessionId}`);
+  }
+  const filePath = draftResultSidecarPath(agentId);
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  try {
+    fs.unlinkSync(filePath);
+  } catch (err) {
+    if (err.code !== 'ENOENT') {
+      throw new Error(`qa-visual-journey: could not clear draft result sidecar for ${sessionId}: ${err.message}`);
+    }
+  }
+  return filePath;
+}
+
+/**
+ * Read-then-unlink the draft-result sidecar exactly once.
+ *
+ * @returns {{ok:true, manifest:object, filePath:string, cleanupError?:string}
+ *          |{ok:false, reason:string, filePath:string, detail?:string,
+ *            actualSessionId?:string, expectedSessionId?:string,
+ *            cleanupError?:string}}
+ */
+function consumeDraftResultSidecar(agentId, expectedSessionId) {
+  if (!_isNonEmptyString(expectedSessionId)) {
+    throw new Error(`qa-visual-journey: invalid expected session id for draft result sidecar: ${expectedSessionId}`);
+  }
+  const filePath = draftResultSidecarPath(agentId);
+  let raw;
+  try {
+    raw = fs.readFileSync(filePath, 'utf8');
+  } catch (err) {
+    return {
+      ok: false,
+      reason: err.code === 'ENOENT' ? 'missing' : 'read-error',
+      detail: err.code === 'ENOENT' ? '' : err.message,
+      filePath,
+    };
+  }
+
+  let outcome;
+  try {
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      outcome = { ok: false, reason: 'malformed', detail: 'expected a JSON object', filePath };
+    } else if (parsed.sessionId !== expectedSessionId) {
+      outcome = {
+        ok: false,
+        reason: 'session-id-mismatch',
+        actualSessionId: typeof parsed.sessionId === 'string' ? parsed.sessionId : '',
+        expectedSessionId,
+        filePath,
+      };
+    } else {
+      outcome = { ok: true, manifest: parsed, filePath };
+    }
+  } catch (err) {
+    outcome = { ok: false, reason: 'malformed', detail: err.message, filePath };
+  }
+
+  try {
+    fs.unlinkSync(filePath);
+  } catch (err) {
+    if (err.code !== 'ENOENT') outcome.cleanupError = err.message;
+  }
+  return outcome;
+}
+
+// ── Manifest validation ────────────────────────────────────────────────────
+
+function _requestedCaptureTypes(session) {
+  const capture = (session && session.spec && session.spec.capture) || {};
+  return Object.keys(EVIDENCE_CONTRACT).filter(key => !!capture[key]);
+}
+
+/**
+ * True when the session asked for screenshots or video — the ONLY condition
+ * under which a visual journey is demanded. A logs-only session (or a session
+ * with no capture at all) keeps its historical pass-through behaviour.
+ */
+function isVisualCaptureRequested(session) {
+  return _requestedCaptureTypes(session).length > 0;
+}
+
+function _sessionProjects(session) {
+  const projects = session && session.spec && session.spec.projects;
+  return Array.isArray(projects) ? projects.filter(_isNonEmptyString) : [];
+}
+
+/**
+ * The managed-spawn names the manifest must cover.
+ *
+ * Callers may inject an inventory (`opts.services`, either bare names or the
+ * `{name, project, ...}` rows `engine.js#buildQaSessionServices` produces);
+ * otherwise it is derived from the session itself. A lookup that throws is
+ * FAIL-CLOSED — an unknown inventory rejects rather than silently waiving the
+ * coverage requirement.
+ */
+function _requiredServiceNames(session, opts) {
+  if (Array.isArray(opts && opts.services)) {
+    const names = [];
+    for (const entry of opts.services) {
+      if (_isNonEmptyString(entry)) names.push(entry);
+      else if (entry && typeof entry === 'object' && _isNonEmptyString(entry.name)) names.push(entry.name);
+    }
+    return { ok: true, names };
+  }
+  try {
+    const names = require('./sessions').managedSpawnNamesForSession(session);
+    return { ok: true, names: Array.isArray(names) ? names.filter(_isNonEmptyString) : [] };
+  } catch (err) {
+    return { ok: false, names: [], error: err.message };
+  }
+}
+
+function _normalizeStringList(value, label, max, errors) {
+  if (value === undefined || value === null) return [];
+  if (!Array.isArray(value)) {
+    errors.push(`${label} must be an array of strings`);
+    return [];
+  }
+  if (value.length > max) {
+    errors.push(`${label} has ${value.length} entries (cap ${max})`);
+    return [];
+  }
+  const out = [];
+  for (const entry of value) {
+    if (!_isNonEmptyString(entry)) {
+      errors.push(`${label} entries must be non-empty strings`);
+      return [];
+    }
+    if (_bytes(entry) > LIMITS.entryMaxBytes) {
+      errors.push(`${label} entry exceeds ${LIMITS.entryMaxBytes} bytes`);
+      return [];
+    }
+    out.push(entry);
+  }
+  return out;
+}
+
+function _normalizeJourney(raw, index, errors) {
+  const label = `journeys[${index}]`;
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    errors.push(`${label} must be a plain object`);
+    return null;
+  }
+  if (!_isNonEmptyString(raw.id) || _bytes(raw.id) > LIMITS.idMaxBytes) {
+    errors.push(`${label}.id must be a non-empty string of at most ${LIMITS.idMaxBytes} bytes`);
+    return null;
+  }
+  if (!_isNonEmptyString(raw.name) || _bytes(raw.name) > LIMITS.nameMaxBytes) {
+    errors.push(`${label}.name must be a non-empty string of at most ${LIMITS.nameMaxBytes} bytes`);
+    return null;
+  }
+  if (!VALID_JOURNEY_KINDS.has(raw.kind)) {
+    errors.push(`${label}.kind must be one of: ${[...VALID_JOURNEY_KINDS].join(', ')}`);
+    return null;
+  }
+
+  const before = errors.length;
+  const journey = {
+    id: raw.id,
+    name: raw.name,
+    kind: raw.kind,
+    projects: _normalizeStringList(raw.projects, `${label}.projects`, LIMITS.listMax, errors),
+    services: _normalizeStringList(raw.services, `${label}.services`, LIMITS.listMax, errors),
+    origins: _normalizeStringList(raw.origins, `${label}.origins`, LIMITS.listMax, errors),
+    steps: _normalizeStringList(raw.steps, `${label}.steps`, LIMITS.stepsMax, errors),
+    assertions: _normalizeStringList(raw.assertions, `${label}.assertions`, LIMITS.assertionsMax, errors),
+    evidence: { screenshots: [], video: [] },
+  };
+
+  const evidence = raw.evidence;
+  if (evidence !== undefined && evidence !== null) {
+    if (typeof evidence !== 'object' || Array.isArray(evidence)) {
+      errors.push(`${label}.evidence must be a plain object`);
+    } else {
+      for (const key of Object.keys(EVIDENCE_CONTRACT)) {
+        journey.evidence[key] = _normalizeStringList(
+          evidence[key], `${label}.evidence.${key}`, LIMITS.evidenceMax, errors,
+        );
+      }
+    }
+  }
+  return errors.length === before ? journey : null;
+}
+
+/**
+ * Validate (and normalize) a DRAFT visual-journey manifest against its session.
+ *
+ * Shape errors short-circuit — coverage cannot be judged on a manifest whose
+ * journeys did not parse. Coverage errors are collected together so one
+ * re-draft can fix everything the gate objects to.
+ *
+ * @param {object} session   - the qa-sessions record
+ * @param {object|null} manifest - parsed sidecar contents (null when absent)
+ * @param {object} [opts]
+ * @param {Array}  [opts.services] - injected managed-spawn inventory
+ * @returns {{ok:true, required:boolean, manifest:object|null}
+ *          |{ok:false, required:boolean, errors:string[], error:string}}
+ */
+function validateVisualJourneyManifest(session, manifest, opts = {}) {
+  const sessionId = (session && session.id) || '(unknown session)';
+  const requestedCapture = _requestedCaptureTypes(session);
+  const required = requestedCapture.length > 0;
+  const reject = (errors) => ({ ok: false, required, errors, error: errors.join(' ') });
+
+  if (manifest === undefined || manifest === null) {
+    if (!required) return { ok: true, required, manifest: null };
+    return reject([
+      `QA Session ${sessionId} requested visual capture (${requestedCapture.join(', ')}) but DRAFT ` +
+      `declared no visual-journey manifest — write the ${DRAFT_RESULT_SIDECAR_FILENAME} sidecar with a ` +
+      '`journeys` array describing what the drafted test actually exercises.',
+    ]);
+  }
+
+  // ── Shape ────────────────────────────────────────────────────────────────
+  const shapeErrors = [];
+  if (typeof manifest !== 'object' || Array.isArray(manifest)) {
+    return reject([`visual-journey manifest for ${sessionId} must be a plain object.`]);
+  }
+  let encodedBytes = 0;
+  try {
+    encodedBytes = _bytes(JSON.stringify(manifest));
+  } catch (err) {
+    return reject([`visual-journey manifest for ${sessionId} is not JSON-encodable: ${err.message}`]);
+  }
+  if (encodedBytes > LIMITS.manifestMaxBytes) {
+    return reject([
+      `visual-journey manifest for ${sessionId} is ${encodedBytes} bytes ` +
+      `(cap ${LIMITS.manifestMaxBytes}) — trim steps/assertions and keep the journey list to what the test covers.`,
+    ]);
+  }
+  if (manifest.sessionId !== sessionId) {
+    return reject([
+      `visual-journey manifest declares sessionId "${manifest.sessionId || ''}" but this DRAFT belongs to ` +
+      `${sessionId} — the sidecar must name its own session.`,
+    ]);
+  }
+  if (!Array.isArray(manifest.journeys)) {
+    return reject([`visual-journey manifest for ${sessionId} must carry a \`journeys\` array.`]);
+  }
+  if (manifest.journeys.length > LIMITS.journeysMax) {
+    return reject([
+      `visual-journey manifest for ${sessionId} declares ${manifest.journeys.length} journeys ` +
+      `(cap ${LIMITS.journeysMax}).`,
+    ]);
+  }
+
+  const journeys = [];
+  const seenIds = new Set();
+  for (let i = 0; i < manifest.journeys.length; i++) {
+    const journey = _normalizeJourney(manifest.journeys[i], i, shapeErrors);
+    if (!journey) continue;
+    if (seenIds.has(journey.id)) {
+      shapeErrors.push(`journeys[${i}].id "${journey.id}" is a duplicate — journey ids must be unique.`);
+      continue;
+    }
+    seenIds.add(journey.id);
+    journeys.push(journey);
+  }
+  if (shapeErrors.length) {
+    return reject([`visual-journey manifest for ${sessionId} is malformed: ${shapeErrors.join('; ')}.`]);
+  }
+
+  const normalized = { sessionId, journeys };
+  if (!required) return { ok: true, required, manifest: normalized };
+
+  // ── Coverage gate (visual capture requested) ─────────────────────────────
+  const errors = [];
+
+  const browserJourneys = journeys.filter(j => j.kind === JOURNEY_KINDS.BROWSER);
+  if (browserJourneys.length === 0) {
+    const kinds = journeys.length ? [...new Set(journeys.map(j => j.kind))].join(', ') : 'none';
+    errors.push(
+      `QA Session ${sessionId} requested visual capture (${requestedCapture.join(', ')}) but the manifest ` +
+      `declares no kind:"browser" journey (declared kinds: ${kinds}) — an API-only draft cannot produce ` +
+      'screenshots or video.',
+    );
+  }
+
+  const declaredProjects = new Set(journeys.flatMap(j => j.projects));
+  const missingProjects = _sessionProjects(session).filter(p => !declaredProjects.has(p));
+  if (missingProjects.length) {
+    errors.push(
+      `visual-journey manifest does not cover project(s): ${missingProjects.join(', ')} — every project in ` +
+      `the session (${_sessionProjects(session).join(', ')}) must appear in some journey's \`projects\`.`,
+    );
+  }
+
+  const serviceLookup = _requiredServiceNames(session, opts);
+  if (!serviceLookup.ok) {
+    errors.push(
+      `visual-journey manifest could not be checked against session ${sessionId}'s managed-spawn inventory ` +
+      `(${serviceLookup.error}) — refusing to advance to EXECUTE without service coverage.`,
+    );
+  } else {
+    const declaredServices = new Set(journeys.flatMap(j => j.services));
+    const missingServices = serviceLookup.names.filter(n => !declaredServices.has(n));
+    if (missingServices.length) {
+      errors.push(
+        `visual-journey manifest does not cover service(s): ${missingServices.join(', ')} — every ` +
+        `managed-spawn the session owns (${serviceLookup.names.join(', ')}) must appear in some journey's ` +
+        '`services`, addressed at its OWN origin.',
+      );
+    }
+  }
+
+  for (const type of requestedCapture) {
+    const { field, ext } = EVIDENCE_CONTRACT[type];
+    const planned = journeys.some(j => j.evidence[field].some(
+      entry => entry.toLowerCase().endsWith(ext),
+    ));
+    if (!planned) {
+      errors.push(
+        `visual-journey manifest plans no ${type} evidence — capture.${type} was requested, so at least one ` +
+        `journey must plan a \`${ext}\` file under \`evidence.${field}\`.`,
+      );
+    }
+  }
+
+  if (errors.length) return reject(errors);
+  return { ok: true, required, manifest: normalized };
+}
+
+// ── EXECUTE-side evidence coverage (W-msb9kgs402813a97-c) ──────────────────
+
+function _emptyMissing() {
+  return { files: [], journeys: [], projects: [], services: [], evidenceTypes: [] };
+}
+
+/**
+ * Does a registered run artifact count as evidence for `type`?
+ *
+ * Accepts either the declared artifact `type` (the sidecar contract) or the
+ * file extension, so a run that labelled its capture `image` instead of
+ * `screenshot` is not rejected on a vocabulary technicality. The file-existence
+ * check below is what actually makes this load-bearing.
+ */
+function _artifactIsEvidenceFor(artifact, contract) {
+  const declared = typeof artifact.type === 'string' ? artifact.type.trim().toLowerCase() : '';
+  if (declared && contract.artifactTypes.includes(declared)) return true;
+  const p = typeof artifact.path === 'string' ? artifact.path.toLowerCase() : '';
+  return !!p && p.endsWith(contract.ext);
+}
+
+/**
+ * Prove one registered artifact is a real file inside the run's artifacts dir.
+ *
+ * Registration is a claim; this is the check. Paths are resolved relative to
+ * the linked run's directory (the sidecar contract), must be strictly INSIDE
+ * it (`shared.isPathInside`), and must be a non-empty regular file.
+ */
+function _checkArtifactFile(artifact, artifactsDir) {
+  const rel = typeof artifact.path === 'string' ? artifact.path : '';
+  if (!rel) return { ok: false, reason: 'has no path' };
+  if (!_isNonEmptyString(artifactsDir)) {
+    return { ok: false, reason: 'has no resolvable run artifacts directory' };
+  }
+  const resolved = path.resolve(artifactsDir, rel);
+  if (!shared.isPathInside(resolved, artifactsDir)) {
+    return { ok: false, reason: 'resolves outside the run artifacts directory' };
+  }
+  let stat;
+  try {
+    stat = fs.statSync(resolved);
+  } catch (err) {
+    return { ok: false, reason: err.code === 'ENOENT' ? 'does not exist on disk' : `is unreadable (${err.code || err.message})` };
+  }
+  if (!stat.isFile()) return { ok: false, reason: 'is not a regular file' };
+  if (!(stat.size > 0)) return { ok: false, reason: 'is a zero-byte file' };
+  return { ok: true, resolved };
+}
+
+/**
+ * EXECUTE-side evidence gate: does a green qa-run actually carry the visual
+ * evidence its session asked for, across every project and service?
+ *
+ * Runs only when the session requested screenshots or video AND a DRAFT
+ * visual-journey manifest was persisted on the record. A logs-only session, or
+ * a legacy session created before the manifest existed, is skipped entirely
+ * (`{ ok: true, required: false }`) so historical completions are untouched.
+ *
+ * When required, all three checks must hold:
+ *   (a) every requested capture type has at least one registered artifact;
+ *   (b) every such artifact resolves INSIDE the run's artifacts dir and exists
+ *       on disk with non-zero size;
+ *   (c) the union of `journeyCoverage[].projects` for PASSED journeys covers
+ *       every `session.spec.projects`, the union of `.services` covers every
+ *       `managedSpawnNamesForSession(session)` name, and every journey the
+ *       manifest declared actually reported `passed`.
+ *
+ * @param {object}   args
+ * @param {object}   args.session      - the qa-sessions record
+ * @param {object|null} args.manifest  - the persisted visual-journey manifest
+ * @param {object|null} args.run       - the linked qa-runs record
+ * @param {string|null} args.artifactsDir - qaRuns.qaArtifactsDirForRun(runId)
+ * @param {Array}    [args.services]   - injected managed-spawn inventory
+ * @returns {{ok:boolean, required:boolean,
+ *            missing:{files:string[],journeys:string[],projects:string[],
+ *                     services:string[],evidenceTypes:string[]},
+ *            errors:string[], error:string}}
+ */
+function validateEvidenceCoverage({ session, manifest, run, artifactsDir, services } = {}) {
+  const sessionId = (session && session.id) || '(unknown session)';
+  const requestedCapture = _requestedCaptureTypes(session);
+  const hasManifest = !!manifest && typeof manifest === 'object' && !Array.isArray(manifest);
+  if (requestedCapture.length === 0 || !hasManifest) {
+    return { ok: true, required: false, missing: _emptyMissing(), errors: [], error: '' };
+  }
+
+  const missing = _emptyMissing();
+  const errors = [];
+  const journeys = Array.isArray(manifest.journeys)
+    ? manifest.journeys.filter(j => j && typeof j === 'object' && _isNonEmptyString(j.id))
+    : [];
+  const artifacts = Array.isArray(run && run.artifacts)
+    ? run.artifacts.filter(a => a && typeof a === 'object')
+    : [];
+  const coverage = Array.isArray(run && run.journeyCoverage)
+    ? run.journeyCoverage.filter(c => c && typeof c === 'object' && _isNonEmptyString(c.journeyId))
+    : [];
+
+  // ── (a) + (b) registered, present, in-directory evidence ─────────────────
+  for (const type of requestedCapture) {
+    const contract = EVIDENCE_CONTRACT[type];
+    const candidates = artifacts.filter(a => _artifactIsEvidenceFor(a, contract));
+    if (candidates.length === 0) {
+      missing.evidenceTypes.push(type);
+      errors.push(
+        `QA Session ${sessionId} requested capture.${type} but the qa-run registered no ${type} artifact — ` +
+        `a green run with no ${type} evidence cannot close a visual session.`,
+      );
+      continue;
+    }
+    let usable = 0;
+    for (const artifact of candidates) {
+      const check = _checkArtifactFile(artifact, artifactsDir);
+      if (check.ok) { usable += 1; continue; }
+      const label = _isNonEmptyString(artifact.path) ? artifact.path : '(no path)';
+      if (!missing.files.includes(label)) missing.files.push(label);
+      errors.push(`registered ${type} artifact "${label}" ${check.reason}.`);
+    }
+    if (usable === 0 && !missing.evidenceTypes.includes(type)) {
+      missing.evidenceTypes.push(type);
+      errors.push(`no usable ${type} evidence survived verification for QA Session ${sessionId}.`);
+    }
+  }
+
+  // ── (c) journey / project / service coverage ─────────────────────────────
+  const passed = coverage.filter(c => c.status === 'passed');
+  const passedIds = new Set(passed.map(c => c.journeyId));
+  const unproven = journeys.map(j => j.id).filter(id => !passedIds.has(id));
+  if (unproven.length) {
+    missing.journeys = unproven;
+    errors.push(
+      `journey(s) ${unproven.join(', ')} declared by the DRAFT manifest never reported ` +
+      `\`status: "passed"\` in the qa-run's journeyCoverage — the run cannot be green on evidence it did not produce.`,
+    );
+  }
+
+  const coveredProjects = new Set(passed.flatMap(c => (Array.isArray(c.projects) ? c.projects : [])));
+  const sessionProjects = _sessionProjects(session);
+  const missingProjects = sessionProjects.filter(p => !coveredProjects.has(p));
+  if (missingProjects.length) {
+    missing.projects = missingProjects;
+    errors.push(
+      `no passed journey produced evidence for project(s): ${missingProjects.join(', ')} — every project in ` +
+      `the session (${sessionProjects.join(', ')}) must appear in some passed journey's \`projects\`.`,
+    );
+  }
+
+  const serviceLookup = _requiredServiceNames(session, { services });
+  if (!serviceLookup.ok) {
+    errors.push(
+      `evidence coverage could not be checked against session ${sessionId}'s managed-spawn inventory ` +
+      `(${serviceLookup.error}) — refusing to close the session as done.`,
+    );
+  } else {
+    const coveredServices = new Set(passed.flatMap(c => (Array.isArray(c.services) ? c.services : [])));
+    const missingServices = serviceLookup.names.filter(n => !coveredServices.has(n));
+    if (missingServices.length) {
+      missing.services = missingServices;
+      errors.push(
+        `no passed journey exercised service(s): ${missingServices.join(', ')} — every managed-spawn the ` +
+        `session owns (${serviceLookup.names.join(', ')}) must appear in some passed journey's \`services\`.`,
+      );
+    }
+  }
+
+  return {
+    ok: errors.length === 0,
+    required: true,
+    missing,
+    errors,
+    error: errors.join(' '),
+  };
+}
+
+module.exports = {
+  DRAFT_RESULT_SIDECAR_FILENAME,
+  VISUAL_COVERAGE_FAILURE_CLASS,
+  EVIDENCE_COVERAGE_FAILURE_CLASS,
+  JOURNEY_KINDS,
+  EVIDENCE_CONTRACT,
+  LIMITS,
+  draftResultSidecarPath,
+  prepareDraftResultSidecar,
+  consumeDraftResultSidecar,
+  isVisualCaptureRequested,
+  validateVisualJourneyManifest,
+  validateEvidenceCoverage,
+};