1'use strict';
2
3// Source coverage accountability.
4//
5// A capability a source adapter advertised or attempted but did not capture (a 401/403 entity, a
6// data route skipped by rule, a route that failed, a quick-mode exclusion) never becomes a
7// `source-schema.json` entity, so before this module nothing forced it into the mapping-gaps
8// ledger or the completion report. It could disappear silently.
9//
10// This module owns the one schema for that record and the one join that decides what each row
11// means for the run's outcome:
12//
13//   adapter -> data/<source>-discovery/source-coverage.json   (rows; written by the adapter)
14//   rp-discovery promote -> discovery/source-coverage.json    (+ `sourceCoverageContract` stamp)

source-coverage.js on GitHub

// 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,

};