rcf-lite 0.20.0 → 0.22.0

package/src/browser-verify/pack-loader.js

@@ -0,0 +1,176 @@
+// Pack loader for blueprint-shipped probe packs
+// (visual round T-0, US-1701 AC-1701-1 / 2 / 3). CN-107.
+//
+// Given a list of applied blueprints, discovers each blueprint's
+// probe packs under `<blueprintAbsPath>/probe-packs/*.pack.{js,mjs}`,
+// imports each module dynamically, validates against the pack schema
+// (`pack-schema.js`), and cross-checks every check id against the AC
+// ids the blueprint contributes via `blueprint.json:contributions[]`.
+//
+// The loader is pure with respect to the filesystem it reads: no
+// writes, no side effects on the imported modules. It returns an
+// aggregate result (`packs`, `warnings`, `errors`) so the CLI can
+// emit one refusal diagnostic per fault rather than stop at the first.
+
+import { readdir, readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join, resolve, isAbsolute } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { validatePackModule } from './pack-schema.js';
+
+const PACK_FILENAME_RE = /\.pack\.(?:js|mjs)$/;
+
+/**
+ * Load and validate probe packs under a set of applied blueprints.
+ *
+ * @param {object} args
+ * @param {Array<{ slug: string, absPath: string }>} args.appliedBlueprints
+ *   List of blueprints on the applied shelf. `absPath` is the
+ *   directory containing the blueprint's `blueprint.json`.
+ * @param {string} [args.projectRoot]  reserved; unused today.
+ * @returns {Promise<{ packs: Array<LoadedPack>, warnings: Array<{ packAbsPath: string, message: string }>, errors: Array<{ packAbsPath: string, message: string }> }>}
+ */
+export async function loadProbePacks({ appliedBlueprints, projectRoot: _projectRoot }) {
+  const packs = [];
+  const warnings = [];
+  const errors = [];
+
+  for (const bp of Array.isArray(appliedBlueprints) ? appliedBlueprints : []) {
+    if (!bp || typeof bp.slug !== 'string' || typeof bp.absPath !== 'string' || !isAbsolute(bp.absPath)) {
+      errors.push({
+        packAbsPath: '(no path)',
+        message: `pack-loader: blueprint entry must carry { slug: string, absPath: absolute path } (got ${JSON.stringify(bp)})`,
+      });
+      continue;
+    }
+    const packsDir = join(bp.absPath, 'probe-packs');
+    if (!existsSync(packsDir)) continue;
+
+    let contributedAcIds;
+    try {
+      contributedAcIds = await readContributedAcIds({ blueprintAbsPath: bp.absPath });
+    } catch (err) {
+      errors.push({ packAbsPath: bp.absPath, message: `pack-loader: cannot read blueprint contributions for '${bp.slug}': ${err.message}` });
+      continue;
+    }
+
+    let entries;
+    try {
+      entries = await readdir(packsDir, { withFileTypes: true });
+    } catch (err) {
+      errors.push({ packAbsPath: packsDir, message: `pack-loader: cannot list probe-packs dir for '${bp.slug}': ${err.message}` });
+      continue;
+    }
+
+    const packFiles = entries
+      .filter((e) => e.isFile() && PACK_FILENAME_RE.test(e.name))
+      .map((e) => join(packsDir, e.name))
+      .sort();
+
+    for (const packAbsPath of packFiles) {
+      let mod;
+      try {
+        mod = await import(pathToFileURL(packAbsPath).href);
+      } catch (err) {
+        errors.push({ packAbsPath, message: `pack-loader: import failed for ${packAbsPath}: ${err.message}` });
+        continue;
+      }
+      const validation = validatePackModule({ mod, blueprintSlug: bp.slug, packAbsPath });
+      if (!validation.ok) {
+        for (const e of validation.errors) errors.push({ packAbsPath, message: e.message });
+        continue;
+      }
+      const pack = validation.pack;
+
+      const badCheckIds = pack.checks
+        .map((c) => c.id)
+        .filter((id) => !contributedAcIds.has(id));
+      if (badCheckIds.length > 0) {
+        errors.push({
+          packAbsPath,
+          message: `pack-loader: pack '${pack.packName}' names checks [${badCheckIds.join(', ')}] that the blueprint '${bp.slug}' does not contribute; contributed AC ids on this blueprint: ${contributedAcIds.size === 0 ? '(none)' : [...contributedAcIds].sort().join(', ')}`,
+        });
+        continue;
+      }
+
+      packs.push({
+        packName: pack.packName,
+        version: pack.version,
+        blueprintSlug: bp.slug,
+        packAbsPath,
+        appliesTo: pack.appliesTo,
+        boot: pack.boot ?? null,
+        checks: pack.checks,
+        preChecks: Array.isArray(pack.preChecks) ? pack.preChecks : [],
+      });
+    }
+  }
+
+  return { packs, warnings, errors };
+}
+
+/**
+ * Read every AC id contributed by a blueprint. A blueprint contributes ACs
+ * inside its US contribution files (`contributions[].kind === 'us'`).
+ *
+ * @param {object} args
+ * @param {string} args.blueprintAbsPath
+ * @returns {Promise<Set<string>>}
+ */
+export async function readContributedAcIds({ blueprintAbsPath }) {
+  const bpJsonPath = join(blueprintAbsPath, 'blueprint.json');
+  const bpRaw = await readFile(bpJsonPath, 'utf8');
+  let bpJson;
+  try { bpJson = JSON.parse(bpRaw); } catch (err) {
+    throw new Error(`invalid JSON in ${bpJsonPath}: ${err.message}`);
+  }
+  const contributions = Array.isArray(bpJson?.contributions) ? bpJson.contributions : [];
+  const acIds = new Set();
+  for (const c of contributions) {
+    if (c?.kind !== 'us' || typeof c.path !== 'string') continue;
+    // blueprint.json contribution paths are relative to the blueprint's
+    // `contributions/` subdirectory (see src/blueprint/loader.js). Older
+    // tests supplied paths that included `contributions/` at the root
+    // instead; probe for both shapes so shelf blueprints and hand-rolled
+    // fixtures both load without a per-caller convention.
+    const insideContributions = resolve(blueprintAbsPath, 'contributions', c.path);
+    const legacyRootRelative = resolve(blueprintAbsPath, c.path);
+    let usAbs = insideContributions;
+    let usRaw;
+    try {
+      usRaw = await readFile(insideContributions, 'utf8');
+    } catch (primaryErr) {
+      try {
+        usRaw = await readFile(legacyRootRelative, 'utf8');
+        usAbs = legacyRootRelative;
+      } catch {
+        throw new Error(`cannot read US contribution ${c.path}: ${primaryErr.message}`);
+      }
+    }
+    let usJson;
+    try {
+      usJson = JSON.parse(usRaw);
+    } catch (err) {
+      throw new Error(`cannot read US contribution ${c.path}: ${err.message}`);
+    }
+    void usAbs;
+    const inlineAcs = Array.isArray(usJson?.acceptanceCriteria) ? usJson.acceptanceCriteria : [];
+    for (const ac of inlineAcs) {
+      if (typeof ac?.id === 'string') acIds.add(ac.id);
+    }
+  }
+  return acIds;
+}
+
+/**
+ * @typedef {object} LoadedPack
+ * @property {string} packName
+ * @property {string} version
+ * @property {string} blueprintSlug
+ * @property {string} packAbsPath
+ * @property {(ctx: { fbs: object, uiBaseline: object|null, manifest: object|null }) => boolean} appliesTo
+ * @property {object|null} boot
+ * @property {Array<{ id: string, severity: 'block'|'warn'|'advisory', description: string, run: (ctx: object) => Promise<{ verdict: 'pass'|'warn'|'fail'|'skipped', detail?: string }>, dependsOn?: string|string[] }>} checks
+ * @property {Array<{ id: string, severity: 'block'|'warn'|'advisory', description: string, run: () => Promise<{ verdict: 'pass'|'warn'|'fail', detail?: string }> }>} preChecks
+ */

