@wix/agent-skills 1.33.0 → 1.34.0

package/skills/wix-replatform/lib/member-crosswalk.js

@@ -0,0 +1,69 @@
+'use strict';
+
+// A project-local crosswalk over the shared state/crosswalk/crosswalk.ndjson (the same file and
+// row shape every other adapter reads -- see local-state.js and order-history.js's own comment on
+// the convention), specialized to the shape resolveOrderBuyer needs: get(sourceCustomerId) ->
+// { memberId, loginEmail } | null.
+//
+// Reuses local-state.js's rewrite-based loader rather than order-history.js's incremental,
+// crash-hardened one: member volume is a small fraction of order volume (customers, not orders),
+// so a full reparse on a cache miss is cheap, and the crash discipline order-history.js needed for
+// the invoice-pending sibling file has no analogue here.
+
+const path = require('node:path');
+const localState = require('./local-state.js');
+
+function createProjectMemberCrosswalk({ projectDir, sourceSystem = 'wordpress', sourceEntityType = 'customer' } = {}) {
+  if (!projectDir) throw new Error('createProjectMemberCrosswalk needs the migration projectDir');
+  const key = (sourceId) => `${sourceSystem}:${sourceEntityType}:${String(sourceId)}`;
+  let cache = null;
+  let cachedStatKey = null;
+
+  async function refresh() {
+    const filePath = localState.crosswalkPath(projectDir);
+    let statKey = 'absent';
+    try {
+      const st = await require('node:fs/promises').stat(filePath);
+      statKey = `${st.ino}:${st.size}:${st.mtimeMs}`;
+    } catch (error) {
+      if (error && error.code !== 'ENOENT') throw error;
+    }
+    if (cache && statKey === cachedStatKey) return cache;
+    cache = await localState.loadCrosswalk(projectDir);
+    cachedStatKey = statKey;
+    return cache;
+  }
+
+  return {
+    async get(sourceId) {
+      const { bySource } = await refresh();
+      const row = bySource[key(sourceId)];
+      if (!row || row.status !== 'imported') return null;
+      return { memberId: row.targetId, loginEmail: row.loginEmail || null };
+    },
+    // Writers persist through here so `loginEmail` rides the row alongside the required fields
+    // (upsertCrosswalkRow does not reject extra properties).
+    async put(sourceId, { memberId, loginEmail, contactId = null } = {}) {
+      if (!memberId) throw new Error('createProjectMemberCrosswalk.put needs memberId');
+      const row = {
+        schemaVersion: 1,
+        sourceSystem,
+        sourceEntityType,
+        sourceId: String(sourceId),
+        sourceStableKey: key(sourceId),
+        targetSystem: 'wix',
+        targetEntityType: 'member',
+        targetId: String(memberId),
+        status: 'imported',
+        updatedAt: new Date().toISOString(),
+        ...(loginEmail ? { loginEmail: String(loginEmail).trim().toLowerCase() } : {}),
+        ...(contactId ? { contactId: String(contactId) } : {}),
+      };
+      await localState.upsertCrosswalkRow(projectDir, row);
+      cache = null; // next get() re-reads; low volume, correctness over the extra stat+parse
+      return row;
+    },
+  };
+}
+
+module.exports = { createProjectMemberCrosswalk };

package/skills/wix-replatform/lib/member-outcome-registry.js

