@wix/agent-skills 1.33.0 → 1.34.0

package/skills/wix-replatform/lib/document-url-guard.js

@@ -0,0 +1,203 @@
+'use strict';
+
+// One home for "is this URL safe to hand to something that will fetch it".
+//
+// A discovered invoice document URL is untrusted input from source-site metadata, and TWO modules
+// act on it: discovery classifies and probes it, and the target writer hands it to Wix Media to
+// fetch server-side. Both must apply the same rules, so the rules live here rather than in either
+// one. While they lived only in discovery, the writer accepted a bare URL and imported
+// `https://169.254.169.254/latest/meta-data` without complaint.
+//
+// The URL is also a bearer link whose filename can carry a customer name and an invoice number,
+// so nothing here logs it or returns it in full.
+//
+// WHAT THIS CANNOT DO, stated because a guard that looks stronger than it is invites misuse.
+// `classifyDocumentUrl` is a LEXICAL check on the URL as written: it does not resolve DNS and it
+// does not follow redirects, so a public hostname that resolves to a private address, or one that
+// redirects to it, passes it. It must therefore never be the only thing between an untrusted URL
+// and a server-side fetch. `fetchPublicDocument` is the fetch that is safe to run on our side:
+// it resolves the host, refuses any private answer, connects to the ADDRESS IT VALIDATED (so the
+// name cannot resolve differently between check and connect -- no DNS rebinding), walks redirects
+// hop by hop applying the same checks, and caps the response size. The bytes are then uploaded to
+// Wix Media, so Wix never fetches an untrusted URL at all.
+
+const dns = require('node:dns');
+
+const PRIVATE_IPV4 = [
+  /^10\./,
+  /^127\./,
+  /^169\.254\./,
+  /^192\.168\./,
+  /^172\.(1[6-9]|2\d|3[01])\./,
+  /^0\./,
+  /^100\.(6[4-9]|[7-9]\d|1[01]\d|12[0-7])\./, // carrier-grade NAT
+];
+
+function isPrivateHostname(hostname) {
+  let host = String(hostname || '').toLowerCase().replace(/^\[|\]$/g, '');
+
+  // An IPv4-mapped IPv6 address is the same destination wearing a different notation, and Node
+  // canonicalizes `::ffff:127.0.0.1` to `::ffff:7f00:1` -- so a loopback check that only knows
+  // dotted-quad form waves it straight through. Unwrap the mapping, in both spellings, before
+  // any other test runs.
+  const mappedDotted = host.match(/^::ffff:(\d{1,3}(?:\.\d{1,3}){3})$/);
+  if (mappedDotted) host = mappedDotted[1];
+  const mappedHex = host.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
+  if (mappedHex) {
+    const high = parseInt(mappedHex[1], 16);
+    const low = parseInt(mappedHex[2], 16);
+    host = [high >> 8, high & 0xff, low >> 8, low & 0xff].join('.');
+  }
+  if (host === 'localhost' || host.endsWith('.localhost') || host.endsWith('.local')) return true;
+  if (host === '::1' || host === '::' || host.startsWith('fc') || host.startsWith('fd') || host.startsWith('fe80')) return true;
+  if (PRIVATE_IPV4.some((pattern) => pattern.test(host))) return true;
+  return false;
+}
+
+// Signal D. Every discovered document is classified, not only the sampled ones -- the strategy
+// depends on where the bytes are, and one WordPress-hosted document in an otherwise PSP-hosted
+// store still dies with the source site.
+function classifyDocumentUrl(rawUrl, { sourceSiteHost = null } = {}) {
+  const text = String(rawUrl || '').trim();
+  if (text.length === 0) return { safe: false, location: null, reason: 'empty-url' };
+
+  let url;
+  try {
+    url = new URL(text);
+  } catch (error) {
+    return { safe: false, location: null, reason: 'unparseable-url' };
+  }
+
+  if (url.protocol !== 'https:') return { safe: false, location: null, reason: 'not-https' };
+  if (url.username || url.password) return { safe: false, location: null, reason: 'embedded-credentials' };
+  if (url.port && url.port !== '443') return { safe: false, location: null, reason: 'non-standard-port' };
+  if (isPrivateHostname(url.hostname)) return { safe: false, location: null, reason: 'private-or-loopback-host' };
+
+  const host = url.hostname.toLowerCase();
+  const sameSite = sourceSiteHost
+    && (host === String(sourceSiteHost).toLowerCase() || host.endsWith(`.${String(sourceSiteHost).toLowerCase()}`));
+
+  // A same-origin uploads path is the WordPress filesystem: those bytes are gone when the site
+  // goes. Anything else is somebody else's archive, which survives the migration but not the
+  // merchant leaving that provider.
+  const location = sameSite ? 'wordpress' : 'third-party';
+  return { safe: true, location, reason: null, host };
+}
+
+const MAX_REDIRECTS = 3;
+const FETCH_TIMEOUT_MS = 20000;
+const DEFAULT_MAX_BYTES = 25 * 1024 * 1024;
+
+// Default transport: one GET over HTTPS, pinned to an address the caller already validated. TLS
+// still verifies the certificate against the hostname (`servername`), so pinning the address does
+// not weaken it. The body is read up to `maxBytes` and the connection is dropped past that.
+function pinnedHttpsGet(url, { address, family, timeoutMs, maxBytes }) {
+  const https = require('node:https');
+  const target = new URL(url);
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const done = (fn, value) => { if (!settled) { settled = true; fn(value); } };
+    const request = https.request({
+      protocol: 'https:',
+      hostname: target.hostname,
+      port: 443,
+      path: `${target.pathname}${target.search}`,
+      method: 'GET',
+      servername: target.hostname,
+      headers: { Accept: '*/*', 'Accept-Encoding': 'identity', 'User-Agent': 'wix-replatform-document-fetch' },
+      lookup: (hostname, options, callback) => (options && options.all
+        ? callback(null, [{ address, family }])
+        : callback(null, address, family)),
+      timeout: timeoutMs,
+    }, (response) => {
+      const status = response.statusCode || 0;
+      const headers = { get: (name) => { const value = response.headers[String(name).toLowerCase()]; return Array.isArray(value) ? value[0] : (value === undefined ? null : value); } };
+      if (status >= 300 && status < 400) { response.resume(); done(resolve, { status, headers, body: Buffer.alloc(0) }); return; }
+      const declared = Number(response.headers['content-length']);
+      if (Number.isFinite(declared) && declared > maxBytes) { response.destroy(); done(reject, Object.assign(new Error('response-too-large'), { code: 'TOO_LARGE' })); return; }
+      const chunks = [];
+      let total = 0;
+      response.on('data', (chunk) => {
+        total += chunk.length;
+        if (total > maxBytes) { response.destroy(); done(reject, Object.assign(new Error('response-too-large'), { code: 'TOO_LARGE' })); return; }
+        chunks.push(chunk);
+      });
+      response.on('end', () => done(resolve, { status, headers, body: Buffer.concat(chunks) }));
+      response.on('error', (error) => done(reject, error));
+    });
+    request.on('timeout', () => { request.destroy(); done(reject, Object.assign(new Error('timeout'), { code: 'TIMEOUT' })); });
+    request.on('error', (error) => done(reject, error));
+    request.end();
+  });
+}
+
+// Fetches the document's bytes on our side, never handing the URL to anything else. Returns
+// { ok: true, bytes, contentType } or { ok: false, unsafe, reason }. `unsafe` separates a URL we
+// refuse on principle (internal address, redirect to one, bad scheme) from a document that is
+// merely unavailable (404, timeout, too large). `lookup` and `transport` are injectable.
+async function fetchPublicDocument(rawUrl, {
+  lookup = dns.promises.lookup,
+  transport = pinnedHttpsGet,
+  maxRedirects = MAX_REDIRECTS,
+  timeoutMs = FETCH_TIMEOUT_MS,
+  maxBytes = DEFAULT_MAX_BYTES,
+} = {}) {
+  let current = String(rawUrl || '').trim();
+  for (let hop = 0; hop <= maxRedirects; hop += 1) {
+    const classification = classifyDocumentUrl(current);
+    if (!classification.safe) return { ok: false, unsafe: true, reason: hop === 0 ? classification.reason : `redirect-${classification.reason}` };
+    let addresses;
+    try {
+      addresses = await lookup(new URL(current).hostname, { all: true });
+    } catch (error) {
+      return { ok: false, unsafe: false, reason: 'host-not-resolvable' };
+    }
+    const list = (Array.isArray(addresses) ? addresses : [addresses]).filter(Boolean);
+    if (!list.length || list.some((entry) => isPrivateHostname(entry.address))) {
+      return { ok: false, unsafe: true, reason: 'resolves-to-private-address' };
+    }
+    const pinned = list[0];
+    let response;
+    try {
+      response = await transport(current, { address: pinned.address, family: pinned.family || (String(pinned.address).includes(':') ? 6 : 4), timeoutMs, maxBytes });
+    } catch (error) {
+      return { ok: false, unsafe: false, reason: error && error.code === 'TOO_LARGE' ? 'response-too-large' : 'unreachable' };
+    }
+    if (response.status >= 300 && response.status < 400) {
+      const location = response.headers && response.headers.get && response.headers.get('location');
+      if (!location) return { ok: false, unsafe: true, reason: 'redirect-without-location' };
+      try {
+        current = new URL(location, current).toString();
+      } catch (error) {
+        return { ok: false, unsafe: true, reason: 'redirect-unparseable-url' };
+      }
+      continue;
+    }
+    if (response.status < 200 || response.status >= 300) return { ok: false, unsafe: false, reason: `http-${response.status}` };
+    const body = Buffer.isBuffer(response.body) ? response.body : Buffer.from(response.body || '');
+    if (body.length > maxBytes) return { ok: false, unsafe: false, reason: 'response-too-large' };
+    if (body.length === 0) return { ok: false, unsafe: false, reason: 'empty-document' };
+    const contentType = response.headers && response.headers.get ? response.headers.get('content-type') : null;
+    return { ok: true, bytes: body, contentType: contentType ? String(contentType).split(';')[0].trim().toLowerCase() : null };
+  }
+  return { ok: false, unsafe: true, reason: 'too-many-redirects' };
+}
+
+// Never log or persist a raw document URL: the query string can carry a bearer token and the
+// filename can carry the customer's name and the invoice number.
+function redactUrlForLog(rawUrl) {
+  try {
+    const url = new URL(String(rawUrl));
+    const segments = url.pathname.split('/').filter(Boolean).length;
+    return `${url.protocol}//${url.hostname}/<${segments} path segment(s) redacted>`;
+  } catch (error) {
+    return '<unparseable url redacted>';
+  }
+}
+
+module.exports = {
+  isPrivateHostname,
+  classifyDocumentUrl,
+  fetchPublicDocument,
+  redactUrlForLog,
+};