package/src/browser-verify/pack-runner.js

@@ -0,0 +1,193 @@
+// Pack pass runner (visual round T-0, US-1701 AC-1701-4 / 6). CN-108.
+//
+// Invokes every applicable loaded pack against a FBS and folds the
+// results into a `probePacks[]` array on the browserVerification
+// record. Applicability is enforced by the pack's own `appliesTo`
+// predicate: a false return records `applicable: false` and no
+// check runs. `preChecks[]` (if any) run first; a failing pre-check
+// causes browser checks that name it under `dependsOn` to record
+// `skipped` with detail `skipped-by-pre-check:<preCheckId>`.
+//
+// The runner is browser-driver-agnostic: the caller injects a
+// `browser` seam (the same shape a pack's `run` expects on its `browser`
+// argument) plus `fetch`, `runtimeUrl` and the route/theme cursor.
+
+/**
+ * Run applicable packs for one FBS.
+ *
+ * @param {object} args
+ * @param {Array<import('./pack-loader.js').LoadedPack>} args.packs
+ * @param {object} args.fbs
+ * @param {object|null} args.uiBaseline
+ * @param {object|null} args.manifest
+ * @param {object|null} args.browser        injected browser (or null in unit tests)
+ * @param {(url: string, init?: object) => Promise<any>|null} args.fetch
+ * @param {string} args.runtimeUrl
+ * @param {Array<object>} args.routes       FBS routes (nav model)
+ * @param {Array<'light'|'dark'>} args.themes
+ * @param {string} [args.packNameFilter]    when set, only packs whose packName === filter are considered
+ * @param {(pack: import('./pack-loader.js').LoadedPack) => object} [args.buildContext]  optional context override for unit tests
+ * @returns {Promise<{ probePacks: Array<object>, packHighestSeverityFail: 'block'|'warn'|null }>}
+ */
+export async function runProbePacksForFbs({
+  packs,
+  fbs,
+  uiBaseline,
+  manifest,
+  projectRoot = null,
+  browser,
+  fetch,
+  runtimeUrl,
+  routes,
+  themes,
+  packNameFilter,
+  buildContext,
+}) {
+  const probePacks = [];
+  let highest = null;
+  const chosen = Array.isArray(packs) ? packs : [];
+  const primaryRoute = Array.isArray(routes) && routes.length > 0 ? routes[0] : null;
+  const primaryTheme = Array.isArray(themes) && themes.length > 0 ? themes[0] : 'light';
+
+  for (const pack of chosen) {
+    if (typeof packNameFilter === 'string' && packNameFilter.length > 0 && pack.packName !== packNameFilter) {
+      continue;
+    }
+
+    let applicable;
+    let applicabilityDetail;
+    try {
+      applicable = Boolean(pack.appliesTo({ fbs, uiBaseline, manifest }));
+    } catch (err) {
+      applicable = false;
+      applicabilityDetail = `appliesTo threw: ${err.message}`;
+    }
+
+    if (!applicable) {
+      probePacks.push({
+        packName: pack.packName,
+        packVersion: pack.version,
+        blueprintSlug: pack.blueprintSlug,
+        applicable: false,
+        ...(applicabilityDetail ? { detail: applicabilityDetail } : { detail: `appliesTo returned false for ${fbs?.fbsId ?? '(no fbs)'}` }),
+        checks: [],
+      });
+      continue;
+    }
+
+    // Pre-checks first.
+    const preCheckRecords = [];
+    const failedPreCheckIds = new Set();
+    for (const pre of pack.preChecks) {
+      let verdict = 'pass';
+      let detail;
+      try {
+        const outcome = await pre.run({ fbs, uiBaseline, manifest, runtimeUrl, fetch, browser });
+        verdict = outcome?.verdict ?? 'pass';
+        detail = outcome?.detail;
+      } catch (err) {
+        verdict = 'fail';
+        detail = `pre-check threw: ${err.message}`;
+      }
+      preCheckRecords.push({
+        id: pre.id,
+        verdict,
+        severity: pre.severity,
+        ...(typeof detail === 'string' && detail.length > 0 ? { detail } : {}),
+      });
+      if (verdict === 'fail') failedPreCheckIds.add(pre.id);
+      if (verdict === 'fail' && pre.severity === 'block') highest = 'block';
+      else if (verdict === 'fail' && pre.severity === 'warn' && highest !== 'block') highest = 'warn';
+    }
+
+    const checkRecords = [];
+    for (const check of pack.checks) {
+      const deps = normaliseDependsOn(check.dependsOn);
+      const failingDep = deps.find((d) => failedPreCheckIds.has(d));
+      if (failingDep) {
+        checkRecords.push({
+          id: check.id,
+          verdict: 'skipped',
+          severity: check.severity,
+          detail: `skipped-by-pre-check:${failingDep}`,
+        });
+        continue;
+      }
+      // Per-check applicability (visual round T-5 spec section 5.5).
+      // A pack check may declare its own `appliesTo` predicate that
+      // reads the applied capability set (from projectRoot) so an
+      // absent capability records `applicable: false` and the
+      // aggregate verdict treats the check as neither pass nor fail.
+      // A check without a predicate always runs (backward compatible
+      // with T-0 through T-4 packs).
+      if (typeof check.appliesTo === 'function') {
+        let checkApplicable;
+        let checkAppliesDetail;
+        try {
+          checkApplicable = Boolean(await check.appliesTo({ fbs, uiBaseline, manifest, projectRoot }));
+        } catch (err) {
+          checkApplicable = false;
+          checkAppliesDetail = `appliesTo threw: ${err.message}`;
+        }
+        if (!checkApplicable) {
+          // Spec section 5.5 says the residual cure records
+          // applicable: false at the check level. rcf-schemas 0.6.1
+          // (browserVerificationProbePackCheck) closes the schema and
+          // still requires a verdict enum, so the manifest write path
+          // refuses a check that carries `applicable: false` alone.
+          // Until the schema minor promotes an `applicable` field at
+          // the check level (follow-up rcf-schemas bump), emit
+          // `verdict: 'skipped'` with a detail naming the applicability
+          // gate. Semantically the aggregate verdict still treats this
+          // as neither pass nor fail (skipped does not raise `highest`).
+          checkRecords.push({
+            id: check.id,
+            verdict: 'skipped',
+            severity: check.severity,
+            detail: checkAppliesDetail ?? 'check appliesTo returned false (required capability not applied)',
+          });
+          continue;
+        }
+      }
+      const context = typeof buildContext === 'function'
+        ? buildContext(pack)
+        : { browser, fetch, runtimeUrl, route: primaryRoute, theme: primaryTheme, projectRoot };
+      let verdict = 'pass';
+      let detail;
+      try {
+        const outcome = await check.run(context);
+        verdict = outcome?.verdict ?? 'pass';
+        detail = outcome?.detail;
+      } catch (err) {
+        verdict = 'fail';
+        detail = `check threw: ${err.message}`;
+      }
+      checkRecords.push({
+        id: check.id,
+        verdict,
+        severity: check.severity,
+        ...(typeof detail === 'string' && detail.length > 0 ? { detail } : {}),
+      });
+      if (verdict === 'fail' && check.severity === 'block') highest = 'block';
+      else if (verdict === 'fail' && check.severity === 'warn' && highest !== 'block') highest = 'warn';
+    }
+
+    const record = {
+      packName: pack.packName,
+      packVersion: pack.version,
+      blueprintSlug: pack.blueprintSlug,
+      applicable: true,
+      checks: checkRecords,
+    };
+    if (preCheckRecords.length > 0) record.preChecks = preCheckRecords;
+    probePacks.push(record);
+  }
+
+  return { probePacks, packHighestSeverityFail: highest };
+}
+
+function normaliseDependsOn(dependsOn) {
+  if (typeof dependsOn === 'string' && dependsOn.length > 0) return [dependsOn];
+  if (Array.isArray(dependsOn)) return dependsOn.filter((d) => typeof d === 'string' && d.length > 0);
+  return [];
+}