@@ -0,0 +1,265 @@
+'use strict';
+
+// Every outcome and finding code the member pass can produce, and what each one means for the
+// journal, the completion report, recovery and telemetry -- in one frozen place.
+//
+// The writer (rp-target-wix ensureMember), the contact builder (customer-member.js), the
+// projection (member-completion.js) and the tests all import these constants. A code the writer
+// can return and this file does not know is a record the report has nowhere to put, which is how
+// a customer finishes a migration without a login and nothing says so. Same rule as
+// payments-outcome-registry.js: both sides import one list, so neither can drift from the other.
+
+// Primary outcomes: exactly one per customer handed to the member pass. They partition the
+// population, so a new reason belongs HERE rather than folded into an existing bucket.
+const MEMBER_OUTCOME = Object.freeze({
+  WRITTEN: 'member-written',
+  RECONCILED_EXISTING: 'member-reconciled-existing',
+  NOT_WRITTEN_NO_EMAIL: 'member-not-written-no-email',
+  RECONCILIATION_AMBIGUOUS: 'member-reconciliation-ambiguous',
+  TARGET_READ_FAILED: 'member-target-read-failed',
+  ALREADY_EXISTS_UNRECONCILED: 'member-already-exists-unreconciled',
+  FAILED: 'member-failed',
+});
+const MEMBER_OUTCOMES = Object.freeze(Object.values(MEMBER_OUTCOME));
+
+// Supplemental findings: zero or more per customer. They never change the primary outcome.
+const MEMBER_FINDING = Object.freeze({
+  PHONE_NOT_NORMALIZED: 'member-phone-not-normalized',
+  PHONE_COLLISION_DROPPED: 'member-phone-collision-dropped',
+  CREATE_RETRIED: 'member-create-retried-after-transient-error',
+  CROSSWALK_ROW_STALE: 'member-crosswalk-row-stale',
+});
+const MEMBER_FINDINGS = Object.freeze(Object.values(MEMBER_FINDING));
+
+// Where the member pass's journal rows live and what they are called. The projection folds only
+// rows carrying both, so a customer key another entity also uses cannot bleed into the members row.
+const MEMBER_TARGET_ENTITY_TYPE = 'members/member';
+const MEMBER_OPERATION = 'ensure-member';
+const MEMBER_ENTITY = 'members';
+
+// The completion buckets a class can land in (the completion partition plus the unresolved counter).
+const PROJECTION = Object.freeze({
+  IMPORTED: 'imported',
+  ALREADY_PRESENT: 'alreadyPresentByCrosswalk',
+  DEFERRED: 'deferred',
+  FAILED: 'failed',
+  UNRESOLVED: 'unresolved',
+});
+
+// A primary outcome splits into a policy CLASS when one outcome code needs two treatments: a
+// reconciliation by crosswalk versus by login email, and a member-failed that was definitely
+// rejected versus one whose result is unknown. Each class has exactly one row.
+const POLICY = Object.freeze({
+  written: Object.freeze({
+    outcome: MEMBER_OUTCOME.WRITTEN,
+    journalStatus: 'imported',
+    failureOutcome: null,
+    projection: PROJECTION.IMPORTED,
+    nextAction: null,
+    selection: null,
+    telemetry: null,
+  }),
+  'reconciled-crosswalk': Object.freeze({
+    outcome: MEMBER_OUTCOME.RECONCILED_EXISTING,
+    matchedBy: 'crosswalk',
+    journalStatus: 'skipped_already_imported',
+    failureOutcome: null,
+    projection: PROJECTION.ALREADY_PRESENT,
+    nextAction: null,
+    selection: null,
+    telemetry: null,
+  }),
+  'reconciled-login-email': Object.freeze({
+    outcome: MEMBER_OUTCOME.RECONCILED_EXISTING,
+    matchedBy: 'loginEmail',
+    journalStatus: 'imported',
+    failureOutcome: null,
+    projection: PROJECTION.IMPORTED,
+    reasonLine: 'adopted existing member by login email',
+    nextAction: null,
+    selection: null,
+    telemetry: null,
+  }),
+  'no-email': Object.freeze({
+    outcome: MEMBER_OUTCOME.NOT_WRITTEN_NO_EMAIL,
+    journalStatus: 'deferred',
+    failureOutcome: null,
+    projection: PROJECTION.DEFERRED,
+    nextAction: 'add the email at source, then re-run with --deferred-only',
+    selection: 'deferred-only',
+    telemetry: Object.freeze({ event_type: 'fidelity_loss', subtype: 'no_target', severity: 'degraded' }),
+  }),
+  ambiguous: Object.freeze({
+    outcome: MEMBER_OUTCOME.RECONCILIATION_AMBIGUOUS,
+    journalStatus: 'deferred',
+    failureOutcome: null,
+    projection: PROJECTION.DEFERRED,
+    nextAction: 'record the chosen member id as the crosswalk row, then re-run with --deferred-only',
+    selection: 'deferred-only',
+    telemetry: Object.freeze({ event_type: 'manual_action_required', subtype: 'other', severity: 'degraded' }),
+  }),
+  'target-read-failed': Object.freeze({
+    outcome: MEMBER_OUTCOME.TARGET_READ_FAILED,
+    journalStatus: 'failed_retryable',
+    failureOutcome: 'failed_retryable',
+    projection: PROJECTION.FAILED,
+    nextAction: 're-run with --failed-only; nothing was written',
+    selection: 'failed-only',
+    telemetry: Object.freeze({ event_type: 'error', subtype: null, severity: 'degraded' }),
+  }),
+  'already-exists-unreconciled': Object.freeze({
+    outcome: MEMBER_OUTCOME.ALREADY_EXISTS_UNRECONCILED,
+    journalStatus: 'succeeded_unverified',
+    failureOutcome: 'unresolved',
+    projection: PROJECTION.UNRESOLVED,
+    nextAction: 're-run with --unresolved-only: reads the member back by login email',
+    selection: 'unresolved-only',
+    telemetry: Object.freeze({ event_type: 'error', subtype: null, severity: 'degraded' }),
+  }),
+  'failed-unknown': Object.freeze({
+    outcome: MEMBER_OUTCOME.FAILED,
+    journalStatus: 'succeeded_unverified',
+    failureOutcome: 'unresolved',
+    projection: PROJECTION.UNRESOLVED,
+    nextAction: 're-run with --unresolved-only: reads the member back by login email',
+    selection: 'unresolved-only',
+    telemetry: Object.freeze({ event_type: 'error', subtype: null, severity: 'degraded' }),
+  }),
+  'failed-rejected': Object.freeze({
+    outcome: MEMBER_OUTCOME.FAILED,
+    journalStatus: 'failed_terminal',
+    failureOutcome: 'failed_terminal',
+    projection: PROJECTION.FAILED,
+    nextAction: 'fix the source value, then re-run with --failed-only',
+    selection: 'failed-only',
+    telemetry: Object.freeze({ event_type: 'error', subtype: null, severity: 'degraded' }),
+  }),
+});
+const POLICY_CLASSES = Object.freeze(Object.keys(POLICY));
+
+// Supplemental finding policy. `droppedField` findings become a dropped-field line and a
+// fidelity_loss event ONLY on a member that was actually written: no contact was sent otherwise.
+const FINDING_POLICY = Object.freeze({
+  [MEMBER_FINDING.PHONE_NOT_NORMALIZED]: Object.freeze({ droppedField: 'contact.phones' }),
+  [MEMBER_FINDING.PHONE_COLLISION_DROPPED]: Object.freeze({ droppedField: 'contact.phones' }),
+  [MEMBER_FINDING.CREATE_RETRIED]: Object.freeze({ droppedField: null }),
+  [MEMBER_FINDING.CROSSWALK_ROW_STALE]: Object.freeze({ droppedField: null }),
+});
+
+// Pre-write population gate defects. Any one stops the whole pass before its first write.
+const POPULATION_DEFECT = Object.freeze({
+  MISSING_SOURCE_KEY: 'missing-source-key',
+  DUPLICATE_SOURCE_KEY: 'duplicate-source-key',
+  UNKNOWN_SOURCE_KEY: 'unknown-source-key',
+});
+
+const OPERATOR_ACTION_AMBIGUOUS = Object.freeze({
+  code: MEMBER_OUTCOME.RECONCILIATION_AMBIGUOUS,
+  severity: 'medium',
+  action: 'For each listed customer, choose which existing Wix member is theirs, record that member id as the customer\'s crosswalk row, then re-run the member pass with --deferred-only.',
+  deadlineReason: 'orders for these customers import without a member link until each is resolved',
+});
+
+function isMemberOutcome(code) {
+  return MEMBER_OUTCOMES.includes(code);
+}
+
+function isMemberFinding(code) {
+  return MEMBER_FINDINGS.includes(code);
+}
+
+// A member-failed whose result nobody knows: the target may or may not hold the member.
+// Unknown = the client said so, no status arrived (transport), a 5xx survived the retry, or a
+// 2xx came back without a member id. A readable 4xx is the target's own decision.
+function memberFailureOutcomeUnknown(error) {
+  if (!error || typeof error !== 'object') return true;
+  if (error.outcomeKnown === false) return true;
+  const status = error.status;
+  if (status === null || status === undefined) return true;
+  const n = Number(status);
+  if (!Number.isFinite(n)) return true;
+  return !(n >= 400 && n < 500);
+}
+
+// The one place a writer result turns into a policy class. Throws on a code the registry does
+// not know: silently bucketing it is the defect this file exists to stop.
+function classifyMemberResult(result) {
+  const outcome = result && result.outcome;
+  switch (outcome) {
+    case MEMBER_OUTCOME.WRITTEN: return 'written';
+    case MEMBER_OUTCOME.RECONCILED_EXISTING:
+      if (result.matchedBy === 'crosswalk') return 'reconciled-crosswalk';
+      if (result.matchedBy === 'loginEmail') return 'reconciled-login-email';
+      throw new Error(`member-reconciled-existing needs matchedBy crosswalk or loginEmail, got ${JSON.stringify(result.matchedBy)}`);
+    case MEMBER_OUTCOME.NOT_WRITTEN_NO_EMAIL: return 'no-email';
+    case MEMBER_OUTCOME.RECONCILIATION_AMBIGUOUS: return 'ambiguous';
+    case MEMBER_OUTCOME.TARGET_READ_FAILED: return 'target-read-failed';
+    case MEMBER_OUTCOME.ALREADY_EXISTS_UNRECONCILED: return 'already-exists-unreconciled';
+    case MEMBER_OUTCOME.FAILED: return memberFailureOutcomeUnknown(result.error) ? 'failed-unknown' : 'failed-rejected';
+    default:
+      throw new Error(`unknown member outcome: ${JSON.stringify(outcome)}`);
+  }
+}
+
+// Error-code derivation. Applied to the final error and to the first error of a retry.
+// Always a non-empty token of at most 48 characters with no whitespace, so it can be a
+// telemetry error_code as-is. Nothing is parsed out of a message.
+const ERROR_CODE_MAX = 48;
+function sanitizeCode(value) {
+  const token = String(value).trim().replace(/\s+/g, '_').slice(0, ERROR_CODE_MAX);
+  return token || null;
+}
+
+function deriveMemberErrorCode(error) {
+  const e = error && typeof error === 'object' ? error : {};
+  if (e.createReturnedNoId === true) return 'create-returned-no-id';
+  if (e.applicationErrorCode !== undefined && e.applicationErrorCode !== null && e.applicationErrorCode !== '') {
+    const code = sanitizeCode(e.applicationErrorCode);
+    if (code) return code;
+  }
+  const status = e.status === undefined || e.status === null ? null : Number(e.status);
+  if (status !== null && Number.isFinite(status) && status >= 400) return String(status);
+  if (status !== null && Number.isFinite(status) && status >= 200 && status < 300 && e.outcomeKnown === false) {
+    return 'unparseable-2xx-response';
+  }
+  if (status === null || !Number.isFinite(status)) return 'transport-error';
+  // A status below 400 with no other marker: the reply arrived and did not carry a member.
+  return 'create-returned-no-id';
+}
+
+// Written/skipped tally, the shape the coupon and plan tallies share. Delegated here so the
+// buckets come from the policy table rather than a hand-kept list of "written" codes.
+function tallyMemberOutcomes(outcomes = []) {
+  const written = new Set([MEMBER_OUTCOME.WRITTEN, MEMBER_OUTCOME.RECONCILED_EXISTING]);
+  const skippedBy = {};
+  let writtenCount = 0;
+  for (const code of outcomes) {
+    if (!isMemberOutcome(code)) throw new Error(`unknown member outcome: ${JSON.stringify(code)}`);
+    if (written.has(code)) { writtenCount += 1; continue; }
+    skippedBy[code] = (skippedBy[code] || 0) + 1;
+  }
+  return { 'members-written': writtenCount, 'members-skipped': outcomes.length - writtenCount, skippedBy };
+}
+
+module.exports = {
+  MEMBER_OUTCOME,
+  MEMBER_OUTCOMES,
+  MEMBER_FINDING,
+  MEMBER_FINDINGS,
+  MEMBER_TARGET_ENTITY_TYPE,
+  MEMBER_OPERATION,
+  MEMBER_ENTITY,
+  PROJECTION,
+  POLICY,
+  POLICY_CLASSES,
+  FINDING_POLICY,
+  POPULATION_DEFECT,
+  OPERATOR_ACTION_AMBIGUOUS,
+  ERROR_CODE_MAX,
+  isMemberOutcome,
+  isMemberFinding,
+  memberFailureOutcomeUnknown,
+  classifyMemberResult,
+  deriveMemberErrorCode,
+  tallyMemberOutcomes,
+};

