'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,
};