package/src/browser-verify/pack-schema.js

@@ -0,0 +1,155 @@
+// Pack schema validator for blueprint-shipped probe packs
+// (visual round T-0, US-1701 AC-1701-1/2). CN-106.
+//
+// Validates a pack module's exported default object against the
+// section 3.2 shape. Enforces the field-level rules the loader must
+// refuse at load time (packName grammar and blueprint-slug prefix,
+// version semver, blueprintSlug matches directory, appliesTo function
+// referencing one of the three legal scoping seams, checks[] non-empty
+// with an id / severity / description / async run per entry).
+//
+// Returns a plain-JS shape (not RcfError): the loader wraps refusals
+// in its own diagnostic aggregate, so a single validation call reports
+// every issue on one pack instead of stopping at the first.
+
+const PACK_NAME_RE = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+const SEMVER_RE = /^\d+\.\d+\.\d+(?:-[A-Za-z0-9.-]+)?$/;
+const CHECK_ID_RE = /^AC-\d{3,}-\d+$/;
+const SEVERITIES = new Set(['block', 'warn', 'advisory']);
+
+const APPLIES_TO_TOKENS = [
+  { key: 'route', matcher: /\broute\b|\bnavModel\b|\bpath\b/ },
+  { key: 'tacIds', matcher: /\btacIds?\b/ },
+  { key: 'blueprintTag', matcher: /blueprint:/ },
+];
+
+/**
+ * Validate a pack module's exported default object.
+ *
+ * @param {object} args
+ * @param {object} args.mod  the imported module (its `.default` is the pack object).
+ * @param {string} args.blueprintSlug  the owning blueprint slug (directory).
+ * @param {string} args.packAbsPath  absolute path of the pack file, for error context.
+ * @returns {{ ok: true, pack: object } | { ok: false, errors: Array<{ field: string, message: string }> }}
+ */
+export function validatePackModule({ mod, blueprintSlug, packAbsPath }) {
+  const errors = [];
+  const pack = mod?.default;
+  if (!pack || typeof pack !== 'object') {
+    return { ok: false, errors: [{ field: 'default', message: `pack ${packAbsPath}: missing default export (expected an object)` }] };
+  }
+
+  if (typeof pack.packName !== 'string' || pack.packName.length === 0) {
+    errors.push({ field: 'packName', message: `pack ${packAbsPath}: packName must be a non-empty string` });
+  } else if (!PACK_NAME_RE.test(pack.packName)) {
+    errors.push({ field: 'packName', message: `pack ${packAbsPath}: packName '${pack.packName}' must match ${PACK_NAME_RE}` });
+  } else if (pack.packName !== blueprintSlug && !pack.packName.startsWith(`${blueprintSlug}-`)) {
+    errors.push({ field: 'packName', message: `pack ${packAbsPath}: packName '${pack.packName}' must equal the blueprint slug '${blueprintSlug}' or start with '${blueprintSlug}-'` });
+  }
+
+  if (typeof pack.version !== 'string' || !SEMVER_RE.test(pack.version)) {
+    errors.push({ field: 'version', message: `pack ${packAbsPath}: version must be semver (got ${JSON.stringify(pack.version)})` });
+  }
+
+  if (typeof pack.blueprintSlug !== 'string' || pack.blueprintSlug.length === 0) {
+    errors.push({ field: 'blueprintSlug', message: `pack ${packAbsPath}: blueprintSlug must be a non-empty string` });
+  } else if (pack.blueprintSlug !== blueprintSlug) {
+    errors.push({ field: 'blueprintSlug', message: `pack ${packAbsPath}: blueprintSlug '${pack.blueprintSlug}' must match the enclosing directory '${blueprintSlug}'` });
+  }
+
+  if (typeof pack.appliesTo !== 'function') {
+    errors.push({ field: 'appliesTo', message: `pack ${packAbsPath}: appliesTo is required and must be a function ({ fbs, uiBaseline, manifest }) => boolean` });
+  } else {
+    const source = String(pack.appliesTo);
+    const matched = APPLIES_TO_TOKENS.filter((t) => t.matcher.test(source)).map((t) => t.key);
+    if (matched.length === 0) {
+      errors.push({
+        field: 'appliesTo',
+        message: `pack ${packAbsPath}: appliesTo must reference one of { route (or navModel/path), tacIds, blueprint:<slug> tag }; got source ${trimForError(source)}. The default '() => true' predicate is refused; scope the pack to the FBS surface it probes.`,
+      });
+    }
+  }
+
+  if (pack.boot !== undefined && pack.boot !== null && typeof pack.boot !== 'object') {
+    errors.push({ field: 'boot', message: `pack ${packAbsPath}: boot must be an object or null when present (fields bootCommand, waitForUrl, waitForSelector are optional)` });
+  }
+
+  if (!Array.isArray(pack.checks) || pack.checks.length === 0) {
+    errors.push({ field: 'checks', message: `pack ${packAbsPath}: checks must be a non-empty array` });
+  } else {
+    const seenIds = new Set();
+    pack.checks.forEach((check, index) => {
+      const at = `checks[${index}]`;
+      if (!check || typeof check !== 'object') {
+        errors.push({ field: at, message: `pack ${packAbsPath}: ${at} must be an object` });
+        return;
+      }
+      if (typeof check.id !== 'string' || !CHECK_ID_RE.test(check.id)) {
+        errors.push({ field: `${at}.id`, message: `pack ${packAbsPath}: ${at}.id must match ${CHECK_ID_RE} (got ${JSON.stringify(check.id)})` });
+      } else if (seenIds.has(check.id)) {
+        errors.push({ field: `${at}.id`, message: `pack ${packAbsPath}: ${at}.id '${check.id}' duplicates an earlier check on the same pack` });
+      } else {
+        seenIds.add(check.id);
+      }
+      if (!SEVERITIES.has(check.severity)) {
+        errors.push({ field: `${at}.severity`, message: `pack ${packAbsPath}: ${at}.severity must be one of ${[...SEVERITIES].join(' | ')} (got ${JSON.stringify(check.severity)})` });
+      }
+      if (typeof check.description !== 'string' || check.description.length === 0) {
+        errors.push({ field: `${at}.description`, message: `pack ${packAbsPath}: ${at}.description must be a non-empty string` });
+      }
+      if (typeof check.run !== 'function') {
+        errors.push({ field: `${at}.run`, message: `pack ${packAbsPath}: ${at}.run must be an async function` });
+      }
+      if (check.dependsOn !== undefined && !(typeof check.dependsOn === 'string' || (Array.isArray(check.dependsOn) && check.dependsOn.every((d) => typeof d === 'string')))) {
+        errors.push({ field: `${at}.dependsOn`, message: `pack ${packAbsPath}: ${at}.dependsOn must be a string or an array of strings (pre-check ids)` });
+      }
+    });
+  }
+
+  if (pack.preChecks !== undefined) {
+    if (!Array.isArray(pack.preChecks)) {
+      errors.push({ field: 'preChecks', message: `pack ${packAbsPath}: preChecks must be an array when present` });
+    } else {
+      const seenPre = new Set();
+      pack.preChecks.forEach((pre, index) => {
+        const at = `preChecks[${index}]`;
+        if (!pre || typeof pre !== 'object') {
+          errors.push({ field: at, message: `pack ${packAbsPath}: ${at} must be an object` });
+          return;
+        }
+        if (typeof pre.id !== 'string' || pre.id.length === 0) {
+          errors.push({ field: `${at}.id`, message: `pack ${packAbsPath}: ${at}.id must be a non-empty string` });
+        } else if (seenPre.has(pre.id)) {
+          errors.push({ field: `${at}.id`, message: `pack ${packAbsPath}: ${at}.id '${pre.id}' duplicates an earlier pre-check on the same pack` });
+        } else {
+          seenPre.add(pre.id);
+        }
+        if (!SEVERITIES.has(pre.severity)) {
+          errors.push({ field: `${at}.severity`, message: `pack ${packAbsPath}: ${at}.severity must be one of ${[...SEVERITIES].join(' | ')} (got ${JSON.stringify(pre.severity)})` });
+        }
+        if (typeof pre.description !== 'string' || pre.description.length === 0) {
+          errors.push({ field: `${at}.description`, message: `pack ${packAbsPath}: ${at}.description must be a non-empty string` });
+        }
+        if (typeof pre.run !== 'function') {
+          errors.push({ field: `${at}.run`, message: `pack ${packAbsPath}: ${at}.run must be an async function` });
+        }
+      });
+    }
+  }
+
+  if (errors.length > 0) return { ok: false, errors };
+  return { ok: true, pack };
+}
+
+function trimForError(s) {
+  const trimmed = String(s).replace(/\s+/g, ' ').trim();
+  return trimmed.length > 80 ? `${trimmed.slice(0, 77)}...` : trimmed;
+}
+
+export const PACK_SCHEMA_INTERNALS = Object.freeze({
+  PACK_NAME_RE,
+  SEMVER_RE,
+  CHECK_ID_RE,
+  SEVERITIES,
+  APPLIES_TO_TOKENS,
+});

