@wix/agent-skills 1.33.1 → 1.34.0

package/skills/wix-replatform/lib/import-recovery.js

@@ -1,14 +1,44 @@
 'use strict';
 
+const { verificationKind } = require('./entity-verification');
 const crypto = require('node:crypto');
 const fs = require('node:fs/promises');
 const path = require('node:path');
-const { loadAttemptJournal, loadCrosswalk } = require('./local-state.js');
+const {
+  UNRESOLVED_ATTEMPT_STATUSES,
+  loadAttemptJournal,
+  loadCrosswalk,
+  rerunDecision,
+  attemptJournalPath,
+  readAttemptJournalSince,
+  foldAttemptsBySourceKey,
+} = require('./local-state.js');
+const { updateSupportFor } = require('./rerun-conflicts.js');
+const { appendExecutionLog } = require('./execution-log.js');
 
 const RECOVERY_SCHEMA_VERSION = 1;
-const RECOVERY_MODES = ['partial', 'missing-only', 'failed-only', 'deferred-only', 'resumed'];
+const RECOVERY_MODES = ['partial', 'missing-only', 'failed-only', 'deferred-only', 'unresolved-only', 'resumed', 'rerun'];
 const RECOVERY_STATUSES = ['complete', 'partial', 'failed', 'blocked'];
 const DEFERRED_ATTEMPT_STATUSES = new Set(['deferred', 'needs_verification']);
+// A missing crosswalk link uses existing source-marker/natural-key checks and
+// attempt-journal reconciliation before create. These statuses mean a previous write MIGHT have
+// landed without being confirmed into the crosswalk, so creating again risks a duplicate.
+const UNCERTAIN_ATTEMPT_STATUSES = new Set(['deferred', 'needs_verification', 'succeeded_unverified', 'started']);
+// The three terminal `skipped_*` statuses
+// `coverageStatusCounts` deliberately never buckets (it has no branch for any of them) make no
+// journal-count claim at all -- there is nothing an importer could even report a disagreeing
+// number for. A target type whose journal rows are ENTIRELY one or more of these is therefore not
+// "unreported journal activity"; it is a type nothing was ever attempted, deferred, or failed for.
+// Before this fix, the reverse journal->summary check (`unmatchedJournalEntities` below) counted
+// ALL rows for a target type, including these, so a type whose only rows were e.g.
+// `skipped_out_of_scope` was never named by any ordinary or naming-only summary bucket (nothing
+// was imported/deferred/failed/attempted/already-present for it) and fell into
+// `unmatchedJournalEntities` permanently -- for example a journal whose only row for
+// a target type (`ecom/shipping-option`) is a single `skipped_out_of_scope` row. Excluding these statuses from the "claiming" row count used by
+// that check -- and from `coverageByType`'s cumulative high-water mark itself,
+// so the mark and the check it feeds always measure the same thing -- fixes this without making
+// skipped_out_of_scope a journal-count claim anywhere else.
+const NON_CLAIMING_ATTEMPT_STATUSES = new Set(['skipped_already_imported', 'skipped_safe_mode_blocked', 'skipped_out_of_scope']);
 
 function executionDir(projectDir) {
   return path.join(projectDir, 'execution');
@@ -84,14 +114,167 @@ function normalizeSelectionFilters(input = {}) {
     missingOnly: Boolean(input.missingOnly || input['missing-only']),
     failedOnly: Boolean(input.failedOnly || input['failed-only']),
     deferredOnly: Boolean(input.deferredOnly || input['deferred-only']),
+    // Unresolved gets its own selection mode because its next action differs:
+    // read the target back, never re-send. Re-sending an uncertain write is how a recovery
+    // pass creates a duplicate on a live store.
+    unresolvedOnly: Boolean(input.unresolvedOnly || input['unresolved-only']),
   };
-  const exclusive = [filters.missingOnly, filters.failedOnly, filters.deferredOnly].filter(Boolean);
+  const exclusive = [filters.missingOnly, filters.failedOnly, filters.deferredOnly, filters.unresolvedOnly].filter(Boolean);
   if (exclusive.length > 1) {
-    throw new Error('--missing-only, --failed-only, and --deferred-only are mutually exclusive');
+    throw new Error('--missing-only, --failed-only, --deferred-only, and --unresolved-only are mutually exclusive');
   }
   return filters;
 }
 
