@wix/agent-skills 1.36.0 → 1.36.1

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

@@ -1,69 +0,0 @@
-'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

@@ -1,265 +0,0 @@
-'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

@@ -1,311 +0,0 @@
-'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,
-};