package/src/browser-verify/runner.js

@@ -20,6 +20,7 @@
 import { runInvariantsForCapture, foldInvariantsForRecord, compareTopLevelStructure } from './invariants.js';
 import { runAuthSmokeChecks, shouldRunAuthSmokeChecks } from './auth-smoke.js';
 import { composeBrowserVerificationRecord } from './manifest-writer.js';
+import { runProbePacksForFbs } from './pack-runner.js';
 
 /**
  * @typedef {object} BrowserCapture
@@ -63,7 +64,8 @@ export const stubBrowserDriver = Object.freeze({
  * @returns {Promise<object>}  the composed browserVerification record
  */
 export async function runAgentScreenshotCritique({
-  tree, fbs, runtimeUrl, runtimeProfile, browserDriver, fetch, artefactDir, critiqueNotes, now = new Date(),
+  tree, fbs, runtimeUrl, runtimeProfile, browserDriver, fetch, artefactDir, critiqueNotes,
+  probePacks = [], packBrowser = null, packNameFilter, projectRoot = null, now = new Date(),
 }) {
   const routes = fbs?.designStage?.navModel?.routes ?? [];
   const themes = readThemesFromBaseline(tree.manifest?.uiBaseline);
@@ -124,6 +126,26 @@ export async function runAgentScreenshotCritique({
     authSmokeChecks = await runAuthSmokeChecks({ fetch, runtimeUrl });
   }
 
+  // Probe-pack pass: runs after invariants and auth-smoke
+  // (visual-round-spec-2026-09-04 §3.4).
+  let packRecords = [];
+  if (Array.isArray(probePacks) && probePacks.length > 0) {
+    const result = await runProbePacksForFbs({
+      packs: probePacks,
+      fbs,
+      uiBaseline: tree.manifest?.uiBaseline ?? null,
+      manifest: tree.manifest ?? null,
+      projectRoot,
+      browser: packBrowser,
+      fetch,
+      runtimeUrl,
+      routes,
+      themes,
+      packNameFilter,
+    });
+    packRecords = result.probePacks;
+  }
+
   return composeBrowserVerificationRecord({
     manifest: tree.manifest,
     fbsId: fbs.fbsId,
@@ -133,6 +155,7 @@ export async function runAgentScreenshotCritique({
     routesChecked,
     invariantChecks,
     authSmokeChecks,
+    probePacks: packRecords,
     notes,
     now,
   });