@wix/agent-skills 1.33.0 → 1.34.0

package/skills/wix-replatform/lib/source-coverage.js

@@ -0,0 +1,1130 @@
+'use strict';
+
+// Source coverage accountability.
+//
+// A capability a source adapter advertised or attempted but did not capture (a 401/403 entity, a
+// data route skipped by rule, a route that failed, a quick-mode exclusion) never becomes a
+// `source-schema.json` entity, so before this module nothing forced it into the mapping-gaps
+// ledger or the completion report. It could disappear silently.
+//
+// This module owns the one schema for that record and the one join that decides what each row
+// means for the run's outcome:
+//
+//   adapter -> data/<source>-discovery/source-coverage.json   (rows; written by the adapter)
+//   rp-discovery promote -> discovery/source-coverage.json    (+ `sourceCoverageContract` stamp)
+//   rp-mapper -> mapping/review/mapping-gaps.json rows carrying `coverageId`, or a
+//                `sourceCoverage:<coverageId>` decision in orchestration/decisions.json
+//   reconcile / summarize -> every row has exactly one valid disposition, or the run refuses
+//   writeCompletionReport -> sourceCoverage[], status floor, headline, operatorActions
+//
+// Everything here is deterministic set/lookup work over adapter declarations and coverage rows.
+// No model calls, no network, no per-record passes.
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+
+const SOURCE_COVERAGE_SCHEMA_VERSION = 1;
+const SOURCE_COVERAGE_CONTRACT = 1;
+
+// Every bundled adapter must emit a coverage file. An adapter outside this set cannot promote
+// discovery until it is added; there is no unstamped path for it.
+const COVERAGE_EMITTERS = Object.freeze(['wordpress', 'csv', 'shopify', 'quick-woocommerce', 'quick-shopify']);
+const QUICK_ADAPTERS = Object.freeze(['quick-woocommerce', 'quick-shopify']);
+
+// Where each full adapter writes its raw capture; promotion reads the adapter file from here.
+const ADAPTER_RAW_DIRS = Object.freeze({
+  wordpress: 'data/wp-discovery',
+  csv: 'data/csv-discovery',
+  shopify: 'data/shopify-discovery',
+});
+
+const SOURCE_COVERAGE_FILE = 'discovery/source-coverage.json';
+const ADAPTER_COVERAGE_FILE_NAME = 'source-coverage.json';
+const SOURCE_SCHEMA_FILE = 'source-schema.json';
+const QUICK_PLAN_FILE = 'quick-mode/plan.json';
+const MAPPING_GAPS_FILE = 'mapping/review/mapping-gaps.json';
+const DECISIONS_FILE = 'orchestration/decisions.json';
+const APPROVALS_FILE = 'orchestration/approvals.json';
+
+const COVERAGE_REASONS = Object.freeze([
+  'auth-gated',
+  'route-unsupported',
+  'route-skipped-by-rule',
+  'capture-failed',
+  'adapter-excluded',
+  'declared-not-observed',
+]);
+const RECOVERABILITY = Object.freeze(['import-operator', 'requires-development', 'not-recoverable']);
+const GATES = Object.freeze(['exclusion', 'loss-accepted']);
+const DECISION_VALUES = Object.freeze(['provided', 'declined']);
+const DECISION_PREFIX = 'sourceCoverage:';
+// Rows whose open state owes the Cutover Operator an urgent action: the source still holds the
+// only copy and nobody decided to leave it behind.
+const URGENT_REASONS = new Set(['auth-gated', 'capture-failed', 'declared-not-observed']);
+
+// Status floors reuse the completion report's existing vocabulary and rank (completion-report.js
+// COMPLETION_STATUS). Duplicated as strings, not imported, so this module stays a leaf.
+const STATUS_FLOOR = Object.freeze({
+  recovered: null,
+  'gated-exclusion': null,
+  'ungated-exclusion': 'complete_with_warnings',
+  'accepted-loss': 'incomplete_with_failures',
+  unresolved: 'incomplete_with_mismatches',
+  'pre-contract': 'complete_with_warnings',
+});
+const STATUS_ORDER = [
+  'aborted',
+  'incomplete_with_mismatches',
+  'incomplete_with_failures',
+  'complete_with_deferred_records',
+  'complete_with_recovered_records',
+  'complete_with_warnings',
+  'complete',
+];
+
+const PRE_CONTRACT_REASON = 'pre-contract-discovery';
+const PRE_CONTRACT_HEADLINE = 'source coverage was not recorded for this run';
+
+class SourceCoverageError extends Error {
+  constructor(message, failures = []) {
+    super(message);
+    this.name = 'SourceCoverageError';
+    this.code = 'source_coverage_invalid';
+    this.failures = failures;
+  }
+}
+
+function worse(left, right) {
+  if (!right) return left;
+  if (!left) return right;
+  return STATUS_ORDER.indexOf(left) <= STATUS_ORDER.indexOf(right) ? left : right;
+}
+
+function nonEmptyString(value) {
+  return typeof value === 'string' && value.trim() !== '';
+}
+
+function requireString(value, label) {
+  if (!nonEmptyString(value)) throw new SourceCoverageError(`${label} must be a non-empty string`);
+  return value;
+}
+
+// ---------------------------------------------------------------------------------------------
+// Rows and the file envelope
+// ---------------------------------------------------------------------------------------------
+
+function coverageIdFor(platform, sourceEntity) {
+  return `${platform}:${sourceEntity}`;
+}
+
+function normalizeEvidence(value, label) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new SourceCoverageError(`${label}.evidence must be an object { artifact, pointer }`);
+  }
+  return {
+    artifact: requireString(value.artifact, `${label}.evidence.artifact`),
+    pointer: value.pointer === undefined || value.pointer === null ? null : String(value.pointer),
+  };
+}
+
+function normalizeCoverageRow(row, index = 0, { platform = null } = {}) {
+  const label = `rows[${index}]`;
+  if (!row || typeof row !== 'object' || Array.isArray(row)) throw new SourceCoverageError(`${label} must be an object`);
+  const rowPlatform = requireString(row.platform, `${label}.platform`);
+  if (platform && rowPlatform !== platform) {
+    throw new SourceCoverageError(`${label}.platform ${rowPlatform} does not match the file platform ${platform}`);
+  }
+  const sourceEntity = requireString(row.sourceEntity, `${label}.sourceEntity`);
+  const coverageId = requireString(row.coverageId, `${label}.coverageId`);
+  if (coverageId !== coverageIdFor(rowPlatform, sourceEntity)) {
+    throw new SourceCoverageError(`${label}.coverageId must be ${coverageIdFor(rowPlatform, sourceEntity)} (got ${coverageId})`);
+  }
+  const reason = requireString(row.reason, `${label}.reason`);
+  if (!COVERAGE_REASONS.includes(reason)) {
+    throw new SourceCoverageError(`${label}.reason must be one of ${COVERAGE_REASONS.join(', ')}`);
+  }
+  let capability = null;
+  let capabilityUnregistered = false;
+  if (row.capability === null || row.capability === undefined) {
+    if (row.capabilityUnregistered !== true) {
+      throw new SourceCoverageError(`${label}: a null capability requires capabilityUnregistered: true`);
+    }
+    capabilityUnregistered = true;
+  } else {
+    capability = requireString(row.capability, `${label}.capability`);
+    capabilityUnregistered = row.capabilityUnregistered === true;
+  }
+  const routes = Array.isArray(row.routes) ? row.routes.map((route, i) => requireString(route, `${label}.routes[${i}]`)) : [];
+  const recoverability = requireString(row.recoverability, `${label}.recoverability`);
+  if (!RECOVERABILITY.includes(recoverability)) {
+    throw new SourceCoverageError(`${label}.recoverability must be one of ${RECOVERABILITY.join(', ')}`);
+  }
+  let recoveryAction = null;
+  if (recoverability === 'import-operator') {
+    recoveryAction = requireString(row.recoveryAction, `${label}.recoveryAction`);
+  }
+  const disposition = row.disposition === undefined || row.disposition === null ? null : row.disposition;
+  if (disposition !== null && disposition !== 'declared-exclusion') {
+    // Every other disposition lives downstream (a gap entry or a decision); only a quick adapter's
+    // declared exclusion is recorded on the row itself.
+    throw new SourceCoverageError(`${label}.disposition may only be null or "declared-exclusion" in the coverage file`);
+  }
+  return {
+    coverageId,
+    platform: rowPlatform,
+    capability,
+    ...(capabilityUnregistered ? { capabilityUnregistered: true } : {}),
+    sourceEntity,
+    routes,
+    reason,
+    evidence: normalizeEvidence(row.evidence, label),
+    recoverability,
+    ...(recoveryAction ? { recoveryAction } : {}),
+    ...(nonEmptyString(row.pluginCoverageRef) ? { pluginCoverageRef: row.pluginCoverageRef } : {}),
+    disposition,
+  };
+}
+
+function validateCoverageFile(file) {
+  if (!file || typeof file !== 'object' || Array.isArray(file)) {
+    throw new SourceCoverageError('source-coverage.json must be an object { schemaVersion, platform, adapter, rows }');
+  }
+  if (file.schemaVersion !== SOURCE_COVERAGE_SCHEMA_VERSION) {
+    throw new SourceCoverageError(`source-coverage.json schemaVersion must be ${SOURCE_COVERAGE_SCHEMA_VERSION}`);
+  }
+  const platform = requireString(file.platform, 'source-coverage.json platform');
+  const adapter = requireString(file.adapter, 'source-coverage.json adapter');
+  if (!COVERAGE_EMITTERS.includes(adapter)) {
+    throw new SourceCoverageError(`source-coverage.json adapter ${adapter} is not a known coverage emitter (${COVERAGE_EMITTERS.join(', ')})`);
+  }
+  if (!Array.isArray(file.rows)) {
+    throw new SourceCoverageError('source-coverage.json rows must be an array; an adapter with nothing to report writes rows: []');
+  }
+  const seen = new Set();
+  const rows = file.rows.map((row, index) => {
+    const normalized = normalizeCoverageRow(row, index, { platform });
+    if (seen.has(normalized.coverageId)) {
+      throw new SourceCoverageError(`source-coverage.json lists coverageId ${normalized.coverageId} twice`);
+    }
+    seen.add(normalized.coverageId);
+    if (normalized.disposition === 'declared-exclusion' && !QUICK_ADAPTERS.includes(adapter)) {
+      throw new SourceCoverageError(`${normalized.coverageId}: declared-exclusion is only a quick adapter's disposition`);
+    }
+    return normalized;
+  });
+  return { schemaVersion: SOURCE_COVERAGE_SCHEMA_VERSION, platform, adapter, rows };
+}
+
+function buildCoverageFile({ platform, adapter, rows = [], generatedAt = null }) {
+  const file = validateCoverageFile({ schemaVersion: SOURCE_COVERAGE_SCHEMA_VERSION, platform, adapter, rows });
+  return generatedAt ? { ...file, generatedAt } : file;
+}
+
+// ---------------------------------------------------------------------------------------------
+// Adapter row builders
+// ---------------------------------------------------------------------------------------------
+
+const DATA_CATEGORIES = new Set(['backend_data', 'backend_metadata', 'public_commerce_data']);
+
+// The OPTIONS probe is a metadata request: inspectEntity records its failure and still issues the
+// data request. Only a failed data request (GET, a profile override, a bridge query) means the
+// entity was not captured, so an OPTIONS-only 401 on a readable, empty entity produces no row.
+function dataRequestErrors(entity) {
+  return (entity.requestErrors || []).filter((error) => error && error.request !== 'OPTIONS');
+}
+
+function isAuthError(error) {
+  return error.status === 401 || error.status === 403;
+}
+
+function sampledCount(entity) {
+  if (Array.isArray(entity.sampleRecords) && entity.sampleRecords.length) return entity.sampleRecords.length;
+  return Number.isInteger(entity.sampleRecordCount) ? entity.sampleRecordCount : 0;
+}
+
+// WordPress / WooCommerce. Inputs are the wp-discovery context the adapter already built:
+// `entities` (inspected routes) and `classifications` (every candidate route's scope decision).
+// A frontend/theme/admin/transient skip is route-scope evidence only and produces no row; a
+// duplicate route is not a capability at all.
+function buildWordPressCoverageRows({ entities = [], classifications = [], rawDir = 'data/wp-discovery', platform = 'wordpress' } = {}) {
+  const rows = [];
+  const seen = new Set();
+  const push = (row) => {
+    if (seen.has(row.coverageId)) return;
+    seen.add(row.coverageId);
+    rows.push(row);
+  };
+  for (const entity of entities) {
+    if (!entity || !nonEmptyString(entity.entityName)) continue;
+    if (sampledCount(entity) > 0) continue;
+    const errors = dataRequestErrors(entity);
+    if (!errors.length) continue;
+    const authGated = errors.some(isAuthError);
+    const status = errors.map((error) => error.status).filter((value) => value !== undefined).join(',');
+    push({
+      coverageId: coverageIdFor(platform, entity.entityName),
+      platform,
+      capability: null,
+      capabilityUnregistered: true,
+      sourceEntity: entity.entityName,
+      routes: [entity.routePath].filter(nonEmptyString),
+      reason: authGated ? 'auth-gated' : 'capture-failed',
+      evidence: { artifact: `${rawDir}/${entity.fileName || 'README.md'}`, pointer: `requestErrors (status ${status || 'unknown'})` },
+      recoverability: 'import-operator',
+      recoveryAction: authGated
+        ? `Supply credentials that can read ${entity.routePath} and re-run WordPress discovery for it.`
+        : `Fix source access for ${entity.routePath} and re-run WordPress discovery for it.`,
+      disposition: null,
+    });
+  }
+  const unsupportedByNamespace = new Map();
+  for (const classification of classifications) {
+    if (!classification || classification.effectiveAction !== 'skip' || classification.includedByOverride) continue;
+    if (DATA_CATEGORIES.has(classification.category)) {
+      const sourceEntity = classification.routePath.replace(/^\/+/, '');
+      push({
+        coverageId: coverageIdFor(platform, sourceEntity),
+        platform,
+        capability: null,
+        capabilityUnregistered: true,
+        sourceEntity,
+        routes: [classification.routePath],
+        reason: 'route-skipped-by-rule',
+        evidence: { artifact: `${rawDir}/skipped-routes.json`, pointer: `routes[routePath=${classification.routePath}]` },
+        recoverability: 'import-operator',
+        recoveryAction: `Re-run WordPress discovery with an audited --include-route override for ${classification.routePath} if this data is needed.`,
+        disposition: null,
+      });
+    } else if (classification.category === 'excluded_credential_bearing') {
+      // A source-data route the adapter deliberately never reads because its payload carries live
+      // secrets (WooCommerce payment-gateway settings). Not an evidence-only skip: it stays
+      // accountable. Not recoverable from the source by design -- the secrets are never read.
+      const sourceEntity = classification.routePath.replace(/^\/+/, '');
+      push({
+        coverageId: coverageIdFor(platform, sourceEntity),
+        platform,
+        capability: null,
+        capabilityUnregistered: true,
+        sourceEntity,
+        routes: [classification.routePath],
+        reason: 'route-skipped-by-rule',
+        evidence: { artifact: `${rawDir}/skipped-routes.json`, pointer: `routes[routePath=${classification.routePath}, category=excluded_credential_bearing]` },
+        recoverability: 'not-recoverable',
+        disposition: null,
+      });
+    } else if (classification.category === 'excluded_unsupported' && !classification.duplicateOf) {
+      // A route the adapter does not support, grouped per namespace so a plugin-heavy site gets
+      // one row per unsupported surface rather than one per route.
+      const namespace = nonEmptyString(classification.namespace) ? classification.namespace : 'unknown-namespace';
+      if (!unsupportedByNamespace.has(namespace)) unsupportedByNamespace.set(namespace, []);
+      unsupportedByNamespace.get(namespace).push(classification.routePath);
+    }
+  }
+  for (const [namespace, routes] of unsupportedByNamespace) {
+    push({
+      coverageId: coverageIdFor(platform, namespace),
+      platform,
+      capability: null,
+      capabilityUnregistered: true,
+      sourceEntity: namespace,
+      routes: [...routes].sort(),
+      reason: 'route-unsupported',
+      evidence: { artifact: `${rawDir}/skipped-routes.json`, pointer: `routes[namespace=${namespace}, category=excluded_unsupported]` },
+      recoverability: 'requires-development',
+      disposition: null,
+    });
+  }
+  return rows;
+}
+
+// CSV. An unknown file role and a halted layout are both things the adapter was handed and could
+// not turn into entities; each gets a row so the decision the halt asks for cannot be skipped.
+function buildCsvCoverageRows({ sourceFiles = [], streams = [], csvInputRoot = null, rawDir = 'data/csv-discovery', platform = 'csv' } = {}) {
+  const rows = [];
+  const seen = new Set();
+  const rel = (file) => (csvInputRoot ? path.relative(csvInputRoot, file) || path.basename(file) : path.basename(file));
+  for (const entry of sourceFiles) {
+    if (!entry || entry.role !== 'unknown') continue;
+    const sourceEntity = rel(entry.file);
+    const coverageId = coverageIdFor(platform, sourceEntity);
+    if (seen.has(coverageId)) continue;
+    seen.add(coverageId);
+    rows.push({
+      coverageId,
+      platform,
+      capability: null,
+      capabilityUnregistered: true,
+      sourceEntity,
+      routes: [sourceEntity],
+      reason: 'route-unsupported',
+      evidence: { artifact: `${rawDir}/fileset.json`, pointer: `sourceFiles[file=${sourceEntity}].role=unknown` },
+      recoverability: 'import-operator',
+      recoveryAction: `Identify what ${sourceEntity} holds and re-run CSV discovery with --role ${sourceEntity}:<role>.`,
+      disposition: null,
+    });
+  }
+  for (const stream of streams) {
+    if (!stream || !stream.layout || stream.layout.halt !== true) continue;
+    const sourceEntity = rel(stream.primary);
+    const coverageId = coverageIdFor(platform, sourceEntity);
+    if (seen.has(coverageId)) continue;
+    seen.add(coverageId);
+    rows.push({
+      coverageId,
+      platform,
+      capability: null,
+      capabilityUnregistered: true,
+      sourceEntity,
+      routes: [sourceEntity],
+      reason: 'capture-failed',
+      evidence: { artifact: `${rawDir}/fileset.json`, pointer: `streams[primary=${sourceEntity}].layout.halt` },
+      recoverability: 'import-operator',
+      recoveryAction: `Answer the layout question for ${sourceEntity} and re-run CSV discovery.`,
+      disposition: null,
+    });
+  }
+  return rows;
+}
+
+// Shopify (private data, read through the Shopify CLI). Inputs are the discovery capture's failed
+// reads -- `{ entity, artifact, errors[] }` per entity whose count or sample read errored -- plus
+// the rows other discovery steps already built. A failed read is a `capture-failed` row, never an
+// empty entity. `capability` is the registry string where one exists, otherwise null.
+const SHOPIFY_CAPABILITIES = Object.freeze({
+  products: 'commerce.catalog-product',
+  orders: 'commerce.orders',
+  customers: 'crm.contact',
+  'gift-cards': 'commerce.gift-cards',
+  articles: 'content.blog-post',
+  files: 'media.file',
+  'inventory-items': 'commerce.inventory',
+  'delivery-profiles': 'commerce.delivery-profiles',
+});
+
+function shopifyCapability(sourceEntity) {
+  const capability = SHOPIFY_CAPABILITIES[sourceEntity];
+  return capability ? { capability } : { capability: null, capabilityUnregistered: true };
+}
+
+function buildShopifyCoverageRows({ captureFailures = [], stepRows = [], rawDir = 'data/shopify-discovery', platform = 'shopify' } = {}) {
+  const rows = [];
+  const seen = new Set();
+  const push = (row) => {
+    if (seen.has(row.coverageId)) return;
+    seen.add(row.coverageId);
+    rows.push(row);
+  };
+  for (const failed of captureFailures) {
+    if (!failed || !nonEmptyString(failed.entity)) continue;
+    const codes = (failed.errors || []).map((error) => error && (error.code || error.class)).filter(nonEmptyString);
+    push({
+      coverageId: coverageIdFor(platform, failed.entity),
+      platform,
+      ...shopifyCapability(failed.entity),
+      sourceEntity: failed.entity,
+      routes: (failed.reads || []).filter(nonEmptyString),
+      reason: 'capture-failed',
+      evidence: { artifact: nonEmptyString(failed.artifact) ? failed.artifact : `${rawDir}/README.md`, pointer: `errors (${[...new Set(codes)].join(',') || 'unknown'})` },
+      recoverability: 'import-operator',
+      recoveryAction: `Fix the Shopify read of ${failed.entity} and re-run Shopify discovery with --reread ${failed.entity}.`,
+      disposition: null,
+    });
+  }
+  for (const row of stepRows) push(row);
+  return rows;
+}
+
+// Quick mode. Every `excluded[]` entry is a declared exclusion under the existing quick-mode
+// scope policy; the row keeps the source name and carries the committed capability translation.
+function buildQuickCoverageRows(contract, { rawText = null } = {}) {
+  const errors = validateQuickExcludedCapabilities(contract, { rawText });
+  if (errors.length) throw new SourceCoverageError(`quick-mode.json excludedCapabilities is invalid: ${errors.join('; ')}`, errors.map((message) => ({ code: 'invalid_quick_contract', message })));
+  return contract.excluded.map((sourceEntity) => ({
+    coverageId: coverageIdFor(contract.platform, sourceEntity),
+    platform: contract.platform,
+    capability: contract.excludedCapabilities[sourceEntity],
+    // Until the capability registry exists, a source-scope.* string is not registered anywhere.
+    ...(contract.excludedCapabilities[sourceEntity].startsWith('source-scope.') ? { capabilityUnregistered: true } : {}),
+    sourceEntity,
+    routes: [],
+    reason: 'adapter-excluded',
+    evidence: { artifact: `resources/rp-${contract.id}/quick-mode.json`, pointer: `excluded[${contract.excluded.indexOf(sourceEntity)}]` },
+    recoverability: 'not-recoverable',
+    disposition: 'declared-exclusion',
+  }));
+}
+
+// The committed quick-mode contract for a quick adapter id; what a declared exclusion is checked
+// against. Read from the bundle, never from the project, so a stale or hand-edited coverage file
+// or plan cannot vouch for itself.
+function bundledQuickContract(adapter) {
+  if (!QUICK_ADAPTERS.includes(adapter)) return null;
+  // eslint-disable-next-line global-require, import/no-dynamic-require
+  return require(path.join(__dirname, '..', 'resources', `rp-${adapter}`, 'quick-mode.json'));
+}
+
+let cachedCapabilityKeys = null;
+function bundledCapabilityKeys() {
+  if (!cachedCapabilityKeys) {
+    // eslint-disable-next-line global-require, import/no-dynamic-require
+    const index = require(path.join(__dirname, '..', 'resources', 'rp-target-wix', 'domains', 'index.json'));
+    cachedCapabilityKeys = new Set(Object.keys(index.capabilityIndex || {}));
+  }
+  return cachedCapabilityKeys;
+}
+
+// JSON.parse keeps the last of two equal keys, so a duplicate key in the committed file would be
+// silently resolved by position. Scan the raw text of the (flat, string-valued) object instead.
+function duplicateExcludedCapabilityKeys(text) {
+  const start = text.indexOf('"excludedCapabilities"');
+  if (start === -1) return [];
+  const open = text.indexOf('{', start);
+  const close = text.indexOf('}', open);
+  if (open === -1 || close === -1) return [];
+  const seen = new Set();
+  const duplicates = new Set();
+  for (const match of text.slice(open + 1, close).matchAll(/"((?:[^"\\]|\\.)*)"\s*:/g)) {
+    if (seen.has(match[1])) duplicates.add(match[1]);
+    seen.add(match[1]);
+  }
+  return [...duplicates];
+}
+
+// The committed translation from quick-mode source-scope names to capability strings. No
+// translation is inferred: exactly one key per excluded[] entry, each value an existing target
+// capability or `source-scope.<its own key>`.
+function validateQuickExcludedCapabilities(contract, { capabilityKeys = bundledCapabilityKeys(), rawText = null } = {}) {
+  const errors = rawText ? duplicateExcludedCapabilityKeys(rawText).map((key) => `excludedCapabilities lists key ${key} more than once`) : [];
+  if (!contract || typeof contract !== 'object') return ['quick-mode contract must be an object'];
+  const excluded = Array.isArray(contract.excluded) ? contract.excluded : null;
+  if (!excluded) return ['excluded must be an array'];
+  const map = contract.excludedCapabilities;
+  if (!map || typeof map !== 'object' || Array.isArray(map)) return ['excludedCapabilities must be an object with one key per excluded[] entry'];
+  const seenExcluded = new Set();
+  for (const name of excluded) {
+    if (seenExcluded.has(name)) errors.push(`excluded[] lists ${name} twice`);
+    seenExcluded.add(name);
+    if (!Object.prototype.hasOwnProperty.call(map, name)) errors.push(`excludedCapabilities is missing ${name}`);
+  }
+  for (const [key, value] of Object.entries(map)) {
+    if (!seenExcluded.has(key)) {
+      errors.push(`excludedCapabilities has extra key ${key} that is not in excluded[]`);
+      continue;
+    }
+    if (typeof value !== 'string' || !value) {
+      errors.push(`excludedCapabilities.${key} must be a capability string`);
+      continue;
+    }
+    if (value.startsWith('source-scope.')) {
+      if (value !== `source-scope.${key}`) errors.push(`excludedCapabilities.${key}: a source-scope value must be source-scope.${key} (got ${value})`);
+    } else if (!capabilityKeys.has(value)) {
+      errors.push(`excludedCapabilities.${key}: ${value} is neither a target capability nor source-scope.${key}`);
+    }
+  }
+  return errors;
+}
+
+// ---------------------------------------------------------------------------------------------
+// The join: exactly one valid disposition per row
+// ---------------------------------------------------------------------------------------------
+
+function readGapList(gaps) {
+  if (Array.isArray(gaps)) return gaps;
+  if (gaps && Array.isArray(gaps.gaps)) return gaps.gaps;
+  return [];
+}
+
+function schemaEntityNames(sourceSchema) {
+  const entities = sourceSchema && sourceSchema.entities;
+  if (Array.isArray(entities)) {
+    return new Set(entities.map((entity) => entity && (entity.name || entity.entityName || entity.sourceEntity)).filter(nonEmptyString));
+  }
+  if (entities && typeof entities === 'object') return new Set(Object.keys(entities));
+  return new Set();
+}
+
+function registerEntry(registers, register, capability) {
+  const list = registers && registers[register];
+  if (!Array.isArray(list)) return null;
+  return list.find((entry) => entry && entry.capability === capability && nonEmptyString(entry.decidedBy)) || null;
+}
+
+// Does the cited gate exist? This only validates; it never creates one.
+function citedGateExists(gate, evidence, lazy) {
+  if (!evidence || typeof evidence !== 'object') return false;
+  if (nonEmptyString(evidence.register)) {
+    if (gate === 'exclusion' && evidence.register !== 'no-migration-needed') return false;
+    if (!['no-migration-needed', 'requires-development'].includes(evidence.register)) return false;
+    return Boolean(registerEntry(lazy.registers(), evidence.register, evidence.capability));
+  }
+  if (gate === 'loss-accepted' && evidence.approval === 'mapping') {
+    const approvals = lazy.approvals();
+    const mapping = approvals && approvals.mapping;
+    return Boolean(mapping && mapping.status === 'approved');
+  }
+  return false;
+}
+
+function failure(code, coverageId, message, sources = []) {
+  return { code, coverageId, message, sources };
+}
+
+// Pure over its inputs. `sourceSchema`, `registers` and `approvals` may be values or thunks; they
+// are only consulted for a `provided` decision or a cited gate, so the common case reads exactly
+// the coverage, gaps and decisions files.
+function reconcileSourceCoverage({ coverage, gaps, decisions, sourceSchema = null, registers = null, approvals = null, quickContract = null } = {}) {
+  const file = validateCoverageFile(coverage);
+  const once = (value) => {
+    let loaded = false;
+    let result;
+    return () => {
+      if (!loaded) { result = typeof value === 'function' ? value() : value; loaded = true; }
+      return result;
+    };
+  };
+  const lazy = {
+    sourceSchema: once(sourceSchema),
+    registers: once(registers),
+    approvals: once(approvals),
+    quickContract: once(quickContract || (() => bundledQuickContract(file.adapter))),
+  };
+  const failures = [];
+  const rowsById = new Map(file.rows.map((row) => [row.coverageId, row]));
+  const isQuick = QUICK_ADAPTERS.includes(file.adapter);
+
+  const gapsById = new Map();
+  readGapList(gaps).forEach((gap, index) => {
+    if (!gap || !nonEmptyString(gap.coverageId)) return;
+    if (!rowsById.has(gap.coverageId)) {
+      failures.push(failure('unknown_coverage_id', gap.coverageId, `mapping-gaps.json entry ${index} references unknown coverageId ${gap.coverageId}`, [`gap[${index}]`]));
+      return;
+    }
+    if (!gapsById.has(gap.coverageId)) gapsById.set(gap.coverageId, []);
+    gapsById.get(gap.coverageId).push({ gap, index });
+  });
+
+  const decisionsById = new Map();
+  for (const [key, entry] of Object.entries(decisions || {})) {
+    if (!key.startsWith(DECISION_PREFIX)) continue;
+    const coverageId = key.slice(DECISION_PREFIX.length);
+    if (!rowsById.has(coverageId)) {
+      failures.push(failure('unknown_coverage_id', coverageId, `decision ${key} references unknown coverageId ${coverageId}`, [`decision:${key}`]));
+      continue;
+    }
+    const value = entry && typeof entry === 'object' ? entry.value : entry;
+    if (!DECISION_VALUES.includes(value)) {
+      failures.push(failure('invalid_decision', coverageId, `decision ${key} must be provided or declined (got ${JSON.stringify(value)})`, [`decision:${key}`]));
+      continue;
+    }
+    decisionsById.set(coverageId, { key, value });
+  }
+
+  const resolved = [];
+  for (const row of file.rows) {
+    const rowGaps = gapsById.get(row.coverageId) || [];
+    const decision = decisionsById.get(row.coverageId) || null;
+    const declared = row.disposition === 'declared-exclusion';
+    const sources = [
+      ...rowGaps.map(({ index }) => `gap[${index}]`),
+      ...(decision ? [`decision:${decision.key}`] : []),
+      ...(declared ? ['declared-exclusion'] : []),
+    ];
+    if (sources.length === 0) {
+      failures.push(failure('missing_disposition', row.coverageId, `${row.coverageId} has no disposition: record a mapping-gaps.json entry with this coverageId or a ${DECISION_PREFIX}${row.coverageId} decision`));
+      continue;
+    }
+    if (sources.length > 1) {
+      failures.push(failure('disposition_conflict', row.coverageId, `${row.coverageId} has ${sources.length} active dispositions (${sources.join(', ')}); exactly one is allowed`, sources));
+      continue;
+    }
+    if (isQuick && row.reason !== 'adapter-excluded') {
+      failures.push(failure('quick_reason_unsupported', row.coverageId, `${row.coverageId}: a quick adapter may only report adapter-excluded rows (got ${row.reason})`, sources));
+      continue;
+    }
+
+    if (declared) {
+      // Declared exclusion: only on an adapter-excluded row from a quick adapter, for a name that
+      // adapter's committed contract lists in excluded[], carrying that contract's translation.
+      // A stale or forged row has no status floor to fall back on, so it is refused here.
+      if (row.reason !== 'adapter-excluded' || !isQuick) {
+        failures.push(failure('gate_reason_mismatch', row.coverageId, `${row.coverageId}: declared-exclusion is valid only on a quick adapter's adapter-excluded row`, sources));
+        continue;
+      }
+      const contract = lazy.quickContract();
+      const excluded = contract && Array.isArray(contract.excluded) ? contract.excluded : [];
+      if (!excluded.includes(row.sourceEntity)) {
+        failures.push(failure('gate_reason_mismatch', row.coverageId, `${row.coverageId}: ${row.sourceEntity} is not in the ${file.adapter} contract's excluded[]; re-run quick-mode plan`, sources));
+        continue;
+      }
+      const committed = contract.excludedCapabilities && contract.excludedCapabilities[row.sourceEntity];
+      if (row.capability !== committed) {
+        failures.push(failure('gate_reason_mismatch', row.coverageId, `${row.coverageId}: capability ${row.capability} does not match the committed translation ${committed || 'none'}; re-run quick-mode plan`, sources));
+        continue;
+      }
+      resolved.push({ row, disposition: 'declared-exclusion', treatment: 'gated-exclusion', gate: null, gateEvidence: null, handling: null });
+      continue;
+    }
+
+    if (decision) {
+      if (decision.value === 'provided') {
+        const names = schemaEntityNames(lazy.sourceSchema());
+        if (!names.has(row.sourceEntity)) {
+          failures.push(failure('disposition_stale', row.coverageId, `${row.coverageId}: decision is "provided" but ${row.sourceEntity} is not an entity in source-schema.json; re-run discovery or record "declined"`, sources));
+          continue;
+        }
+        resolved.push({ row, disposition: 'recovered', treatment: 'recovered', gate: null, gateEvidence: null, handling: null });
+      } else {
+        resolved.push({
+          row,
+          disposition: 'declined',
+          treatment: row.reason === 'adapter-excluded' ? 'ungated-exclusion' : 'unresolved',
+          gate: null,
+          gateEvidence: null,
+          handling: null,
+        });
+      }
+      continue;
+    }
+
+    const { gap } = rowGaps[0];
+    const gate = gap.gate === undefined || gap.gate === null ? null : gap.gate;
+    const handling = nonEmptyString(gap.recommendedHandling) ? gap.recommendedHandling : (nonEmptyString(gap.handling) ? gap.handling : null);
+    if (gate === null) {
+      resolved.push({ row, disposition: 'gap', treatment: row.reason === 'adapter-excluded' ? 'ungated-exclusion' : 'unresolved', gate: null, gateEvidence: null, handling });
+      continue;
+    }
+    if (!GATES.includes(gate)) {
+      failures.push(failure('invalid_gate', row.coverageId, `${row.coverageId}: gate must be one of ${GATES.join(', ')} (got ${JSON.stringify(gate)})`, sources));
+      continue;
+    }
+    const evidence = gap.gateEvidence || null;
+    if (gate === 'exclusion') {
+      // A gated exclusion has no status floor, so it must be exactly what it claims: an
+      // adapter exclusion backed by a signed no-migration-needed entry for this capability.
+      const evidenceCapability = evidence && evidence.capability;
+      if (row.reason !== 'adapter-excluded' || !row.capability || evidenceCapability !== row.capability || (evidence && evidence.register !== 'no-migration-needed')) {
+        failures.push(failure('gate_reason_mismatch', row.coverageId, `${row.coverageId}: an exclusion gate is valid only on an adapter-excluded row whose no-migration-needed entry names its own capability (reason ${row.reason}, row capability ${row.capability}, cited ${evidenceCapability || 'none'})`, sources));
+        continue;
+      }
+    }
+    if (gate === 'loss-accepted' && evidence && nonEmptyString(evidence.register) && evidence.capability !== row.capability) {
+      failures.push(failure('gate_reason_mismatch', row.coverageId, `${row.coverageId}: the cited ${evidence.register} entry names ${evidence.capability}, not this row's capability ${row.capability}`, sources));
+      continue;
+    }
+    if (!citedGateExists(gate, evidence, lazy)) {
+      failures.push(failure('gate_missing', row.coverageId, `${row.coverageId}: the cited ${gate} gate does not exist; reconcile never creates one`, sources));
+      continue;
+    }
+    resolved.push({
+      row,
+      disposition: 'gap',
+      treatment: gate === 'exclusion' ? 'gated-exclusion' : 'accepted-loss',
+      gate,
+      gateEvidence: evidence,
+      handling,
+    });
+  }
+
+  return { ok: failures.length === 0, adapter: file.adapter, platform: file.platform, failures, resolved };
+}
+
+// ---------------------------------------------------------------------------------------------
+// Completion: status floor, headline, sourceCoverage[] and operator actions
+// ---------------------------------------------------------------------------------------------
+
+function labelOf(row) {
+  return row.capability || row.sourceEntity;
+}
+
+// What the Cutover Operator reads about a row it can only act on in Wix. Source recovery is
+// mentioned only for an `import-operator` row; a `not-recoverable` row (for example a
+// credential-bearing route whose secrets are never read) or a `requires-development` row must
+// never suggest that the source can still supply the data through an operator.
+function sourceRecoveryNote(recoverability) {
+  switch (recoverability) {
+    case 'import-operator':
+      return ' Recovering it from the source is Import Operator work before the source is retired.';
+    case 'requires-development':
+      return ' This migration cannot recover it from the source without new adapter development.';
+    default:
+      return ' This migration cannot recover it from the source.';
+  }
+}
+
+function cutoverActionFor(treatment, label, recoverability) {
+  switch (treatment) {
+    case 'gated-exclusion':
+      return `Excluded by the chosen scope: ${label} is not part of this migration. Set it up in Wix separately only if the business needs it.`;
+    case 'ungated-exclusion':
+      return `Excluded without a recorded review: confirm with the merchant whether ${label} needs to be set up in Wix.`;
+    case 'accepted-loss':
+      return `Accepted loss: ${label} was left behind by a recorded decision. Nothing to recreate unless that decision changes.`;
+    default:
+      return `Not migrated: recreate or confirm ${label} in Wix if the business still needs it.${sourceRecoveryNote(recoverability)}`;
+  }
+}
+
+function headlineFor(treatment, label, reasons) {
+  const reasonText = [...reasons].sort().join(', ');
+  switch (treatment) {
+    case 'ungated-exclusion':
+      return `${label}: excluded from the source without a recorded gate (${reasonText})`;
+    case 'accepted-loss':
+      return `${label}: not migrated from the source; loss accepted (${reasonText})`;
+    default:
+      return `${label}: not migrated from the source (${reasonText})`;
+  }
+}
+
+function preContractSummary() {
+  return {
+    sourceCoverageRecorded: false,
+    sourceCoverageReason: PRE_CONTRACT_REASON,
+    sourceCoverage: [],
+    operatorActions: [],
+    headline: [{ entity: 'source-coverage', subtype: 'source-coverage', message: PRE_CONTRACT_HEADLINE }],
+    status: STATUS_FLOOR['pre-contract'],
+  };
+}
+
+// The pure join. Throws on any reconcile failure, so a writer refuses instead of choosing a status.
+// `coverage: null` means a pre-contract project (no stamp); the caller decides that, never this.
+function summarizeSourceCoverage({ coverage, gaps, decisions, sourceSchema = null, registers = null, approvals = null, quickContract = null } = {}) {
+  if (coverage === null) return preContractSummary();
+  const result = reconcileSourceCoverage({ coverage, gaps, decisions, sourceSchema, registers, approvals, quickContract });
+  if (!result.ok) {
+    throw new SourceCoverageError(
+      `source coverage does not reconcile: ${result.failures.map((item) => `${item.code} ${item.coverageId || ''}`.trim()).join('; ')}`,
+      result.failures,
+    );
+  }
+
+  let status = null;
+  const sourceCoverage = [];
+  const grouped = new Map();
+  const gatedCapabilities = new Set();
+  for (const item of result.resolved) {
+    status = worse(status, STATUS_FLOOR[item.treatment]);
+    if (item.treatment === 'recovered') continue;
+    const label = labelOf(item.row);
+    sourceCoverage.push({
+      coverageId: item.row.coverageId,
+      platform: item.row.platform,
+      capability: item.row.capability,
+      sourceEntity: item.row.sourceEntity,
+      reason: item.row.reason,
+      recoverability: item.row.recoverability,
+      disposition: item.disposition,
+      treatment: item.treatment,
+      gate: item.gate,
+      gateEvidence: item.gateEvidence,
+      recommendedHandling: item.handling,
+      cutoverAction: cutoverActionFor(item.treatment, label, item.row.recoverability),
+    });
+    if (item.treatment === 'gated-exclusion') {
+      gatedCapabilities.add(label);
+      continue;
+    }
+    const key = `${item.treatment}\0${label}`;
+    if (!grouped.has(key)) grouped.set(key, { treatment: item.treatment, label, reasons: new Set(), urgent: false, sourceRecoverable: false });
+    const group = grouped.get(key);
+    group.reasons.add(item.row.reason);
+    if (item.row.recoverability === 'import-operator') group.sourceRecoverable = true;
+    if (item.treatment === 'unresolved' && URGENT_REASONS.has(item.row.reason)) group.urgent = true;
+  }
+
+  const headline = [];
+  const operatorActions = [];
+  for (const group of grouped.values()) {
+    headline.push({ entity: group.label, subtype: 'source-coverage', message: headlineFor(group.treatment, group.label, group.reasons) });
+    if (group.urgent) {
+      operatorActions.push({
+        code: 'source-capability-not-migrated',
+        severity: 'high',
+        action: `${group.label} was not migrated from the source (${[...group.reasons].sort().join(', ')}). Recreate or confirm it in Wix${group.sourceRecoverable ? '; recovering it from the source requires the Import Operator in the original migration environment' : ''}.`,
+        deadlineReason: 'the source is still the only copy of this data',
+        entity: group.label,
+        affectedCount: 0,
+      });
+    }
+  }
+  if (gatedCapabilities.size) {
+    headline.push({
+      entity: 'source-coverage',
+      subtype: 'source-coverage',
+      message: `${gatedCapabilities.size} source capabilit${gatedCapabilities.size === 1 ? 'y' : 'ies'} excluded by the chosen scope`,
+    });
+  }
+
+  return {
+    sourceCoverageRecorded: true,
+    sourceCoverageReason: null,
+    sourceCoverage,
+    operatorActions,
+    headline,
+    status,
+  };
+}
+
+// ---------------------------------------------------------------------------------------------
+// Project I/O: the stamp, the fail-closed loaders, and the decision writer
+// ---------------------------------------------------------------------------------------------
+
+async function readJsonFile(filePath) {
+  try {
+    return JSON.parse(await fs.readFile(filePath, 'utf8'));
+  } catch (error) {
+    if (error.code === 'ENOENT') return undefined;
+    throw new SourceCoverageError(`${filePath} could not be read as JSON: ${error.message}`);
+  }
+}
+
+function contractStampOf(document, label) {
+  if (!document || typeof document !== 'object' || document.sourceCoverageContract === undefined) return null;
+  if (document.sourceCoverageContract !== SOURCE_COVERAGE_CONTRACT) {
+    throw new SourceCoverageError(`${label} carries unknown sourceCoverageContract ${JSON.stringify(document.sourceCoverageContract)}`);
+  }
+  return SOURCE_COVERAGE_CONTRACT;
+}
+
+// Full mode reads the stamp only from the project-root source-schema.json; quick mode only from
+// quick-mode/plan.json. Never from anywhere else.
+async function readCoverageContract(projectDir, { mode = 'full', readJson = readJsonFile } = {}) {
+  const file = mode === 'quick' ? QUICK_PLAN_FILE : SOURCE_SCHEMA_FILE;
+  const document = await readJson(path.join(projectDir, file));
+  return { stamped: contractStampOf(document, file) === SOURCE_COVERAGE_CONTRACT, document: document || null, file };
+}
+
+async function loadRegisters() {
+  const dir = path.join(__dirname, '..', 'resources', 'rp-source-wordpress', 'plugins');
+  const read = async (name) => {
+    const document = await readJsonFile(path.join(dir, `${name}.json`));
+    return Array.isArray(document && document.capabilities) ? document.capabilities : [];
+  };
+  return { 'no-migration-needed': await read('no-migration-needed'), 'requires-development': await read('requires-development') };
+}
+
+// Loads the three named files (coverage, gaps, decisions), failing closed on a missing coverage
+// file. The source schema, registers and approvals are read only when a row actually needs them.
+async function loadCoverageInputs(projectDir, { readJson = readJsonFile } = {}) {
+  const coverage = await readJson(path.join(projectDir, SOURCE_COVERAGE_FILE));
+  if (coverage === undefined) {
+    throw new SourceCoverageError(`${SOURCE_COVERAGE_FILE} is missing; it is never optional for a current adapter`, [
+      { code: 'missing_coverage_file', coverageId: null, message: `${SOURCE_COVERAGE_FILE} is missing`, sources: [] },
+    ]);
+  }
+  const gaps = (await readJson(path.join(projectDir, MAPPING_GAPS_FILE))) || [];
+  const decisions = (await readJson(path.join(projectDir, DECISIONS_FILE))) || {};
+  return { coverage, gaps, decisions };
+}
+
+function needsLazyInputs(inputs) {
+  const gaps = readGapList(inputs.gaps);
+  const anyProvided = Object.entries(inputs.decisions || {}).some(([key, entry]) => key.startsWith(DECISION_PREFIX) && entry && entry.value === 'provided');
+  const anyRegister = gaps.some((gap) => gap && gap.coverageId && gap.gateEvidence && gap.gateEvidence.register);
+  const anyApproval = gaps.some((gap) => gap && gap.coverageId && gap.gateEvidence && gap.gateEvidence.approval);
+  return { anyProvided, anyRegister, anyApproval };
+}
+
+// Eagerly resolves the lazily-needed side inputs (async), but only those a row will consult.
+async function resolveSideInputs(projectDir, inputs, { readJson = readJsonFile, registers = null } = {}) {
+  const need = needsLazyInputs(inputs);
+  return {
+    sourceSchema: need.anyProvided ? (await readJson(path.join(projectDir, SOURCE_SCHEMA_FILE))) || null : null,
+    registers: need.anyRegister ? (registers || (await loadRegisters())) : null,
+    approvals: need.anyApproval ? (await readJson(path.join(projectDir, APPROVALS_FILE))) || null : null,
+  };
+}
+
+async function reconcileProject(projectDir, { readJson = readJsonFile, registers = null } = {}) {
+  const inputs = await loadCoverageInputs(projectDir, { readJson });
+  const side = await resolveSideInputs(projectDir, inputs, { readJson, registers });
+  return reconcileSourceCoverage({ ...inputs, ...side });
+}
+
+// The completion-time join for a project. `mode: 'quick'` reads the quick-mode plan stamp.
+// The pre-contract exception is bounded to an unstamped full-mode source-schema.json; a quick
+// plan written since Phase 1 always carries the stamp, so a missing or unstamped one refuses.
+async function summarizeProjectCoverage(projectDir, { mode = 'full', readJson = readJsonFile, registers = null } = {}) {
+  const contract = await readCoverageContract(projectDir, { mode, readJson });
+  if (!contract.stamped && mode === 'quick') {
+    const what = contract.document ? 'has no sourceCoverageContract stamp' : 'is missing';
+    throw new SourceCoverageError(`${QUICK_PLAN_FILE} ${what}; re-run quick-mode plan before import`, [
+      { code: 'quick_plan_unstamped', coverageId: null, message: `${QUICK_PLAN_FILE} ${what}`, sources: [] },
+    ]);
+  }
+  if (!contract.stamped) return summarizeSourceCoverage({ coverage: null });
+  const inputs = await loadCoverageInputs(projectDir, { readJson });
+  const side = await resolveSideInputs(projectDir, inputs, { readJson, registers });
+  return summarizeSourceCoverage({ ...inputs, ...side });
+}
+
+async function writeJsonAtomic(filePath, value) {
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  const temp = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  await fs.writeFile(temp, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+  await fs.rename(temp, filePath);
+}
+
+// Promotion: validate the adapter's file, copy it to discovery/, and stamp the canonical
+// project-root source-schema.json. Refuses for an unknown adapter, a missing adapter file or a
+// missing source schema -- there is no unstamped path for a current adapter.
+async function promoteSourceCoverage(projectDir, { adapter }) {
+  if (!COVERAGE_EMITTERS.includes(adapter) || QUICK_ADAPTERS.includes(adapter)) {
+    throw new SourceCoverageError(`adapter ${adapter} cannot promote discovery: full-discovery coverage emitters are ${Object.keys(ADAPTER_RAW_DIRS).join(', ')}`);
+  }
+  const adapterFile = path.join(projectDir, ADAPTER_RAW_DIRS[adapter], ADAPTER_COVERAGE_FILE_NAME);
+  const raw = await readJsonFile(adapterFile);
+  if (raw === undefined) {
+    throw new SourceCoverageError(`${path.relative(projectDir, adapterFile)} is missing; the ${adapter} adapter must write it (rows: [] when there is nothing to report) before discovery is promoted`, [
+      { code: 'missing_coverage_file', coverageId: null, message: 'adapter coverage file missing', sources: [] },
+    ]);
+  }
+  const file = validateCoverageFile(raw);
+  if (file.adapter !== adapter) throw new SourceCoverageError(`adapter coverage file names adapter ${file.adapter}, not ${adapter}`);
+  const schemaPath = path.join(projectDir, SOURCE_SCHEMA_FILE);
+  const schema = await readJsonFile(schemaPath);
+  if (!schema || typeof schema !== 'object') {
+    throw new SourceCoverageError(`${SOURCE_SCHEMA_FILE} must be synthesized before source coverage is promoted`);
+  }
+  await writeJsonAtomic(path.join(projectDir, SOURCE_COVERAGE_FILE), { ...file, ...(raw.generatedAt ? { generatedAt: raw.generatedAt } : {}) });
+  await writeJsonAtomic(schemaPath, { ...schema, sourceCoverageContract: SOURCE_COVERAGE_CONTRACT });
+  return { coveragePath: path.join(projectDir, SOURCE_COVERAGE_FILE), rows: file.rows.length };
+}
+
+// A coverage row first found after discovery (during the import) joins the adapter's raw file by
+// coverageId -- a row with the same id is replaced, otherwise appended -- and the file is
+// re-promoted, so the canonical record and the stamp come from the one promotion path. What the
+// run does next is the general path for every source; this writes no gap, decision or approval.
+async function upsertAdapterCoverageRows(projectDir, { adapter, rows, checkpoint = null }) {
+  if (!COVERAGE_EMITTERS.includes(adapter) || QUICK_ADAPTERS.includes(adapter)) {
+    throw new SourceCoverageError(`adapter ${adapter} has no adapter coverage file to update`);
+  }
+  if (!Array.isArray(rows) || rows.length === 0) throw new SourceCoverageError('upsertAdapterCoverageRows needs at least one row');
+  const adapterFile = path.join(projectDir, ADAPTER_RAW_DIRS[adapter], ADAPTER_COVERAGE_FILE_NAME);
+  const raw = await readJsonFile(adapterFile);
+  if (raw === undefined) {
+    throw new SourceCoverageError(`${path.relative(projectDir, adapterFile)} is missing; discovery must have written it before a row can be added`, [
+      { code: 'missing_coverage_file', coverageId: null, message: 'adapter coverage file missing', sources: [] },
+    ]);
+  }
+  const file = validateCoverageFile(raw);
+  if (file.adapter !== adapter) throw new SourceCoverageError(`adapter coverage file names adapter ${file.adapter}, not ${adapter}`);
+  const merged = [...file.rows];
+  let added = 0;
+  let replaced = 0;
+  for (const [index, candidate] of rows.entries()) {
+    const normalized = normalizeCoverageRow(candidate, index, { platform: file.platform });
+    const at = merged.findIndex((existing) => existing.coverageId === normalized.coverageId);
+    if (at === -1) { merged.push(normalized); added += 1; } else { merged[at] = normalized; replaced += 1; }
+  }
+  const next = validateCoverageFile({ ...file, rows: merged });
+  await writeJsonAtomic(adapterFile, { ...next, ...(raw.generatedAt ? { generatedAt: raw.generatedAt } : {}) });
+  // Optional checkpoints let recovery tests stop between the two durable writes.
+  if (typeof checkpoint === 'function') await checkpoint('after-row-upsert');
+  await promoteSourceCoverage(projectDir, { adapter });
+  if (typeof checkpoint === 'function') await checkpoint('after-re-promotion');
+  return { added, replaced, rows: next.rows.length };
+}
+
+// The rp-mapper decision writer. Recording a `sourceCoverage:` decision removes that row's gap
+// entries in the same write, so the normal recovery path never creates a disposition conflict.
+// Gaps are written first: an interruption between the two writes leaves a row with no
+// disposition (reconcile fails closed; re-running this fixes it), never a silent conflict.
+async function recordCoverageDecision(projectDir, { coverageId, value, rationale = null, source = 'user', timestamp = new Date().toISOString() }) {
+  requireString(coverageId, 'coverageId');
+  if (!DECISION_VALUES.includes(value)) throw new SourceCoverageError(`decision value must be one of ${DECISION_VALUES.join(', ')}`);
+  const inputs = await loadCoverageInputs(projectDir);
+  const file = validateCoverageFile(inputs.coverage);
+  if (!file.rows.some((row) => row.coverageId === coverageId)) {
+    throw new SourceCoverageError(`unknown coverageId ${coverageId}`);
+  }
+  const gapsPath = path.join(projectDir, MAPPING_GAPS_FILE);
+  const rawGaps = await readJsonFile(gapsPath);
+  let removed = 0;
+  if (rawGaps !== undefined) {
+    const keep = (gap) => {
+      if (gap && gap.coverageId === coverageId) { removed += 1; return false; }
+      return true;
+    };
+    const next = Array.isArray(rawGaps) ? rawGaps.filter(keep)
+      : rawGaps && Array.isArray(rawGaps.gaps) ? { ...rawGaps, gaps: rawGaps.gaps.filter(keep) } : rawGaps;
+    if (removed) await writeJsonAtomic(gapsPath, next);
+  }
+  const decisionsPath = path.join(projectDir, DECISIONS_FILE);
+  const decisions = (await readJsonFile(decisionsPath)) || {};
+  decisions[`${DECISION_PREFIX}${coverageId}`] = { value, decidedAt: timestamp, source, rationale };
+  await writeJsonAtomic(decisionsPath, decisions);
+  return { coverageId, value, removedGaps: removed };
+}
+
+// Quick-mode `plan`: write the declared-exclusion rows, run the same reconcile check, and return
+// the stamp the plan must carry. Throws (so the plan is not written) when either fails.
+async function writeQuickPlanCoverage(projectDir, contract, { rawText = null, generatedAt = new Date().toISOString() } = {}) {
+  const rows = buildQuickCoverageRows(contract, { rawText });
+  const file = buildCoverageFile({ platform: contract.platform, adapter: contract.id, rows });
+  const result = reconcileSourceCoverage({ coverage: file, gaps: [], decisions: {}, quickContract: contract });
+  if (!result.ok) {
+    throw new SourceCoverageError(`quick-mode source coverage does not reconcile: ${result.failures.map((item) => item.code).join(', ')}`, result.failures);
+  }
+  await writeJsonAtomic(path.join(projectDir, SOURCE_COVERAGE_FILE), { ...file, generatedAt });
+  return { sourceCoverageContract: SOURCE_COVERAGE_CONTRACT, rows: rows.length };
+}
+
+// Quick-mode `import`: the completion summary carries the same sourceCoverage[] field and
+// coverage status. Throws (so no summary is written) on a stamped plan with a missing or
+// unreconciled coverage file.
+async function quickSummaryCoverage(projectDir) {
+  const summary = await summarizeProjectCoverage(projectDir, { mode: 'quick' });
+  return {
+    sourceCoverageRecorded: summary.sourceCoverageRecorded,
+    ...(summary.sourceCoverageReason ? { sourceCoverageReason: summary.sourceCoverageReason } : {}),
+    sourceCoverageStatus: summary.status,
+    sourceCoverage: summary.sourceCoverage,
+    sourceCoverageHeadline: summary.headline,
+  };
+}
+
+module.exports = {
+  writeQuickPlanCoverage,
+  quickSummaryCoverage,
+  SOURCE_COVERAGE_SCHEMA_VERSION,
+  SOURCE_COVERAGE_CONTRACT,
+  COVERAGE_EMITTERS,
+  QUICK_ADAPTERS,
+  ADAPTER_RAW_DIRS,
+  SHOPIFY_CAPABILITIES,
+  SOURCE_COVERAGE_FILE,
+  ADAPTER_COVERAGE_FILE_NAME,
+  SOURCE_SCHEMA_FILE,
+  QUICK_PLAN_FILE,
+  MAPPING_GAPS_FILE,
+  DECISIONS_FILE,
+  COVERAGE_REASONS,
+  RECOVERABILITY,
+  DECISION_PREFIX,
+  PRE_CONTRACT_REASON,
+  PRE_CONTRACT_HEADLINE,
+  SourceCoverageError,
+  coverageIdFor,
+  normalizeCoverageRow,
+  validateCoverageFile,
+  buildCoverageFile,
+  buildWordPressCoverageRows,
+  buildCsvCoverageRows,
+  buildShopifyCoverageRows,
+  buildQuickCoverageRows,
+  validateQuickExcludedCapabilities,
+  duplicateExcludedCapabilityKeys,
+  reconcileSourceCoverage,
+  summarizeSourceCoverage,
+  readCoverageContract,
+  loadCoverageInputs,
+  loadRegisters,
+  reconcileProject,
+  summarizeProjectCoverage,
+  promoteSourceCoverage,
+  upsertAdapterCoverageRows,
+  recordCoverageDecision,
+  writeJsonAtomic,
+};