+// A rerun buckets the refreshed scope into create / update / unchanged
+// / unknown against the crosswalk baseline. It is deliberately NOT expressible as the existing
+// filters: `missingOnly` excludes every crosswalk hit (so no changed record is ever seen) and
+// `failedOnly` only revisits what was already attempted (so a change nobody attempted is
+// missed). A regression check exists because an importer built from those two filters looks
+// like a delta and silently is not.
+//
+// `unknown` is a first-class outcome, never folded into unchanged: see rerunDecision.
+function selectRerunRecords(records, options = {}) {
+  if (!Array.isArray(records)) {
+    throw new Error('records must be an array');
+  }
+  const sourceSystem = options.sourceSystem || 'wordpress';
+  const sourceEntityType = requireString(
+    options.entity || options.sourceEntityType,
+    'rerun selection entity',
+  );
+  const getSourceId = options.getSourceId || defaultSourceId;
+  const crosswalkBySource = options.crosswalkBySource || {};
+  const attemptsBySource = options.attemptsBySource || foldAttemptsBySource(options.attemptRows || []);
+  // How to read this entity's version off a refreshed source record. Declared by the adapter,
+  // never guessed here — an object id or capture time must never be treated as a record version an object id or capture time as a record version.
+  const sourceVersionField = options.sourceVersionField || null;
+  const getSourceVersion = options.getSourceVersion
+    || ((record) => (sourceVersionField ? record?.[sourceVersionField] : undefined));
+  const getSourceHash = options.getSourceHash || (() => undefined);
+  const sourceHashDefinition = options.sourceHashDefinition || null;
+  // Excluded history and deletions stay out. The accepted scope is enforced HERE
+  // rather than deferred to a generated importer: `inScope(record)` returns false for anything
+  // the approved plan excluded, and those records are reported as out-of-scope, never actioned.
+  // Deletions need no rule beyond this loop: a record absent from the refreshed source is simply
+  // never iterated, so absence can never become a delete instruction.
+  const inScope = typeof options.inScope === 'function' ? options.inScope : null;
+  // Per-entity update capability, so a changed record for an entity with no verified
+  // revision-protected writer is reported for review instead of being routed to an update.
+  const entityRef = options.targetEntityRef || null;
+  const declaredUpdateWriters = options.declaredUpdateWriters || {};
+  // FAIL CLOSED. An undeclared entity used to default to supported:true, which bypassed BOTH the
+  // order ban and the verified-writer requirement — an order with no targetEntityRef went
+  // straight to `update`. Absence of a declaration is not evidence that an update is safe, so
+  // the missing declaration is itself a review outcome.
+  const updateSupport = updateSupportFor(entityRef, { declaredUpdateWriters });
+
+  const create = [];
+  const update = [];
+  const unchanged = [];
+  const unknown = [];
+  const excluded = [];
+  const outOfScope = [];
+  const needsReconciliation = [];
+  const reportForReview = [];
+
+  for (const record of records) {
+    const sourceId = getSourceId(record);
+    if (sourceId === undefined || sourceId === null || sourceId === '') {
+      excluded.push({ record, reason: 'missing_source_id' });
+      continue;
+    }
+    const stableKey = sourceStableKey(sourceSystem, sourceEntityType, String(sourceId));
+    if (inScope && !inScope(record)) {
+      outOfScope.push({ sourceStableKey: stableKey, reason: 'excluded_by_accepted_scope' });
+      continue;
+    }
+    const crosswalkRow = crosswalkBySource[stableKey] || null;
+    const latestAttempt = attemptsBySource[stableKey] || null;
+    const decision = rerunDecision({
+      crosswalkRow,
+      sourceVersion: getSourceVersion(record),
+      sourceVersionField,
+      sourceHash: getSourceHash(record),
+      sourceHashDefinition,
+    });
+    const entry = {
+      record,
+      sourceStableKey: stableKey,
+      existing: crosswalkRow,
+      latestAttempt,
+      decision,
+    };
+    if (decision.action === 'create') {
+      // The attempt journal is consulted, not merely carried: an unconfirmed earlier write may
+      // already exist on the target, so this reconciles before it creates a second one.
+      if (latestAttempt && UNCERTAIN_ATTEMPT_STATUSES.has(latestAttempt.status)) {
+        needsReconciliation.push({ ...entry, reason: `uncertain_prior_attempt:${latestAttempt.status}` });
+      } else {
+        create.push(entry);
+      }
+    } else if (decision.action === 'update') {
+      if (!updateSupport.supported) {
+        reportForReview.push({ ...entry, reason: updateSupport.reason, detail: updateSupport.detail || null });
+      } else if (latestAttempt && UNCERTAIN_ATTEMPT_STATUSES.has(latestAttempt.status)) {
+        // An uncertain attempt is as dangerous on a LINKED record as on a new one, for a
+        // different reason: if the previous write actually landed and the process died before
+        // saving its baseline, the saved revision is already stale. Re-sending it makes the
+        // importer collide with its OWN earlier write and report it to the user as a merchant
+        // edit. Reconcile first.
+        needsReconciliation.push({ ...entry, reason: `uncertain_prior_attempt:${latestAttempt.status}` });
+      } else {
+        update.push(entry);
+      }
+    } else if (decision.action === 'skip') {
+      if (verificationKind({ ...options, entity: sourceEntityType }) !== 'none') {
+        needsReconciliation.push({ ...entry, reason: 'unchanged_source_requires_target_verification' });
+      } else unchanged.push(entry);
+    } else {
+      unknown.push(entry);
+    }
+  }
+
+  // Unknown counts are not zero. The caller reports these four buckets separately; an
+  // unresolved record must never be summed into unchanged to make a report look clean.
+  return {
+    entity: sourceEntityType,
+    mode: 'rerun',
+    create,
+    update,
+    unchanged,
+    unknown,
+    excluded,
+    outOfScope,
+    needsReconciliation,
+    reportForReview,
+    updateSupport,
+    summary: {
+      entity: sourceEntityType,
+      recordsRead: records.length,
+      toCreate: create.length,
+      toUpdate: update.length,
+      unchanged: unchanged.length,
+      unknown: unknown.length,
+      needsReconciliation: needsReconciliation.length,
+      reportForReview: reportForReview.length,
+      outOfScope: outOfScope.length,
+      excluded: excluded.length,
+      sourceVersionField: sourceVersionField || null,
+    },
+  };
+}
+
+async function selectRerunRecordsFromState(projectDir, records, options = {}) {
+  const crosswalk = await loadCrosswalk(projectDir);
+  const attempts = await loadAttemptJournal(projectDir);
+  return selectRerunRecords(records, {
+    ...options,
+    crosswalkBySource: crosswalk.bySource,
+    attemptRows: attempts.rows,
+  });
+}
+
 function foldAttemptsBySource(attemptRows = []) {
   const bySource = {};
   for (const row of attemptRows) {
@@ -120,6 +303,7 @@ function selectImportRecords(records, options = {}) {
   const excluded = [];
   const failed = [];
   const deferred = [];
+  const unresolved = [];
 
   for (const record of records) {
     const sourceId = getSourceId(record);
@@ -136,7 +320,8 @@ function selectImportRecords(records, options = {}) {
       excluded.push({ sourceStableKey: stableKey, sourceType, reason: 'source_type_filter' });
       continue;
     }
-    if (filters.missingOnly && existing) {
+    const identityRequired = verificationKind({ ...options, entity: sourceEntityType, targetEntityType: existing?.targetEntityType }) !== 'none';
+    if (filters.missingOnly && existing && !identityRequired) {
       alreadyPresent.push({ sourceStableKey: stableKey, targetId: existing.targetId, reason: 'crosswalk' });
       continue;
     }
@@ -148,6 +333,10 @@ function selectImportRecords(records, options = {}) {
       excluded.push({ sourceStableKey: stableKey, reason: 'not_deferred' });
       continue;
     }
+    if (filters.unresolvedOnly && (!latestAttempt || !UNRESOLVED_ATTEMPT_STATUSES.has(latestAttempt.status))) {
+      excluded.push({ sourceStableKey: stableKey, reason: 'not_unresolved' });
+      continue;
+    }
 
     if (latestAttempt && String(latestAttempt.status).startsWith('failed')) {
       failed.push(stableKey);
@@ -155,6 +344,12 @@ function selectImportRecords(records, options = {}) {
     if (latestAttempt && DEFERRED_ATTEMPT_STATUSES.has(latestAttempt.status)) {
       deferred.push(stableKey);
     }
+    // Never also counted in `failed`: the two sets are disjoint by construction, and an
+    // uncertain write summed into a failure count produces a report that reconciles
+    // arithmetically and is wrong.
+    if (latestAttempt && UNRESOLVED_ATTEMPT_STATUSES.has(latestAttempt.status)) {
+      unresolved.push(stableKey);
+    }
     selected.push({ record, sourceStableKey: stableKey, sourceType, existing, latestAttempt });
   }
 
@@ -164,6 +359,7 @@ function selectImportRecords(records, options = {}) {
     selected,
     alreadyPresent,
     excluded,
+    unresolved,
     summary: {
       entity: sourceEntityType,
       sourceType: filters.sourceType || 'all',
@@ -173,6 +369,7 @@ function selectImportRecords(records, options = {}) {
       excluded: excluded.length,
       failedCandidates: failed.length,
       deferredCandidates: deferred.length,
+      unresolvedCandidates: unresolved.length,
     },
   };
 }
@@ -209,7 +406,8 @@ function normalizeRecoveryEntry(input = {}) {
   const mode = input.mode || (input.selectionFilters && (
     input.selectionFilters.missingOnly ? 'missing-only' :
       input.selectionFilters.failedOnly ? 'failed-only' :
-        input.selectionFilters.deferredOnly ? 'deferred-only' : 'partial'
+        input.selectionFilters.deferredOnly ? 'deferred-only' :
+          input.selectionFilters.unresolvedOnly ? 'unresolved-only' : 'partial'
   ));
   if (!RECOVERY_MODES.includes(mode)) {
     throw new Error(`recovery mode must be one of: ${RECOVERY_MODES.join(', ')}`);
@@ -222,10 +420,19 @@ function normalizeRecoveryEntry(input = {}) {
   if (Number.isNaN(Date.parse(timestamp))) {
     throw new Error('recovery timestamp must be an ISO timestamp');
   }
+  // `unresolved` must be stated, not defaulted: an entry that omits it is an
+  // entry whose author never decided where its uncertain writes went, and `count()` would
+  // silently read that as zero.
+  if (input.unresolved === undefined || input.unresolved === null) {
+    throw new Error('recovery unresolved count must be stated explicitly — uncertain writes are never folded into failed');
+  }
   const entry = {
     schemaVersion: RECOVERY_SCHEMA_VERSION,
     recoveryId: input.recoveryId || null,
     timestamp,
+    // This entry is built field by field, so anything not named here is
+    // dropped silently — which is why both of these are added explicitly.
+    runId: requireString(input.runId, 'recovery runId'),
     mode,
     selectionFilters: input.selectionFilters || {},
     reason: requireString(input.reason || 'operator_requested_recovery', 'recovery reason'),
@@ -235,16 +442,95 @@ function normalizeRecoveryEntry(input = {}) {
     alreadyPresent: count(input.alreadyPresent, 'alreadyPresent'),
     failed: count(input.failed, 'failed'),
     deferred: count(input.deferred, 'deferred'),
+    // Its own count, never summed into `failed`. A recovery record whose failed count silently
+    // includes uncertain writes reconciles arithmetically and is wrong, which is the worst
+    // combination available.
+    unresolved: count(input.unresolved, 'unresolved'),
     crosswalkChanges: input.crosswalkChanges || { before: 0, after: 0, added: 0, updated: 0 },
     summaryChanges: input.summaryChanges || {},
     outcome: requireString(input.outcome || status, 'recovery outcome'),
     status,
     logs: Array.isArray(input.logs) ? input.logs : [],
+    // A keep-Wix answer has to survive a reload, or the next rerun re-asks a
+    // question the user already answered — or worse, silently overwrites what they chose to
+    // keep. This entry is built field-by-field, so anything not named here is dropped; before
+    // this, passing a recordConflictDecision() result through lost choice, record identity,
+    // versions and the binding fingerprint without erroring.
+    conflictDecisions: normalizeConflictDecisions(input.conflictDecisions),
   };
   entry.recoveryId = recoveryIdFor(entry);
   return entry;
 }
 
+// Each decision keeps exactly the fields keepDecisionApplies()/approvalApplies() need to judge
+// whether it still applies. A decision missing any of them cannot be matched later, so it is
+// rejected at write time rather than silently stored as unusable.
+const CONFLICT_DECISION_FIELDS = [
+  'choice', 'sourceStableKey', 'targetId', 'entity',
+  'sourceVersion', 'sourceHash', 'reviewedTargetRevision', 'bindingFingerprint',
+  'decidedBy', 'decidedAt',
+];
+
+function normalizeConflictDecisions(input) {
+  if (input === undefined || input === null) {
+    return [];
+  }
+  if (!Array.isArray(input)) {
+    throw new Error('conflictDecisions must be an array');
+  }
+  return input.map((d, i) => {
+    if (!d || typeof d !== 'object') {
+      throw new Error(`conflictDecisions[${i}] must be an object`);
+    }
+    for (const required of ['choice', 'sourceStableKey', 'targetId', 'bindingFingerprint']) {
+      if (!d[required] || typeof d[required] !== 'string') {
+        throw new Error(`conflictDecisions[${i}].${required} must be a non-empty string — a decision that cannot be matched to a record is not reusable`);
+      }
+    }
+    if (!['override', 'keep'].includes(d.choice)) {
+      throw new Error(`conflictDecisions[${i}].choice must be override or keep`);
+    }
+    const out = {};
+    for (const f of CONFLICT_DECISION_FIELDS) {
+      out[f] = d[f] === undefined ? null : d[f];
+    }
+    return out;
+  });
+}
+
+// Reads every conflict decision recorded across the whole recovery log, newest last, so a rerun
+// can ask "did the user already answer for this record?" without replaying the log itself.
+function recoveryEntriesOf(recoveryLog) {
+  // loadRecoveryLog() returns an ARRAY. Reading `.entries` off it yields
+  // Array.prototype.entries -- a function, which a for-of then rejects with a bare
+  // "entries is not iterable". Accept the array (the real shape on disk) and the
+  // `{ entries: [...] }` wrapper, and treat anything else as empty.
+  if (Array.isArray(recoveryLog)) {
+    return recoveryLog;
+  }
+  if (recoveryLog && Array.isArray(recoveryLog.entries)) {
+    return recoveryLog.entries;
+  }
+  return [];
+}
+
+function loadConflictDecisions(recoveryLog) {
+  const entries = recoveryEntriesOf(recoveryLog);
+  const out = [];
+  for (const entry of entries) {
+    for (const d of (entry.conflictDecisions || [])) {
+      out.push({ ...d, recoveryId: entry.recoveryId || null, timestamp: entry.timestamp || null });
+    }
+  }
+  return out;
+}
+
+// The newest decision for one record, which is the only one that can still apply.
+function latestConflictDecisionFor(recoveryLog, sourceStableKey) {
+  const all = loadConflictDecisions(recoveryLog).filter((d) => d.sourceStableKey === sourceStableKey);
+  return all.length ? all[all.length - 1] : null;
+}
+
 async function loadRecoveryLog(projectDir) {
   const rows = await readJsonIfExists(recoveryLogPath(projectDir), []);
   if (!Array.isArray(rows)) {
@@ -277,14 +563,427 @@ function diffCounts(before = {}, after = {}) {
   return diff;
 }
 
+// ---------------------------------------------------------------------------
+// The live import summary checks its held counters against the attempt journal for
+// the same run, instead of trusting them on faith. This cache keeps that check cheap and isolated per run.
+// ---------------------------------------------------------------------------
+
+const COVERAGE_JOURNAL_REL_PATH = 'state/attempts/write-attempts.ndjson';
+const COVERAGE_ORDINARY_BUCKETS = ['imported', 'deferred', 'failed', 'attempted'];
+// A flush can legitimately name an entity ONLY through a
+// non-coverage-bucket counter -- `alreadyPresentByCrosswalk` records what a re-run pass found
+// already linked, with nothing attempted this run and so no journal status to compare it
+// against (the `imported + alreadyPresentByCrosswalk + deferred + failed == inScope` identity
+// this repo's entityCompleteness accounting already protects). A flush naming only this
+// counter for an entity is still reporting on that entity: it must count toward "this flush named
+// it" for the reverse-direction match, the same way an ordinary bucket does, or a correct re-run
+// pass reporting solely `alreadyPresentByCrosswalk` gets the same false `unmatchedJournalEntities`
+// mismatch an ordinary bucket's absence would produce if it were mistaken for silence.
+const COVERAGE_NAMING_ONLY_BUCKETS = ['alreadyPresentByCrosswalk'];
+
+// Keyed by the absolute live-journal path, so distinct project directories (or a test's many temp
+// dirs) never share state. Each entry's `offset` is the end of the last complete line read; `runs`
+// holds one folded Map<sourceStableKey, latestRow> PER RUN ID seen in the journal so far -- not
+// only the run currently flushing -- so switching from run A to run B and back never carries A's
+// rows into B's map and never misses a row written while the other run was flushing. Memory is
+// O(unique records across runs in the journal); work per flush is O(new bytes read).
+//
+// `reportedEntityCoverage` is a SIBLING per-run accumulator, independent of the folded rows: for
+// each resolved target entity type some flush of this run has named a summary key for (ever, not
+// only the flush currently running), it keeps the highest CLAIMING journal row count (never the raw row count -- see `NON_CLAIMING_ATTEMPT_STATUSES` above) that was true for
+// that entity AT THE TIME it was last named -- not just a boolean "was it ever named". The journal fold
+// is deliberately cumulative across the whole run (so a later flush sees everything an earlier one
+// did -- that is the point of this cache), but `live-import-summary.json` is fully overwritten on
+// every flush and a real multi-entity importer flushes one entity at a time (the only documented
+// caller shape, rp-import-codegen/SKILL.md's contacts wrapper). Comparing the CURRENT flush's
+// summary keys against the FULL run's cumulative journal entity types would then flag every entity
+// reported by an earlier flush of the SAME run as "journal has rows, no summary key names it" the
+// moment a later flush reports a different entity -- a false mismatch on every correctly-behaving
+// multi-entity run. Tracking what has EVER been named across
+// the run's own flushes, instead of only the current one, keeps a truly never-reported entity type
+// detectable (it is never added) while an entity named by an earlier flush of this same run is
+// correctly recognized as reported, not re-flagged by a later, different flush -- AS LONG AS the
+// journal has not grown new rows for that entity since the last time it was named.
+//
+// A plain per-entity boolean
+// is wrong, because "named once" is not the same thing as "accounts for the journal's current
+// state". A flush naming an entity ONLY via a naming-only bucket (`alreadyPresentByCrosswalk`)
+// while that entity had zero matching journal rows at that moment legitimately agrees -- but if the journal LATER accrues real, ordinary-status rows for that same entity type,
+// and no later flush of the run ever names it again (via any bucket), a permanent boolean would
+// keep calling that entity "reported" forever, hiding genuinely unreported journal activity from
+// the reverse-direction (journal -> summary) check this check exists to provide. Storing the ROW
+// COUNT that was true at the moment of naming, instead of a bare boolean, and re-comparing it
+// against the journal's CURRENT row count on every subsequent flush, fixes this without reopening
+// either case: an entity whose journal rows have not grown past what was already named stays correctly
+// exempt (the legitimate "nothing new happened" cases both look like this), while new,
+// never-claimed rows past that high-water mark are caught the same way a never-named entity is.
+//
+// This whole cache, including `reportedEntityCoverage`, is
+// process-local (in-memory) and is NOT persisted across a process restart. That is intentional,
+// not an oversight: a run id's entire lifetime is confined to one process by a GATE-ENFORCED
+// contract, not merely a convention. Every generated importer must self-describe
+// `runIdSource: "process-start"` (`assertGeneratedImporterContract` below rejects anything else;
+// `rp-import-codegen/SKILL.md`'s "runId is the id the importer mints at process start" and
+// `rp-execute-import/SKILL.md`'s recovery-log contract, "the id the importer minted at process
+// start, so the entry is attributable to a pass", restate the same rule). So a genuinely resumed
+// or recovery pass is a NEW process that mints a NEW run id -- it is correct, not a loss of state,
+// for that new run id's `reportedEntityCoverage` to start empty, because no flush has ever happened
+// under it. This reasoning does NOT cover a caller outside that gated contract that manually
+// reuses an old run id across a process restart (for example an ad hoc recovery script bypassing
+// codegen); that usage is unsupported today and would resurface the false-mismatch pattern on
+// its first post-restart flush.
+const coverageJournalCache = new Map();
+
+function emptyCoverageCacheEntry() {
+  return { offset: 0, runs: new Map(), reportedEntityCoverage: new Map() };
+}
+
+// Reuses `foldAttemptsBySourceKey` (local-state.js) on just the newly read rows, grouped by run,
+// then merges each run's folded result into that run's cached map -- `Map.set` overwrites, and the
+// new rows are strictly later in file order than whatever is already cached, so this reproduces
+// exactly what folding the whole run's rows from scratch would produce.
+function mergeRowsIntoCoverageCache(entry, rows) {
+  const byRun = new Map();
+  for (const row of rows) {
+    if (!row || !row.runId || !row.sourceStableKey) {
+      continue;
+    }
+    if (!byRun.has(row.runId)) {
+      byRun.set(row.runId, []);
+    }
+    byRun.get(row.runId).push(row);
+  }
+  for (const [rowRunId, runRows] of byRun) {
+    const folded = foldAttemptsBySourceKey(runRows);
+    let runMap = entry.runs.get(rowRunId);
+    if (!runMap) {
+      runMap = new Map();
+      entry.runs.set(rowRunId, runMap);
+    }
+    for (const [key, row] of folded) {
+      runMap.set(key, row);
+    }
+  }
+}
+
+// Count buckets, computed directly from the folded rows' latest status -- never derived by summing
+// other held counters. `attempted` matches this repo's documented semantics
+// (rp-import-codegen/SKILL.md:2181-2182): imported or failed, never deferred.
+function coverageStatusCounts(rows) {
+  const counts = { imported: 0, deferred: 0, failed: 0, attempted: 0, unexpectedSkipped: 0, unresolved: 0 };
+  for (const row of rows) {
+    const status = row.status;
+    if (status === 'imported') {
+      counts.imported += 1;
+      counts.attempted += 1;
+    } else if (status === 'failed_retryable' || status === 'failed_terminal') {
+      counts.failed += 1;
+      counts.attempted += 1;
+    } else if (DEFERRED_ATTEMPT_STATUSES.has(status)) {
+      counts.deferred += 1;
+    } else if (status === 'skipped_unexpected') {
+      counts.unexpectedSkipped += 1;
+    } else if (UNRESOLVED_ATTEMPT_STATUSES.has(status)) {
+      counts.unresolved += 1;
+    }
+  }
+  return counts;
+}
+
+// A held counter is "carried" only when the summary names it explicitly, including an explicit 0
+// -- `in` rather than a truthiness check, so a real `0` is never mistaken for absence.
+function heldBucketValue(summary, bucket, key) {
+  const container = summary && summary[bucket];
+  if (!container || typeof container !== 'object' || !(key in container)) {
+    return { present: false, value: null };
+  }
+  return { present: true, value: container[key] };
+}
+
+function truncateMessage(message) {
+  return typeof message === 'string' && message.length > 300 ? message.slice(0, 300) : message;
+}
+
+// Disagreeing `{key, bucket, held, journal}` entries, in entity-then-bucket order -- shared by the
+// execution-log detail text below and by completion-report.js's operator-action text.
+function coverageDisagreements(coverageCheck) {
+  const items = [];
+  for (const [key, row] of Object.entries((coverageCheck && coverageCheck.entities) || {})) {
+    for (const bucket of [...COVERAGE_ORDINARY_BUCKETS, 'unexpectedSkipped']) {
+      const counter = row[bucket];
+      if (counter && counter.compared && counter.agrees === false) {
+        items.push({ key, bucket, held: counter.held, journal: counter.journal });
+      }
+    }
+  }
+  return items;
+}
+
+function describeCoverageMismatch(coverageCheck) {
+  const parts = coverageDisagreements(coverageCheck)
+    .map((item) => `${item.key}.${item.bucket} disagrees (held ${item.held}, journal ${item.journal})`);
+  for (const key of (coverageCheck && coverageCheck.unmatched) || []) {
+    parts.push(`${key} not found in the journal for this run`);
+  }
+  for (const type of (coverageCheck && coverageCheck.unmatchedJournalEntities) || []) {
+    parts.push(`journal has ${type} records not named by any summary key`);
+  }
+  return parts.join('; ') || 'coverage check mismatch';
+}
+
+// Reads (incrementally, via the cache above) the live journal rows for `runId`,
+// folds them, and compares them against `summary`'s held counters. Never throws: every case the
+// check itself cannot complete resolves to `status: "unchecked"` with a named `reason`.
+async function computeCoverageCheck(projectDir, summary, options, runId) {
+  const checkedAt = new Date().toISOString();
+  const base = { runId: runId || null, checkedAt, journalPath: COVERAGE_JOURNAL_REL_PATH };
+  if (!runId) {
+    return { ...base, status: 'unchecked', reason: 'no_run_id', rowsRead: 0, entities: {}, unmatched: [], unmatchedJournalEntities: [] };
+  }
+
+  const absPath = path.resolve(attemptJournalPath(projectDir));
+  let entry = coverageJournalCache.get(absPath);
+  if (!entry) {
+    entry = emptyCoverageCacheEntry();
+    coverageJournalCache.set(absPath, entry);
+  }
+
+  let readResult;
+  try {
+    readResult = await readAttemptJournalSince(projectDir, entry.offset);
+  } catch (error) {
+    if (error && error.code === 'JOURNAL_MISSING') {
+      return { ...base, status: 'unchecked', reason: 'journal_missing', rowsRead: 0, entities: {}, unmatched: [], unmatchedJournalEntities: [] };
+    }
+    if (error && error.code === 'JOURNAL_READ_FAILED') {
+      return {
+        ...base, status: 'unchecked', reason: 'journal_read_failed', rowsRead: 0, entities: {}, unmatched: [], unmatchedJournalEntities: [],
+        error: { code: (error.cause && error.cause.code) || null, message: truncateMessage(error.message) },
+      };
+    }
+    if (error && error.code === 'JOURNAL_INVALID') {
+      // Drop the whole cache entry so the next flush retries with a full read.
+      coverageJournalCache.delete(absPath);
+      return {
+        ...base, status: 'unchecked', reason: 'journal_invalid', rowsRead: 0, entities: {}, unmatched: [], unmatchedJournalEntities: [],
+        error: { line: truncateMessage(error.line), message: truncateMessage(error.message) },
+      };
+    }
+    throw error;
+  }
+
+  if (readResult.truncated) {
+    entry.runs = new Map();
+    entry.reportedEntityCoverage = new Map();
+  }
+  mergeRowsIntoCoverageCache(entry, readResult.rows);
+  entry.offset = readResult.nextOffset;
+
+  const runMap = entry.runs.get(runId) || new Map();
+  const entityTypesOption = (options && options.entityTypes) || {};
+  const resolveTargetEntityType = (key) => entityTypesOption[key] || key;
+
+  // Buckets that merely NAME an entity (for match purposes) vs. buckets whose VALUE is actually
+  // compared against the journal. `alreadyPresentByCrosswalk` is in the first set only.
+  const summaryKeys = new Set();
+  for (const bucket of [...COVERAGE_ORDINARY_BUCKETS, 'unexpectedSkipped', ...COVERAGE_NAMING_ONLY_BUCKETS]) {
+    const container = summary && summary[bucket];
+    if (container && typeof container === 'object') {
+      for (const key of Object.keys(container)) {
+        summaryKeys.add(key);
+      }
+    }
+  }
+
+  const rowsByTargetType = new Map();
+  for (const row of runMap.values()) {
+    const type = row.targetEntityType;
+    if (!rowsByTargetType.has(type)) {
+      rowsByTargetType.set(type, []);
+    }
+    rowsByTargetType.get(type).push(row);
+  }
+
+  const entities = {};
+  const unmatched = [];
+  const matchedTargetTypes = new Set();
+  let anyMismatch = false;
+  let anyUnresolved = false;
+
+  for (const key of summaryKeys) {
+    const targetType = resolveTargetEntityType(key);
+    const rows = rowsByTargetType.get(targetType) || [];
+    // A key named ONLY through a naming-only bucket (e.g. `alreadyPresentByCrosswalk`) makes
+    // no claim about journal activity for this entity -- zero matching rows is its expected,
+    // unremarkable state (nothing was attempted this run), not an unmatched claim. A key that
+    // names at least one ORDINARY bucket (imported/deferred/failed/attempted) is still held to
+    // the existing rule: claiming activity with zero matching journal rows is unmatched.
+    const namesOrdinaryBucket = COVERAGE_ORDINARY_BUCKETS.some((bucket) => heldBucketValue(summary, bucket, key).present);
+    if (rows.length === 0 && namesOrdinaryBucket) {
+      // A summary key with no matching rows is reported as unmatched, never as agreement.
+      unmatched.push(key);
+      anyMismatch = true;
+      continue;
+    }
+    matchedTargetTypes.add(targetType);
+    const counts = coverageStatusCounts(rows);
+    if (counts.unresolved > 0) {
+      anyUnresolved = true;
+    }
+    const entityRow = { unresolved: counts.unresolved };
+    for (const bucket of COVERAGE_ORDINARY_BUCKETS) {
+      const held = heldBucketValue(summary, bucket, key);
+      if (!held.present) {
+        entityRow[bucket] = { held: null, journal: counts[bucket], agrees: null, compared: false };
+      } else {
+        const agrees = held.value === counts[bucket];
+        if (!agrees) {
+          anyMismatch = true;
+        }
+        entityRow[bucket] = { held: held.value, journal: counts[bucket], agrees, compared: true };
+      }
+    }
+    // `unexpectedSkipped` is deliberately the opposite of the four ordinary buckets: a status
+    // nothing should ever reach must not go invisible merely because the importer never named a
+    // counter for it, so an absent held value defaults to 0 rather than to "not compared".
+    const heldSkipped = heldBucketValue(summary, 'unexpectedSkipped', key);
+    const heldSkippedValue = heldSkipped.present ? heldSkipped.value : 0;
+    const skippedAgrees = heldSkippedValue === counts.unexpectedSkipped;
+    if (!skippedAgrees) {
+      anyMismatch = true;
+    }
+    entityRow.unexpectedSkipped = { held: heldSkippedValue, journal: counts.unexpectedSkipped, agrees: skippedAgrees, compared: true };
+    entities[key] = entityRow;
+  }
+
+  // Accumulate this flush's matched target types into the run's PERSISTED, cumulative
+  // coverage map -- not a bare "was it ever named" boolean, but the CLAIMING journal row count that
+  // was true for that entity AT THE TIME it was named. See the cache comment above
+  // `coverageJournalCache` for why cumulative tracking across flushes is required at all, and
+  // for why a boolean is not enough on its own: a naming-only bucket (or any bucket) can
+  // legitimately name an entity while the journal has zero (or fewer) rows for it, and the journal
+  // can keep growing afterward without any later flush ever naming that entity again. Storing the
+  // row count lets the reverse check keep comparing cumulative reported coverage against the
+  // journal's cumulative state on every flush, instead of permanently exempting an entity the
+  // moment it is named once.
+  //
+  // This mark and the reverse-mismatch check below are two
+  // halves of one invariant -- "the mark only ever reflects rows that make a journal-count claim" --
+  // and must be computed from the SAME per-type claiming count, not two separately-filtered ones.
+  // Updating the mark with each type's FULL row count (claiming + non-claiming) while the check below
+  // compares it against the claiming-only count let a type matched while it already had non-claiming
+  // rows (e.g. `skipped_out_of_scope`) set an inflated mark that could then mask a later genuine,
+  // never-renamed claiming row (e.g. a real `imported` row) for that same type -- the mark never
+  // dropped, so `covered < claimingRowCount` stayed false even though the claim was real. Computing
+  // `claimingRowCountByType` once, up front, and using it for BOTH the mark and the check keeps them
+  // structurally unable to drift apart again.
+  const claimingRowCountByType = new Map();
+  for (const [targetType, rowsForType] of rowsByTargetType) {
+    const claimingRowCount = rowsForType.filter((row) => !NON_CLAIMING_ATTEMPT_STATUSES.has(row.status)).length;
+    claimingRowCountByType.set(targetType, claimingRowCount);
+  }
+
+  let coverageByType = entry.reportedEntityCoverage.get(runId);
+  if (!coverageByType) {
+    coverageByType = new Map();
+    entry.reportedEntityCoverage.set(runId, coverageByType);
+  }
+  for (const targetType of matchedTargetTypes) {
+    const claimingRowCount = claimingRowCountByType.get(targetType) || 0;
+    const previouslyCovered = coverageByType.get(targetType) || 0;
+    coverageByType.set(targetType, Math.max(previouslyCovered, claimingRowCount));
+  }
+
+  // Journal -> summary direction: a targetEntityType with real folded CLAIMING rows but no summary
+  // key EVER naming it across this run's flushes (directly, or via `entityTypes`) is a counter the
+  // importer never reported. "Named" is re-checked against the journal's CURRENT cumulative
+  // claiming row count on every flush, not treated as a one-time permanent exemption -- an entity
+  // whose claiming row count has grown past what was covered the last time it was named is just as
+  // unreported, from this run's own summary, as one that was never named at all.
+  //
+  // A target type whose ONLY rows are e.g. `skipped_out_of_scope` has zero claiming rows, so
+  // `covered` (0, since `coverageByType` only ever accumulates claiming counts too) is never less
+  // than 0 and it is correctly never flagged -- it made no claim, so there is nothing to be missing.
+  const unmatchedJournalEntities = [];
+  for (const [targetType, claimingRowCount] of claimingRowCountByType) {
+    const covered = coverageByType.get(targetType) || 0;
+    if (covered < claimingRowCount) {
+      unmatchedJournalEntities.push(targetType);
+      anyMismatch = true;
+    }
+  }
+
+  let status;
+  let reason;
+  if (anyMismatch) {
+    status = 'mismatch';
+  } else if (anyUnresolved) {
+    status = 'unchecked';
+    reason = 'has_unresolved';
+  } else {
+    status = 'agrees';
+  }
+
+  return {
+    ...base,
+    status,
+    ...(reason ? { reason } : {}),
+    rowsRead: readResult.rows.length,
+    entities,
+    unmatched,
+    unmatchedJournalEntities,
+  };
+}
+
+// This is the PER-BATCH FLUSH POINT, not a recovery-only helper. An
+// importer that holds its counters until the end loses them to any interruption, and a long
+// import redirected to a temp file loses them to the shell. Call it after every batch with the
+// run's own held counters -- never with figures re-derived from the append-only ledger, which
+// folds dry-run rows, retried batches and recovery re-entries into the live total.
+//
+// Durable accounting, not liveness: heartbeat output belongs to `lib/progress-log.js`.
+//
+// When this flush names a run id (its own `options.runId`, else `summary.runId`), the
+// write is also checked against that run's attempt-journal rows. The check never replaces a
+// held counter and never throws for its own sake -- a wrong or uncheckable count is reported, not
+// hidden, and the write still completes normally either way.
 async function writeLiveImportSummary(projectDir, summary, options = {}) {
   const before = await readJsonIfExists(liveImportSummaryPath(projectDir), null);
+  const effectiveRunId = options.runId || (summary && summary.runId) || null;
+  const coverageCheck = await computeCoverageCheck(projectDir, summary, options, effectiveRunId);
   const next = {
     schemaVersion: 1,
     generatedAt: new Date().toISOString(),
     ...(summary || {}),
+    coverageCheck,
   };
   await writeJsonAtomic(liveImportSummaryPath(projectDir), next);
+  if (options.runId) {
+    await appendExecutionLog(projectDir, {
+      runId: options.runId,
+      phase: options.phase || 'import',
+      event: 'batch_flush',
+      detail: options.detail || `accounting flushed after batch ${options.batchNumber === undefined ? '(unnumbered)' : options.batchNumber}`,
+      artifacts: ['execution/live-import-summary.json'],
+    });
+  }
+  if (effectiveRunId && coverageCheck.status === 'mismatch') {
+    await appendExecutionLog(projectDir, {
+      runId: effectiveRunId,
+      phase: options.phase || 'import',
+      event: 'coverage_mismatch',
+      detail: describeCoverageMismatch(coverageCheck),
+      artifacts: ['execution/live-import-summary.json'],
+    });
+  } else if (effectiveRunId && coverageCheck.status === 'unchecked') {
+    await appendExecutionLog(projectDir, {
+      runId: effectiveRunId,
+      phase: options.phase || 'import',
+      event: 'coverage_unchecked',
+      detail: `coverage check could not run (reason: ${coverageCheck.reason})`,
+      artifacts: ['execution/live-import-summary.json'],
+    });
+  }
   return {
     path: 'execution/live-import-summary.json',
     beforeExists: Boolean(before),
@@ -294,11 +993,95 @@ async function writeLiveImportSummary(projectDir, summary, options = {}) {
       failed: diffCounts(before && before.failed, next.failed),
       ...(options.extraChanges || {}),
     },
+    coverageCheck,
   };
 }
 
+
+// ---------------------------------------------------------------------------
+// The generated importer declares its modes, and the gate checks them.
+//
+// Before this, the codegen skill ASKED for selective-recovery flags and nothing anywhere
+// verified that a generated importer honoured the instruction. A generated importer once
+// shipped that parsed no command-line arguments at all, exposed none of the modes,
+// and passed the import gate — a mandatory boundary that existed only as prose.
+// ---------------------------------------------------------------------------
+
+const GENERATED_IMPORTER_CONTRACT_VERSION = 1;
+
+const REQUIRED_SELECTION_MODES = [
+  'entity',
+  'source-type',
+  'missing-only',
+  'failed-only',
+  'deferred-only',
+  'unresolved-only',
+  'rerun',
+];
+
+// Project-relative, forward-slashed. These are the paths the shared helpers actually write, so
+// a descriptor that names something else describes an importer keeping a private ledger.
+const REQUIRED_LEDGER_PATHS = {
+  attempts: 'state/attempts/write-attempts.ndjson',
+  sampleAttempts: 'state/sample/attempts/write-attempts.ndjson',
+  unresolved: 'execution/unresolved-writes.ndjson',
+  recoveryLog: 'execution/recovery-log.json',
+};
+
+// Throws naming EVERY missing mode and EVERY misplaced path at once. One error per run of the
+// gate would turn a codegen fix into a guessing game.
+function assertGeneratedImporterContract(descriptor) {
+  const problems = [];
+  if (!descriptor || typeof descriptor !== 'object' || Array.isArray(descriptor)) {
+    throw new Error('generated importer contract: descriptor must be an object — an entrypoint that ignores --describe fails the gate, it never passes by default');
+  }
+  if (descriptor.contractVersion !== GENERATED_IMPORTER_CONTRACT_VERSION) {
+    problems.push(`contractVersion must be ${GENERATED_IMPORTER_CONTRACT_VERSION}, got ${JSON.stringify(descriptor.contractVersion)}`);
+  }
+  if (descriptor.runIdSource !== 'process-start') {
+    problems.push(`runIdSource must be "process-start", got ${JSON.stringify(descriptor.runIdSource)}`);
+  }
+  const modes = Array.isArray(descriptor.selectionModes) ? descriptor.selectionModes : null;
+  if (!modes) {
+    problems.push('selectionModes must be an array of mode names');
+  } else {
+    for (const mode of REQUIRED_SELECTION_MODES) {
+      if (!modes.includes(mode)) {
+        problems.push(`missing selection mode: ${mode}`);
+      }
+    }
+  }
+  const ledger = descriptor.ledger;
+  if (!ledger || typeof ledger !== 'object' || Array.isArray(ledger)) {
+    problems.push('ledger must be an object naming the durable artifact paths');
+  } else {
+    for (const [key, expected] of Object.entries(REQUIRED_LEDGER_PATHS)) {
+      const actual = ledger[key];
+      if (typeof actual !== 'string' || actual.replace(/\\/g, '/') !== expected) {
+        problems.push(`ledger.${key} must be "${expected}", got ${JSON.stringify(actual)}`);
+      }
+    }
+    // The vendoring escape hatch survives for the helper IMPLEMENTATIONS; it does not survive
+    // for the entry contract, and an append-only ledger is part of that contract.
+    if (ledger.appendOnly !== true) {
+      problems.push('ledger.appendOnly must be true — a per-record log of what we wrote to a merchant store is only ever appended to');
+    }
+  }
+  if (problems.length) {
+    throw new Error(`generated importer contract violated:\n  - ${problems.join('\n  - ')}`);
+  }
+  return descriptor;
+}
+
 module.exports = {
   RECOVERY_SCHEMA_VERSION,
+  RECOVERY_MODES,
+  DEFERRED_ATTEMPT_STATUSES,
+  UNCERTAIN_ATTEMPT_STATUSES,
+  GENERATED_IMPORTER_CONTRACT_VERSION,
+  REQUIRED_SELECTION_MODES,
+  REQUIRED_LEDGER_PATHS,
+  assertGeneratedImporterContract,
   recoveryLogPath,
   liveImportSummaryPath,
   normalizeSelectionFilters,
@@ -306,8 +1089,19 @@ module.exports = {
   sourceStableKey,
   selectImportRecords,
   selectImportRecordsFromState,
+  selectRerunRecords,
+  selectRerunRecordsFromState,
   normalizeRecoveryEntry,
+  normalizeConflictDecisions,
+  recoveryEntriesOf,
+  loadConflictDecisions,
+  latestConflictDecisionFor,
   loadRecoveryLog,
   appendRecoveryLogEntry,
   writeLiveImportSummary,
+  // Exported so `completion-report.js`'s operator-action text and `website-handoff.js`'s
+  // rendering can describe the same disagreements the writer computed, without recomputing them.
+  coverageDisagreements,
+  describeCoverageMismatch,
+  COVERAGE_JOURNAL_REL_PATH,
 };