package/skills/wix-replatform/lib/migration-completion.js

@@ -0,0 +1,311 @@
+'use strict';
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+
+const { POST_EXECUTION_HANDOFF_JSON, loadPostExecutionHandoff, readEntityMappings } = require('./website-handoff.js');
+const { executionLogExists, EXECUTION_LOG_FILE } = require('./execution-log.js');
+const { hashArtifact } = require('./artifact-freshness.js');
+const { STATUS_FILE, discoveredSetStatusFreshness, deriveFinalStatus, inputDigests, checkResolutionPrefix } = require('./discovered-set-status.js');
+const { ENTITY_QA_ATTESTATION_FILE, validateEntityQaAttestation } = require('./entity-qa-attestation.js');
+
+const COMPLETION_FILE = 'completion/migration-completion.json';
+const FRONTEND_COMPLETION_FILE = 'website/completion.json';
+const BACKEND_COMPLETION_FILE = 'execution/completion-report.json';
+const MAPPING_PLAN_FILE = 'mapping/mapping-plan.json';
+const QUICK_MODE_PLAN_FILE = 'quick-mode/plan.json';
+const COMPLETE_STATUSES = new Set(['complete', 'complete_with_warnings']);
+const BACKEND_COMPLETE_STATUSES = new Set([
+  'complete',
+  'complete_with_warnings',
+  'complete_with_recovered_records',
+  'complete_with_deferred_records',
+]);
+
+async function readJsonIfExists(filePath) {
+  try {
+    return JSON.parse(await fs.readFile(filePath, 'utf8'));
+  } catch (error) {
+    if (error && error.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+// A parse failure on the entity-QA attestation (or on the independent mapped-entity
+// source used to judge its coverage) must resolve exactly like a missing file -- never a thrown
+// error that aborts finalization checking outright. This mirrors `orchestration-router.js`'s own
+// `readJson` helper; it is intentionally NOT `readJsonIfExists` above, whose re-throw-on-parse-
+// -failure behavior for every other artifact it already loads is unchanged.
+async function readJsonTolerant(filePath) {
+  try {
+    return JSON.parse(await fs.readFile(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+// The independent coverage source `validateEntityQaAttestation` checks attestation coverage
+// against -- never the completion report's own (possibly incomplete) `entityCompleteness[]`.
+// Full mode: the entity rows of `mapping/mapping-plan.json`, read the same way
+// `website-handoff.js`'s `readEntityMappings` already does. Quick mode: the `entities` array of
+// `quick-mode/plan.json`, written at plan time before extraction or import ever runs.
+async function readMappedEntities(projectDir, managementImportMode) {
+  if (managementImportMode === 'quick') {
+    const quickPlan = await readJsonTolerant(path.join(projectDir, QUICK_MODE_PLAN_FILE));
+    return Array.isArray(quickPlan && quickPlan.entities) ? quickPlan.entities : [];
+  }
+  const mappingPlan = await readJsonTolerant(path.join(projectDir, MAPPING_PLAN_FILE));
+  return readEntityMappings(mappingPlan);
+}
+
+// This compatibility receipt test deliberately uses only the original receipt fields.
+// Later finalization requirements cannot prove that a legacy run really finished.
+async function classifyFinalizedRun(projectDir, { decisions = {} } = {}) {
+  const { getDecisionValue } = require('./orchestration-decisions.js');
+  const receiptPath = path.join(projectDir, COMPLETION_FILE);
+  try { await fs.access(receiptPath); } catch (error) { if (error.code === 'ENOENT') return { kind: 'none', errors: [] }; throw error; }
+  const [receipt, report] = await Promise.all([readJsonTolerant(receiptPath), readJsonTolerant(path.join(projectDir, BACKEND_COMPLETION_FILE))]);
+  if (receipt?.schemaVersion === 2) return { kind: 'current', errors: [] };
+  const quick = getDecisionValue(decisions, 'managementImportMode') === 'quick';
+  const reportIsObject = report && typeof report === 'object' && !Array.isArray(report);
+  if ((quick && (!reportIsObject || report.managementImportMode !== 'quick')) || (!quick && report?.managementImportMode === 'quick')) return { kind: 'unverified-v1', reason: 'completion_mode_mismatch', errors: ['completion_mode_mismatch'] };
+  const errors = [];
+  const object = receipt && typeof receipt === 'object' && !Array.isArray(receipt);
+  if (!object || receipt.schemaVersion !== 1) errors.push('schemaVersion');
+  if (!object || !BACKEND_COMPLETE_STATUSES.has(receipt.status)) errors.push('status');
+  if (typeof receipt?.finalizedAt !== 'string' || !Number.isFinite(Date.parse(receipt.finalizedAt))) errors.push('finalizedAt');
+  const mode = getDecisionValue(decisions, 'deliveryMode');
+  if (!['management','management_and_website'].includes(mode) || receipt?.deliveryMode !== mode) errors.push('deliveryMode');
+  if (receipt?.backendCompletion !== BACKEND_COMPLETION_FILE) errors.push('backendCompletion');
+  if (mode === 'management_and_website') {
+    if (receipt?.frontendCompletion !== FRONTEND_COMPLETION_FILE || typeof receipt?.handoffFingerprint !== 'string' || !receipt.handoffFingerprint.trim()) errors.push('websiteBinding');
+  } else if (receipt?.frontendCompletion !== null || receipt?.handoffFingerprint !== null) errors.push('websiteBinding');
+  if (!reportIsObject || !BACKEND_COMPLETE_STATUSES.has(report.status) || receipt?.status !== report.status) errors.push('completionReport.status');
+  if (report?.lastWriteAt && (!Number.isFinite(Date.parse(report.lastWriteAt)) || Date.parse(receipt?.finalizedAt) <= Date.parse(report.lastWriteAt))) errors.push('completionReport.lastWriteAt');
+  if (errors.length) return { kind: 'unverified-v1', reason: quick ? 'quick_receipt_unverified' : 'finalized_receipt_unverified', errors: quick ? ['quick_receipt_unverified', ...errors] : errors };
+  return { kind: quick ? 'quick' : 'valid-v1', errors: [] };
+}
+
+function validateFrontendCompletion(receipt, handoff, { requireHandoff = true } = {}) {
+  if (!receipt || typeof receipt !== 'object') {
+    return { ok: false, reason: 'frontend_completion_missing' };
+  }
+  if (receipt.schemaVersion !== 1) {
+    return { ok: false, reason: 'frontend_completion_schema_invalid' };
+  }
+  if (!COMPLETE_STATUSES.has(receipt.status)) {
+    return { ok: false, reason: receipt.status === 'blocked' ? 'frontend_blocked' : 'frontend_completion_incomplete', receipt };
+  }
+  if (requireHandoff && (!handoff || !handoff.handoffFingerprint || receipt.handoffFingerprint !== handoff.handoffFingerprint)) {
+    return { ok: false, reason: 'frontend_completion_stale', receipt };
+  }
+  const gapAnalysis = receipt.gapAnalysis;
+  if (!gapAnalysis || gapAnalysis.screenshotReview !== 'complete'
+    || gapAnalysis.unresolvedCritical !== 0 || gapAnalysis.unresolvedHigh !== 0) {
+    return { ok: false, reason: 'frontend_gap_analysis_incomplete', receipt };
+  }
+  if (!receipt.release || !['released', 'not_applicable'].includes(receipt.release.status)) {
+    return { ok: false, reason: 'frontend_release_incomplete', receipt };
+  }
+  return { ok: true, receipt };
+}
+
+// "done" requires all four artifacts, and a requirement nothing checks is how three
+// of them came to have no writer. Both delivery modes now need the post-execution handoff and the
+// execution log -- `management` previously required no handoff at all, which is why a
+// backend-only run could finalize with no account of the migration anywhere in the project.
+function validateCompletionArtifacts({ postExecutionHandoff, executionLogPresent, backendCompletion }) {
+  if (!executionLogPresent) {
+    return { ok: false, reason: 'missing_execution_log' };
+  }
+  if (!postExecutionHandoff || typeof postExecutionHandoff !== 'object') {
+    return { ok: false, reason: 'missing_post_execution_handoff' };
+  }
+  const lastWriteAt = backendCompletion && backendCompletion.lastWriteAt;
+  if (!lastWriteAt) {
+    return { ok: false, reason: 'completion_report_missing_last_write' };
+  }
+  // The generation timestamp must be later than the run's own last write. A handoff that
+  // predates the import is exactly the artifact this check exists to stop.
+  if (!postExecutionHandoff.generatedAt || Date.parse(postExecutionHandoff.generatedAt) <= Date.parse(lastWriteAt)) {
+    return { ok: false, reason: 'post_execution_handoff_predates_last_write' };
+  }
+  return { ok: true };
+}
+
+function runEntityQaGate({ backendCompletion, entityQaAttestation, mappedEntities, reportDigest }) {
+  return validateEntityQaAttestation({
+    attestation: entityQaAttestation,
+    report: backendCompletion,
+    reportDigest,
+    mappedEntities,
+  });
+}
+
+function createMigrationCompletion({
+  deliveryMode,
+  backendCompletion,
+  frontendCompletion = null,
+  handoff = null,
+  postExecutionHandoff = null,
+  executionLogPresent = false,
+  entityQaAttestation = null,
+  mappedEntities = null,
+  reportDigest = null,
+  discoveredSetStatus = null, discoveredSetFreshness = null, discoveredSetDigest = null,
+}) {
+  if (!backendCompletion || typeof backendCompletion !== 'object' || !backendCompletion.status) {
+    throw new Error('backend completion report is required');
+  }
+  if (!BACKEND_COMPLETE_STATUSES.has(backendCompletion.status)) {
+    throw new Error(`backend completion is not successful: ${backendCompletion.status}`);
+  }
+  if (!['management', 'management_and_website'].includes(deliveryMode)) {
+    throw new Error('aggregate migration completion requires management or management_and_website deliveryMode');
+  }
+  const artifacts = validateCompletionArtifacts({ postExecutionHandoff, executionLogPresent, backendCompletion });
+  if (!artifacts.ok) throw new Error(`migration cannot complete: ${artifacts.reason}`);
+  const quick = backendCompletion.managementImportMode === 'quick';
+  if (!quick) {
+    if (!discoveredSetStatus) throw Object.assign(new Error('missing_discovered_set_status'), { code: 'missing_discovered_set_status' });
+    if (!discoveredSetFreshness?.ok) throw Object.assign(new Error('discovered_set_status_stale'), { code: 'discovered_set_status_stale', staleInputs: discoveredSetFreshness?.staleInputs || [] });
+    if (discoveredSetStatus.inputs?.completionReport !== reportDigest) throw Object.assign(new Error('discovered_set_status_stale'), { code: 'discovered_set_status_stale', staleInputs: ['completionReport'] });
+    if (!discoveredSetDigest || postExecutionHandoff?.discoveredSet?.sha256 !== discoveredSetDigest) throw Object.assign(new Error('handoff_discovered_set_stale'), { code: 'handoff_discovered_set_stale' });
+  }
+  const finalStatus = deriveFinalStatus(backendCompletion.status, quick ? null : discoveredSetStatus);
+  if (postExecutionHandoff?.status !== finalStatus) throw Object.assign(new Error('handoff_status_mismatch'), { code: 'handoff_status_mismatch' });
+  if (deliveryMode === 'management_and_website') {
+    const validation = validateFrontendCompletion(frontendCompletion, handoff);
+    if (!validation.ok) throw new Error(`website migration cannot complete: ${validation.reason}`);
+  }
+  // A run is not allowed to finish without a fresh, complete
+  // entity-QA attestation. Missing, stale or failed refuses the same as any other
+  // artifact gap above -- it is not a new kind of failure, just one more required artifact.
+  const entityQa = runEntityQaGate({ backendCompletion, entityQaAttestation, mappedEntities, reportDigest });
+  if (!entityQa.ok) throw new Error(`migration cannot complete: ${entityQa.reasons[0]}`);
+  return {
+    schemaVersion: 2,
+    status: finalStatus,
+    backendStatus: backendCompletion.status,
+    discoveredSet: quick ? null : { path: STATUS_FILE, sha256: discoveredSetDigest, openCount: discoveredSetStatus.openCount, inputs: discoveredSetStatus.inputs },
+    deliveryMode,
+    backendCompletion: BACKEND_COMPLETION_FILE,
+    frontendCompletion: deliveryMode === 'management_and_website' ? FRONTEND_COMPLETION_FILE : null,
+    handoffFingerprint: deliveryMode === 'management_and_website' ? handoff.handoffFingerprint : null,
+    postExecutionHandoff: POST_EXECUTION_HANDOFF_JSON,
+    executionLog: EXECUTION_LOG_FILE,
+    // `scope` says what was attested: import rows only. Not business setup, not launch
+    // readiness. A hollow attestation that copies the report can still pass; the gate proves
+    // freshness and coverage only.
+    entityQaAttestation: {
+      path: ENTITY_QA_ATTESTATION_FILE,
+      completionReportDigest: entityQaAttestation.completionReportDigest,
+      verifiedAt: entityQaAttestation.verifiedAt,
+      scope: 'import-entity-coverage',
+    },
+    finalizedAt: new Date().toISOString(),
+  };
+}
+
+async function loadMigrationCompletionInputs(projectDir) {
+  const [backendCompletion, frontendCompletion, handoff, completion, postExecutionHandoff, executionLogPresent, entityQaAttestation] = await Promise.all([
+    readJsonIfExists(path.join(projectDir, BACKEND_COMPLETION_FILE)),
+    readJsonIfExists(path.join(projectDir, FRONTEND_COMPLETION_FILE)),
+    readJsonIfExists(path.join(projectDir, 'website', 'handoff.json')),
+    readJsonIfExists(path.join(projectDir, COMPLETION_FILE)),
+    loadPostExecutionHandoff(projectDir),
+    executionLogExists(projectDir),
+    readJsonTolerant(path.join(projectDir, ENTITY_QA_ATTESTATION_FILE)),
+  ]);
+  const managementImportMode = backendCompletion && backendCompletion.managementImportMode === 'quick' ? 'quick' : 'full';
+  const mappedEntities = await readMappedEntities(projectDir, managementImportMode);
+  const reportDigest = hashArtifact(projectDir, BACKEND_COMPLETION_FILE);
+  const discoveredSetStatus = managementImportMode === 'quick' ? null : await readJsonTolerant(path.join(projectDir, STATUS_FILE));
+  const discoveredSetFreshness = discoveredSetStatus ? await discoveredSetStatusFreshness(projectDir, discoveredSetStatus) : null;
+  const discoveredSetDigest = discoveredSetStatus ? hashArtifact(projectDir, STATUS_FILE) : null;
+  const completionDiscoveredInputs = managementImportMode === 'quick' ? null : await inputDigests(projectDir);
+  const resolutionsPrefixValid = completion?.discoveredSet?.inputs?.resolutions ? await checkResolutionPrefix(projectDir, completion.discoveredSet.inputs.resolutions) : false;
+  return {
+    discoveredSetStatus, discoveredSetFreshness, discoveredSetDigest, completionDiscoveredInputs, resolutionsPrefixValid,
+    backendCompletion,
+    frontendCompletion,
+    handoff,
+    completion,
+    postExecutionHandoff,
+    executionLogPresent,
+    entityQaAttestation,
+    mappedEntities,
+    reportDigest,
+  };
+}
+
+function validateMigrationCompletion(completion, {
+  deliveryMode, backendCompletion, frontendCompletion, handoff, postExecutionHandoff, executionLogPresent,
+  entityQaAttestation, mappedEntities, reportDigest,
+  discoveredSetStatus = null, discoveredSetFreshness = null, discoveredSetDigest = null, completionDiscoveredInputs = null, resolutionsPrefixValid = false,
+}) {
+  if (!completion || typeof completion !== 'object') return { ok: false, reason: 'migration_completion_missing' };
+  if (![1, 2].includes(completion.schemaVersion) || completion.deliveryMode !== deliveryMode) {
+    return { ok: false, reason: 'migration_completion_invalid' };
+  }
+  const quick = backendCompletion?.managementImportMode === 'quick';
+  if (!quick && completion.schemaVersion === 1) return { ok: false, reason: 'migration_completion_discovered_set_missing' };
+  if (!quick) {
+    if (!discoveredSetStatus || !completion.discoveredSet) return { ok: false, reason: 'missing_discovered_set_status' };
+    if (!resolutionsPrefixValid) return { ok: false, reason: 'discovered_set_resolutions_rewritten' };
+    if (!discoveredSetFreshness?.ok) return { ok: false, reason: 'discovered_set_status_stale', staleInputs: discoveredSetFreshness?.staleInputs || [] };
+    for (const key of ['completionReport','reconciliation','approvalsMapping']) {
+      if (!completionDiscoveredInputs || completion.discoveredSet.inputs?.[key] !== completionDiscoveredInputs[key]) return { ok: false, reason: 'discovered_set_status_stale', staleInputs: [key] };
+    }
+  }
+  // Only a verified append may lower the live open count while preserving the historical
+  // finalization. Without an append, derive status from the current report as usual.
+  const resolutionsAppended = !quick && completionDiscoveredInputs?.resolutions?.lines > completion.discoveredSet?.inputs?.resolutions?.lines;
+  if (resolutionsAppended && discoveredSetStatus.openCount > completion.discoveredSet.openCount) return { ok: false, reason: 'migration_completion_stale' };
+  const statusAtFinalization = resolutionsAppended ? { openCount: completion.discoveredSet.openCount } : discoveredSetStatus;
+  const expectedStatus = deriveFinalStatus(backendCompletion?.status, quick ? null : statusAtFinalization);
+  if (postExecutionHandoff?.status !== expectedStatus) return { ok: false, reason: 'handoff_status_mismatch' };
+  const artifacts = validateCompletionArtifacts({ postExecutionHandoff, executionLogPresent, backendCompletion });
+  if (!artifacts.ok) return artifacts;
+  if (!backendCompletion || !BACKEND_COMPLETE_STATUSES.has(backendCompletion.status) || completion.status !== expectedStatus) {
+    return { ok: false, reason: 'migration_completion_stale' };
+  }
+  if (deliveryMode === 'management_and_website') {
+    const frontend = validateFrontendCompletion(frontendCompletion, handoff);
+    if (!frontend.ok) return frontend;
+    if (completion.frontendCompletion !== FRONTEND_COMPLETION_FILE || completion.handoffFingerprint !== handoff.handoffFingerprint) {
+      return { ok: false, reason: 'migration_completion_stale' };
+    }
+  }
+  // The same existing gate call, handed the inputs it now also judges on -- not a
+  // new router branch. See `orchestration-router.js`'s `determineNextStep`.
+  const entityQa = runEntityQaGate({ backendCompletion, entityQaAttestation, mappedEntities, reportDigest });
+  if (!entityQa.ok) {
+    return {
+      ok: false,
+      reason: entityQa.reasons[0],
+      entityQa: { qaStatus: entityQa.qaStatus, entities: entityQa.entities, recheck: entityQa.recheck },
+    };
+  }
+  return { ok: true, completion };
+}
+
+module.exports = {
+  classifyFinalizedRun,
+  COMPLETION_FILE,
+  FRONTEND_COMPLETION_FILE,
+  BACKEND_COMPLETION_FILE,
+  MAPPING_PLAN_FILE,
+  QUICK_MODE_PLAN_FILE,
+  BACKEND_COMPLETE_STATUSES,
+  readJsonIfExists,
+  readJsonTolerant,
+  readMappedEntities,
+  POST_EXECUTION_HANDOFF_JSON,
+  EXECUTION_LOG_FILE,
+  validateFrontendCompletion,
+  validateCompletionArtifacts,
+  createMigrationCompletion,
+  loadMigrationCompletionInputs,
+  validateMigrationCompletion,
+};