package/skills/wix-replatform/lib/entity-qa-attestation.js

@@ -0,0 +1,339 @@
+'use strict';
+
+// The entity-QA attestation gate on migration finalization.
+//
+// An entity-by-entity QA pass is mandatory before an import phase counts as done
+// (`rp-execute-import/SKILL.md`), but only in prose -- nothing checked that it happened, or
+// that it checked the report that actually shipped. This module is the check: a pure validator
+// (`validateEntityQaAttestation`) that mirrors `setup-verification.js`'s `isSetupVerified`
+// pattern -- fail closed, and judge coverage against an INDEPENDENT list the attestation
+// cannot have produced itself (`mappedEntities`, resolved by the caller from
+// `mapping/mapping-plan.json` or, for quick mode, `quick-mode/plan.json` -- never from the
+// completion report or the attestation under test).
+//
+// The gate proves freshness and coverage, not that the QA pass actually happened. A hollow attestation that copies the report's own
+// counts and marks every blocked row reverified still passes. That is an accepted limit, not
+// a defect -- `isSetupVerified` has the identical limit already.
+
+const SCHEMA_VERSION = 1;
+
+const ENTITY_QA_ATTESTATION_FILE = 'execution/qa/entity-qa-attestation.json';
+
+// The ten fields `completion-report.js`'s `normalizeCompletenessRow` writes to every
+// `entityCompleteness[]` row. `reconciled`/`expectedReconciled`/`mismatch` are pure functions
+// of these and are deliberately not attested separately.
+const FULL_MODE_FIELDS = [
+  'extracted',
+  'inScope',
+  'attempted',
+  'imported',
+  'alreadyPresentByCrosswalk',
+  'deferred',
+  'failed',
+  'unresolved',
+  'skippedOutOfScope',
+  'unexpectedSkipped',
+];
+
+const QUICK_MODE_FIELDS = ['imported', 'skipped'];
+
+function entityKey(entity, subtype) {
+  return `${entity}/${subtype || 'all'}`;
+}
+
+// Normalizes whatever shape the caller's independent mapped-entity source carries (full mode:
+// `website-handoff.js`'s `readEntityMappings` rows, keyed by `sourceEntity`; quick mode:
+// `quick-mode/plan.json`'s own `entities` rows, keyed by `id`) into a `key -> {entity,
+// subtype}` map. Rows with no recognizable entity name are dropped, never counted as coverage.
+// Returns `null` when the input itself isn't a usable array at all (as opposed to a usable,
+// but empty-after-normalization, array) -- both cases resolve to "unavailable" one level up,
+// but keeping them distinct helps a caller that wants to know which happened.
+function normalizeMappedEntities(mappedEntities) {
+  if (!Array.isArray(mappedEntities)) return null;
+  const map = new Map();
+  for (const row of mappedEntities) {
+    if (!row || typeof row !== 'object') continue;
+    const entity = firstNonEmptyString(row.entity, row.sourceEntity, row.id);
+    if (!entity) continue;
+    const subtype = typeof row.subtype === 'string' && row.subtype ? row.subtype : 'all';
+    map.set(entityKey(entity, subtype), { entity, subtype });
+  }
+  return map;
+}
+
+function firstNonEmptyString(...values) {
+  for (const value of values) {
+    if (typeof value === 'string' && value) return value;
+  }
+  return null;
+}
+
+// Indexes a full-mode report's `entityCompleteness[]` rows by `entity/subtype`. A row missing
+// `entity` entirely can never be matched against anything and is dropped, same as
+// `normalizeMappedEntities`.
+function indexFullModeReportRows(report) {
+  const map = new Map();
+  const rows = report && Array.isArray(report.entityCompleteness) ? report.entityCompleteness : [];
+  for (const row of rows) {
+    if (!row || typeof row !== 'object' || !row.entity) continue;
+    const subtype = row.subtype || 'all';
+    map.set(entityKey(row.entity, subtype), row);
+  }
+  return map;
+}
+
+function numericFieldValue(value) {
+  return typeof value === 'number' && Number.isFinite(value) ? value : 0;
+}
+
+// Quick mode's `imported`/`skipped` maps are keyed by plain entity id (no subtype). `skipped`
+// may be an array of per-record skip reasons (as `rp-quick-shopify` writes) or entirely absent
+// (as `rp-quick-woocommerce`'s summary is) -- either resolves to a count, and an absent map
+// resolves to 0 for every entity, never a mismatch (the WooCommerce quick-mode case).
+function quickModeCount(container, entity) {
+  if (!container || typeof container !== 'object') return 0;
+  const value = container[entity];
+  if (Array.isArray(value)) return value.length;
+  return numericFieldValue(value);
+}
+
+function quickModeEntityPresent(container, entity) {
+  return !!(container && typeof container === 'object' && Object.prototype.hasOwnProperty.call(container, entity));
+}
+
+// A duplicate `entity/subtype` row must not silently let the
+// last one win -- `setup-verification.js`'s `isSetupVerified`, which this validator mirrors,
+// flags a duplicate requirement id instead of dropping it quietly (`normalizeIds`'s
+// `onDuplicate`). `duplicateKeys` collects every key seen more than once so the caller can
+// raise a finding for it.
+//
+// `normalizeIds` keeps the FIRST occurrence of
+// a duplicate id for everything downstream (`seen.has(id)` short-circuits every later one via
+// `continue`, before it can overwrite anything) -- it does not compare values at all, but the
+// keep-first discipline is the behavior this mirrors. This indexer now keeps the first
+// occurrence of a duplicate key too (the finding is raised regardless, and a duplicate already
+// fails the gate on its own either way, but the row used for the count comparison -- and
+// reported in `entities` -- is now deterministically the first one seen, not the last).
+function indexAttestationEntities(attestation) {
+  const map = new Map();
+  const duplicateKeys = new Set();
+  for (const row of attestation.entities) {
+    if (!row || typeof row !== 'object' || !row.entity) continue;
+    const subtype = row.subtype || 'all';
+    const key = entityKey(row.entity, subtype);
+    if (map.has(key)) {
+      duplicateKeys.add(key);
+      continue;
+    }
+    map.set(key, row);
+  }
+  return { map, duplicateKeys };
+}
+
+// `validateEntityQaAttestation({ attestation, report, reportDigest, mappedEntities })`.
+//
+// Returns `{ ok, reasons, qaStatus, entities, recheck }`.
+//   - `qaStatus`: 'missing' | 'stale' | 'failed' | 'attested'. Precedence: missing wins over
+//     stale, stale wins over failed -- a stale record's per-entity findings describe an old
+//     report, so they are never computed or listed.
+//   - `entities`: for `qaStatus: 'failed'`, one entry per affected `{entity, subtype, reasons}`.
+//     Empty for every other status.
+//   - `recheck`: 'full' for missing/stale, 'entities' for failed, `null` once attested.
+function validateEntityQaAttestation({ attestation, report, reportDigest, mappedEntities }) {
+  // 1. The attestation file itself: missing (or unreadable -- a malformed file is handed in by
+  // the caller's tolerant load as `null`, same as a missing one) or
+  // schema-invalid.
+  if (!attestation || typeof attestation !== 'object') {
+    return { ok: false, reasons: ['entity_qa_attestation_missing'], qaStatus: 'missing', entities: [], recheck: 'full' };
+  }
+  if (attestation.schemaVersion !== SCHEMA_VERSION || !Array.isArray(attestation.entities)) {
+    return { ok: false, reasons: ['entity_qa_attestation_schema_invalid'], qaStatus: 'missing', entities: [], recheck: 'full' };
+  }
+
+  // 2. There must be a usable completion report and a digest to compare against -- never
+  // "nothing to cover".
+  if (!report || typeof report !== 'object' || !reportDigest) {
+    return { ok: false, reasons: ['entity_qa_report_unavailable'], qaStatus: 'missing', entities: [], recheck: 'full' };
+  }
+
+  // 3. The independent coverage source must itself be usable. An empty list is exactly as
+  // unusable as a missing one -- it is never a legitimate "nothing was mapped".
+  const mapped = normalizeMappedEntities(mappedEntities);
+  if (!mapped || mapped.size === 0) {
+    return { ok: false, reasons: ['entity_qa_mapped_entities_unavailable'], qaStatus: 'missing', entities: [], recheck: 'full' };
+  }
+
+  // 4. Freshness: the attestation must name the digest of the report that is actually
+  // shipping. A later report rewrite reopens the whole review -- no per-entity findings are
+  // computed for a stale record, since they would describe a report that no longer exists.
+  if (attestation.completionReportDigest !== reportDigest) {
+    return { ok: false, reasons: ['entity_qa_attestation_stale'], qaStatus: 'stale', entities: [], recheck: 'full' };
+  }
+
+  // 5. Coverage and counts, judged two ways that together close two different gaps (see the comment above `reportRowsByBaseEntity` below for the second
+  // half). Neither judgment is against the attestation's or report's own entity list taken
+  // alone -- both comparands (`mapped` and, for full mode, the report's own
+  // `entityCompleteness`) are sources the attestation under test cannot have produced itself.
+  //
+  // `mapped` keys are always `<entity>/all`: `mapping-plan.json`'s schema (`readEntityMappings`
+  // in website-handoff.js) documents entities, not write-path subtypes -- subtyping is an
+  // execution/reporting concern that `rp-import-codegen/SKILL.md` requires only "whenever
+  // source records with the same entity map through materially different write paths or
+  // deferral rules, for example simple vs subscription Stores products". A full-mode run that
+  // legitimately splits a mapped entity's `entityCompleteness` rows by subtype therefore
+  // produces attested rows like `product/simple` and `product/subscription` that can never
+  // exact-key-match the plan's `product/all` -- comparing exact keys would flag such a row as
+  // BOTH missing (`product/all` absent) and unexpected (`product/simple` not in the plan)
+  // simultaneously, permanently blocking a correct migration. Coverage against `mapped`
+  // and uniqueness are therefore judged at the base-entity level: `mapped` only decides WHICH
+  // BASE ENTITIES are in scope at all, never which subtypes are required (the plan doesn't
+  // know). Which subtypes are required is then judged separately, against the report itself
+  // (below) -- closing the gap where an attestation that covers only some of an in-scope
+  // entity's real subtype rows used to read as fully covered. Only the per-row count
+  // comparison uses the full `entity/subtype` key, matching whatever subtype breakdown the
+  // attestation and report actually carry.
+  const isQuickMode = report.managementImportMode === 'quick';
+  const { map: attested, duplicateKeys } = indexAttestationEntities(attestation);
+  const fullModeReportRows = isQuickMode ? null : indexFullModeReportRows(report);
+
+  const findings = new Map(); // key -> { entity, subtype, reasons: [] }
+  const findingsFor = (key, entity, subtype) => {
+    if (!findings.has(key)) findings.set(key, { entity, subtype, reasons: [] });
+    return findings.get(key);
+  };
+
+  // A duplicate attested row for the same entity/subtype is a finding, not a silent
+  // last-one-wins resolution.
+  for (const key of duplicateKeys) {
+    const row = attested.get(key);
+    findingsFor(key, row.entity, row.subtype || 'all').reasons.push(`entity_qa_duplicate_attestation:${key}`);
+  }
+
+  const mappedBaseEntities = new Set([...mapped.values()].map(({ entity }) => entity));
+  const attestedByBaseEntity = new Map(); // entity -> [{ key, subtype }]
+  for (const [key, row] of attested) {
+    const subtype = row.subtype || 'all';
+    if (!attestedByBaseEntity.has(row.entity)) attestedByBaseEntity.set(row.entity, []);
+    attestedByBaseEntity.get(row.entity).push({ key, subtype });
+  }
+
+  // The base-entity grouping above fixes a case (a legitimate
+  // subtype split must not be flagged as both missing and unexpected against a plan that only
+  // knows base entities) but, left as-is, opened a new gap -- an attestation covering only
+  // SOME of a mapped entity's real subtype rows read as fully covered, because "missing" was
+  // judged as "at least one attested row for this base entity" rather than "every subtype row
+  // that actually exists". A QA agent could silently omit an inconvenient subtype from
+  // `--entities-file` and the gate would still pass. Close it by indexing which subtype rows
+  // the full-mode report itself actually carries per base entity -- the report, not the plan,
+  // is authoritative on which subtypes exist (the plan never carries subtypes at all).
+  const reportRowsByBaseEntity = new Map(); // entity -> [{ key, subtype }]
+  if (!isQuickMode) {
+    for (const [key, row] of fullModeReportRows) {
+      const subtype = row.subtype || 'all';
+      if (!reportRowsByBaseEntity.has(row.entity)) reportRowsByBaseEntity.set(row.entity, []);
+      reportRowsByBaseEntity.get(row.entity).push({ key, subtype });
+    }
+  }
+
+  // Missing: for each mapped (in-scope) base entity, every subtype row the report actually
+  // carries for it must have a matching attested row -- this is what closes the partial-subtype gap,
+  // using the report (never the plan) to decide which subtypes are required. When the report
+  // carries no rows at all for a mapped entity (quick mode, which has no subtype concept and no
+  // `entityCompleteness`, or a full-mode entity the report's completeness data never touched),
+  // fall back to requiring at least one attested row under `entity/all` -- the original
+  // behavior, still needed so a genuinely-never-attested entity is still caught.
+  for (const entity of mappedBaseEntities) {
+    const reportRows = !isQuickMode ? reportRowsByBaseEntity.get(entity) : null;
+    const attestedRows = attestedByBaseEntity.get(entity) || [];
+
+    if (reportRows && reportRows.length > 0) {
+      const attestedKeys = new Set(attestedRows.map((row) => row.key));
+      for (const { key, subtype } of reportRows) {
+        if (!attestedKeys.has(key)) {
+          findingsFor(key, entity, subtype).reasons.push(`entity_qa_missing_entity:${key}`);
+        }
+      }
+    } else if (attestedRows.length === 0) {
+      const key = entityKey(entity, 'all');
+      findingsFor(key, entity, 'all').reasons.push(`entity_qa_missing_entity:${key}`);
+    }
+  }
+  // Unexpected: an attested row whose base entity was never mapped at all -- a subtype split
+  // under a mapped entity is never flagged here, only an entity absent from the plan entirely.
+  for (const [entity, rows] of attestedByBaseEntity) {
+    if (mappedBaseEntities.has(entity)) continue;
+    for (const { key, subtype } of rows) {
+      findingsFor(key, entity, subtype).reasons.push(`entity_qa_unexpected_entity:${key}`);
+    }
+  }
+
+  // Only attested rows under a mapped base entity ever reach a count comparison -- a
+  // missing/unexpected row already has its own finding above. A plain (unsubtyped) entity
+  // compares its single `entity/all` row, same as before; a subtype-split entity compares each
+  // of its subtype rows independently against the matching report row.
+  for (const entity of mappedBaseEntities) {
+    const rows = attestedByBaseEntity.get(entity);
+    if (!rows || rows.length === 0) continue;
+
+    for (const { key, subtype } of rows) {
+      const attestedRow = attested.get(key);
+
+      if (isQuickMode) {
+        if (!quickModeEntityPresent(report.imported, entity)) {
+          findingsFor(key, entity, subtype).reasons.push(`entity_qa_report_entity_missing:${key}`);
+          continue;
+        }
+        const reportImported = quickModeCount(report.imported, entity);
+        const reportSkipped = quickModeCount(report.skipped, entity);
+        const attestedImported = numericFieldValue(attestedRow.imported);
+        const attestedSkipped = numericFieldValue(attestedRow.skipped);
+        if (attestedImported !== reportImported) {
+          findingsFor(key, entity, subtype).reasons.push(`entity_qa_count_mismatch:${key}:imported`);
+        }
+        if (attestedSkipped !== reportSkipped) {
+          findingsFor(key, entity, subtype).reasons.push(`entity_qa_count_mismatch:${key}:skipped`);
+        }
+        if (attestedSkipped > 0 && attestedRow.blockedReasonsReverified !== true) {
+          findingsFor(key, entity, subtype).reasons.push(`entity_qa_blocked_reasons_not_reverified:${key}`);
+        }
+      } else {
+        const reportRow = fullModeReportRows.get(key);
+        if (!reportRow) {
+          findingsFor(key, entity, subtype).reasons.push(`entity_qa_report_entity_missing:${key}`);
+          continue;
+        }
+        for (const field of FULL_MODE_FIELDS) {
+          const attestedValue = numericFieldValue(attestedRow[field]);
+          const reportValue = numericFieldValue(reportRow[field]);
+          if (attestedValue !== reportValue) {
+            findingsFor(key, entity, subtype).reasons.push(`entity_qa_count_mismatch:${key}:${field}`);
+          }
+        }
+        const blocked = numericFieldValue(attestedRow.deferred) > 0
+          || numericFieldValue(attestedRow.failed) > 0
+          || numericFieldValue(attestedRow.unresolved) > 0
+          || numericFieldValue(attestedRow.skippedOutOfScope) > 0;
+        if (blocked && attestedRow.blockedReasonsReverified !== true) {
+          findingsFor(key, entity, subtype).reasons.push(`entity_qa_blocked_reasons_not_reverified:${key}`);
+        }
+      }
+    }
+  }
+
+  if (findings.size > 0) {
+    const entities = [...findings.values()];
+    const reasons = entities.flatMap((entry) => entry.reasons);
+    return { ok: false, reasons, qaStatus: 'failed', entities, recheck: 'entities' };
+  }
+
+  return { ok: true, reasons: [], qaStatus: 'attested', entities: [], recheck: null };
+}
+
+module.exports = {
+  SCHEMA_VERSION,
+  ENTITY_QA_ATTESTATION_FILE,
+  FULL_MODE_FIELDS,
+  QUICK_MODE_FIELDS,
+  normalizeMappedEntities,
+  validateEntityQaAttestation,
+};

package/skills/wix-replatform/lib/entity-verification.js

@@ -0,0 +1,18 @@
+'use strict';
+const ZERO = '00000000-0000-0000-0000-000000000000';
+const opaqueId = id => typeof id === 'string' && id.length > 0 && id.trim() === id && id !== ZERO && !/^dry[-_]run/i.test(id);
+const contactId = id => opaqueId(id) && /^[a-f\d]{8}(?:-[a-f\d]{4}){3}-[a-f\d]{12}$/i.test(id);
+// The accepted mapping declares this policy independently of source naming.
+// Legacy inspected entity names remain compatible, but unknown names never opt out.
+function verificationKind({ verificationKind, entity, targetEntityType } = {}) {
+  if (verificationKind !== undefined) {
+    if (!['contact', 'product', 'none'].includes(verificationKind)) throw new Error('verificationKind must be contact, product, or none');
+    return verificationKind;
+  }
+  for (const name of [entity, targetEntityType]) {
+    if (/^(contacts?|customers?|crm[./_-]contacts?)$/i.test(name || '')) return 'contact';
+    if (/^(products?|stores[./_-]products?)$/i.test(name || '')) return 'product';
+  }
+  return 'required';
+}
+module.exports = { opaqueId, contactId, verificationKind };