Rp Target Wix

lib/order-history.js

'use strict';

// An imported order's history as ONE composite write.
//
// Four writes with an ordering constraint, a shared identity, two inputs that come from neither
// the source nor the mapping plan, and one piece of state that must outlive a crash. The first
// caller to assemble that by hand -- with the whole spec in context -- made four mistakes in an
// afternoon, and two of them were silent: a mis-named gate parameter that reported a plausible
// zero, and a missing order crosswalk that would have duplicated the store. The writers were
// right every time. So the SEQUENCE lives here, and a caller supplies facts: a mapped order body
// and the source's evidence. No ordering, no reconciliation, no gate invocation, no state.
//
// THE ORDER WRITE'S IDENTITY. LIVE-VERIFIED 2026-09-05 against a disposable site:
// Import Order ACCEPTS a
// caller-supplied `id` it has never seen and keeps it; a re-send with the same id fully replaces
// the order body; payments and extendedFields attached to the order SURVIVE the replace; a
// non-GUID id is refused with a 400. So the order id is DERIVED here from the source site and
// the source order id, which makes the order write idempotent on the target's own terms: a run
// that lost its crosswalk asks the target whether the derived id exists, and finds it. The
// crosswalk is still written -- before anything else -- but it is an accelerator and a report
// input, not the only thing standing between a crash and a duplicated store.
//
// What the probe ALSO showed, and why an existing order is never re-sent: a different order body
// with an existing id replaces it silently, and nothing distinguishes "replace mine" from
// "clobber a merchant's edits". So an order that already exists is RECONCILED (left alone) and
// its history continued, never re-imported. Search Orders is not used as an existence check: it
// read a stale number within a second of a change, and an id read is exact.

const crypto = require('node:crypto');
const fs = require('node:fs/promises');
const path = require('node:path');
const w = require('./wix-writers.js');
const paymentMapping = require('./order-payment-mapping.js');
const localState = require('../../../lib/local-state.js');
const approvalStamp = require('../../../lib/preservation-approval-stamp.js');
const orderBuyer = require('./order-buyer.js');
const customerMember = require('./customer-member.js');
const fsSync = require('node:fs');

const GUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;

// A bounded retry for the TWO writes in this file that have earned one, and nowhere else. It is
// deliberately not on the shared client: bulk coupon, contact, member, form-submission, product
// and media creation are not reconciled against the target before writing, so a failure arriving
// AFTER the target committed would be retried into a second copy -- worse than the problem.
//
// Both sites below are reconciled first, so the second attempt is demonstrably the SAME attempt:
// the order id is derived from the source and the writer refuses a caller-chosen one, and the
// payment write is preceded by a read that decides create-or-adopt.
//
// `isTransientWixError` says the condition is likely to clear; whether a retry can duplicate
// anything is this call site's question, and only these two can answer it yes.
const WRITE_RETRY_ATTEMPTS = 3;
const WRITE_RETRY_DELAYS_MS = [500, 1500];
const realSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

const ORDER_OUTCOMES = Object.freeze({
  IMPORTED: 'order-imported',
  ALREADY_IMPORTED: 'order-already-imported',
  IMPORT_FAILED: 'order-import-failed',
  TARGET_READ_FAILED: 'order-target-read-failed',
});

// The evidence contract. A key outside this list is REFUSED, not ignored: an ignored key is how
// `sourceAmount` for `amount` reported every order in a live store as never paid, with no reason.
const EVIDENCE_KEYS = Object.freeze([
  'amount', 'paidDate', 'altPaidDate', 'currency', 'status', 'distinctAmountCount', 'utcOffsetMinutes',
  'paidDateZone', 'altPaidDateZone',
  'methodName', 'providerTransactionId', 'offlinePayment', 'cardDisplay',
  'refunds', 'invoice',
]);
const REFUND_KEYS = Object.freeze(['sourceId', 'amount', 'reason']);
const INVOICE_KEYS = Object.freeze(['approval', 'sourceUrl', 'invoiceNumber', 'pendingMediaFileId']);
// Names a caller is likely to reach for, and where each actually goes.
const MISNAMED = Object.freeze({
  sourceAmount: 'amount', total: 'amount', orderTotal: 'amount',
  sourcePaidDate: 'paidDate', datePaid: 'paidDate', paid: 'paidDate',
  // The two source stamps are NOT interchangeable and must not both land on `paidDate`: the
  // `_gmt` sibling is universal by the source schema's definition of that key, the plain one is
  // the shop's wall clock. Routing both here is how one shop offset came to be applied to a
  // value that was already universal, moving the payment by the whole offset.
  date_paid_gmt: "paidDate, declared paidDateZone: 'utc'",
  date_paid: "altPaidDate, declared altPaidDateZone: 'site-local'",
  sourceCurrency: 'currency',
  targetCurrency: 'nothing here -- the target currency is read from order.currency',
  transactionId: 'providerTransactionId', transaction_id: 'providerTransactionId', reference: 'providerTransactionId',
  method: 'methodName', paymentMethod: 'methodName', payment_method: 'methodName', payment_method_title: 'methodName',
  sourceStatus: 'status',
  refund: 'refunds (an array)', invoices: 'invoice (one document per order)',
});

function isPlainObject(value) {
  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
}

function assertKeys(object, allowed, label) {
  if (!isPlainObject(object)) throw new Error(`${label} must be an object, got ${JSON.stringify(object)}`);
  const unknown = Object.keys(object).filter((key) => !allowed.includes(key));
  if (unknown.length === 0) return;
  const hints = unknown.map((key) => (MISNAMED[key] ? `${key} (this contract calls it ${MISNAMED[key]})` : key));
  throw new Error(
    `${label} carries keys this contract does not read: ${hints.join(', ')}. Accepted: ${allowed.join(', ')}. `
    + 'Unknown keys are refused rather than ignored, because an ignored key reads exactly like a source that evidences nothing.',
  );
}

// Known keys with malformed VALUES are as silent as unknown keys: `offlinePayment: "false"` was
// dropped rather than read, a scalar `cardDisplay` lost the card evidence, and
// `distinctAmountCount: "unknown"` became NaN, which is "not more than one", which let a
// multi-payment order through the gate. Each is refused with the key and the value it got.
const EVIDENCE_TYPES = Object.freeze({
  amount: (v) => typeof v === 'string' || (typeof v === 'number' && Number.isFinite(v)),
  paidDate: (v) => typeof v === 'string',
  altPaidDate: (v) => typeof v === 'string',
  currency: (v) => typeof v === 'string',
  status: (v) => typeof v === 'string',
  distinctAmountCount: (v) => Number.isInteger(v) && v >= 1,
  // UTC-14 to UTC+14 is every offset that exists; 999999 accepted here moved a payment two years.
  utcOffsetMinutes: (v) => Number.isInteger(v) && v >= -840 && v <= 840,
  // A clock is a two-member enumeration, refused rather than coerced: 'UTC', true and 0 each
  // read exactly like a correctly-declared clock once coerced, and would restore the defect
  // these keys exist to remove -- silently, on a financial value.
  paidDateZone: (v) => v === 'utc' || v === 'site-local',
  altPaidDateZone: (v) => v === 'utc' || v === 'site-local',
  methodName: (v) => typeof v === 'string',
  providerTransactionId: (v) => typeof v === 'string',
  offlinePayment: (v) => typeof v === 'boolean',
  cardDisplay: (v) => isPlainObject(v)
    && Object.keys(v).every((k) => k === 'lastFourDigits' || k === 'brand')
    && Object.values(v).every((x) => x === null || x === undefined || typeof x === 'string'),
});
const EVIDENCE_TYPE_HINTS = Object.freeze({
  amount: 'a decimal string or finite number',
  paidDate: 'an ISO date-time string', altPaidDate: 'an ISO date-time string',
  currency: 'an ISO 4217 code string', status: 'a string',
  distinctAmountCount: 'a positive integer', utcOffsetMinutes: 'an integer between -840 and 840',
  paidDateZone: "'utc' or 'site-local'", altPaidDateZone: "'utc' or 'site-local'",
  methodName: 'a string', providerTransactionId: 'a string',
  offlinePayment: 'a real boolean (not the string "false")',
  cardDisplay: 'an object { lastFourDigits?, brand? } of strings',
});

function assertEvidence(evidence, { sourceId = null } = {}) {
  assertKeys(evidence, EVIDENCE_KEYS, 'evidence');
  // Internal: the source id the approval must name. Not a contract key -- set on a shallow copy.
  evidence = { ...evidence, __sourceId: sourceId };
  for (const [key, accepts] of Object.entries(EVIDENCE_TYPES)) {
    const value = evidence[key];
    if (value === undefined || value === null) continue;
    if (!accepts(value)) {
      throw new Error(`evidence.${key} must be ${EVIDENCE_TYPE_HINTS[key]}, got ${JSON.stringify(value)}`);
    }
  }
  // Cross-key: a shop offset supplied beside a stamp whose clock nobody stated. Knowing the shop's
  // offset is exactly the case where getting the clock wrong moves the money -- the offset is
  // applied, so a stamp that was already universal lands hours out. The 'site-local' default exists
  // to leave callers that never knew the offset untouched; it is not allowed to cover this shape.
  // Per PRESENT stamp, not once per record: declaring one clock and leaving the other on the
  // default reads as though the caller had been updated while still exposing a stamp the offset can
  // move. Deliberately NOT widened to "offset present => declaration required": an unpaid order in
  // a shop whose offset the run happens to know has no stamp to misapply it to.
  if (evidence.utcOffsetMinutes !== undefined && evidence.utcOffsetMinutes !== null) {
    for (const [stamp, zoneKey] of [['paidDate', 'paidDateZone'], ['altPaidDate', 'altPaidDateZone']]) {
      if (evidence[stamp] === undefined || evidence[stamp] === null) continue;
      if (evidence[zoneKey] !== undefined && evidence[zoneKey] !== null) continue;
      throw new Error(
        `evidence.${stamp} needs ${zoneKey} ('utc' or 'site-local') when utcOffsetMinutes is supplied; `
        + 'without it the offset may be applied to a stamp that is already universal',
      );
    }
  }
  if (evidence.refunds !== undefined) {
    if (!Array.isArray(evidence.refunds)) throw new Error('evidence.refunds must be an array (one entry per source refund)');
    evidence.refunds.forEach((refund, index) => {
      assertKeys(refund, REFUND_KEYS, `evidence.refunds[${index}]`);
      if (refund.sourceId === undefined || refund.sourceId === null || String(refund.sourceId).trim() === '') {
        throw new Error(`evidence.refunds[${index}] needs a sourceId; occurrence numbers are assigned by it and a re-run recognizes its own refunds through it`);
      }
      // A refund with no positive amount would reach Refund Payments as `amount: "undefined"` --
      // after the payment create it hangs off. Refused here, before any target call.
      const amount = paymentMapping.canonicalizeDecimal(refund.amount);
      if (amount === null || !(Number(amount) > 0)) {
        throw new Error(`evidence.refunds[${index}] needs a positive amount, got ${JSON.stringify(refund.amount)}`);
      }
    });
  }
  if (evidence.invoice !== undefined && evidence.invoice !== null) {
    const invoice = evidence.invoice;
    assertKeys(invoice, INVOICE_KEYS, 'evidence.invoice');
    // The approval must be the PLANNER's. The writer only insists on the stamp where an opt-in is
    // relied on; this composite insists everywhere, because a hand-built reference-only approval
    // with an object for a number wrote "[object Object]" onto an order in review. The plan is the
    // one producer, and it stamps everything it issues.
    if (!isPlainObject(invoice.approval) || !approvalStamp.verifyApprovalStamp(invoice.approval)) {
      throw new Error('evidence.invoice.approval must be an approval issued by resolvePreservationPlan() (it carries the plan\'s stamp); pass the plan\'s object, do not rebuild it');
    }
    // The planner's approvals name their order, and the stamp covers that name. One handed over
    // for a different source order would preserve somebody else's document onto this one (review
    // demonstrated it), and one with the order DELETED after stamping would fit any order (review
    // demonstrated that too) -- so the order is required, not merely compared when present.
    if (invoice.approval.orderId === undefined || invoice.approval.orderId === null || String(invoice.approval.orderId).trim() === '') {
      throw new Error('evidence.invoice.approval names no source order (orderId); resolvePreservationPlan() issues approvals per order, and one without an order could be handed to any');
    }
    if (String(invoice.approval.orderId) !== String(evidence.__sourceId)) {
      throw new Error(`evidence.invoice.approval is for source order ${invoice.approval.orderId}, not ${evidence.__sourceId}`);
    }
    const optional = (key, accepts, hint) => {
      const v = invoice[key];
      if (v === undefined || v === null) return;
      if (!accepts(v)) throw new Error(`evidence.invoice.${key} must be ${hint}, got ${JSON.stringify(v)}`);
    };
    optional('sourceUrl', (v) => typeof v === 'string', 'a URL string');
    optional('invoiceNumber', (v) => typeof v === 'string' || typeof v === 'number', 'a string or number');
    optional('pendingMediaFileId', (v) => typeof v === 'string' && v.trim() !== '', 'a Media file id string');
  }
}

// A stable GUID for a source order on this target. Version-5 style: a SHA-1 over a namespaced
// name with the version and variant bits set, which is what Import Order accepted live. The
// source SITE is part of the name so two stores importing "order 1042" into one Wix site cannot
// collide -- and so a migration re-run from the same store converges on the same order.
// `shop.example`, `https://shop.example/`, `SHOP.EXAMPLE:443` and `shop.example/wp` are one site.
// Four spellings deriving four ids would re-import a store the day a config string gained a
// scheme, so the host is normalized to its bare lowercase hostname (a non-default port is kept).
function normalizeSourceSiteHost(sourceSiteHost) {
  let text = String(sourceSiteHost === undefined || sourceSiteHost === null ? '' : sourceSiteHost).trim().toLowerCase();
  if (!text) return '';
  if (!/^[a-z][a-z0-9+.-]*:\/\//.test(text)) text = `https://${text}`;
  let url;
  try { url = new URL(text); } catch (error) { return ''; }
  return url.port && url.port !== '443' ? `${url.hostname}:${url.port}` : url.hostname;
}

function deriveImportedOrderId({ sourceSiteHost, sourceId } = {}) {
  const host = normalizeSourceSiteHost(sourceSiteHost);
  const id = sourceId === undefined || sourceId === null ? '' : String(sourceId).trim();
  if (!host) throw new Error('deriveImportedOrderId needs sourceSiteHost (a hostname, or a URL it can be read from): the id is namespaced by the source site');
  if (!id) throw new Error('deriveImportedOrderId needs the source order id');
  const hash = crypto.createHash('sha1').update(`replatform:ecom:order:${host}:${id}`).digest();
  hash[6] = (hash[6] & 0x0f) | 0x50;
  hash[8] = (hash[8] & 0x3f) | 0x80;
  const hex = hash.toString('hex');
  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
}

// Same rule as rp-source-wordpress's assignRefundOccurrences, kept target-side so this module does
// not depend on a source adapter: two source refunds of equal amount on one order are the first
// and second OCCURRENCE of that amount, ordered by source id, and reconcile as such. Pass ALL of an
// order's refunds in one call -- occurrences are relative to the list.
function withOccurrences(refunds) {
  const seen = new Map();
  return [...refunds]
    .sort((a, b) => String(a.sourceId).localeCompare(String(b.sourceId)))
    .map((refund) => {
      const key = paymentMapping.canonicalizeDecimal(refund.amount) || String(refund.amount);
      const occurrence = (seen.get(key) || 0) + 1;
      seen.set(key, occurrence);
      return { ...refund, sourceOccurrence: occurrence };
    });
}

function describeError(error) {
  return {
    message: String((error && error.message) || error).slice(0, 300),
    ...(error && error.status ? { status: error.status } : {}),
    // Conditional, like the rest: an unknown outcome is the exceptional case, and making this
    // unconditional would change the shape of every row already written to a results ledger.
    // Without it, the rejected-vs-unknown distinction is lost the moment it is recorded.
    ...(error && error.outcomeKnown === false ? { outcomeKnown: false } : {}),
    ...(error && error.applicationErrorCode ? { applicationErrorCode: error.applicationErrorCode } : {}),
    // A refusal before the network (readiness, raw-request guard) wrote nothing; kept so the
    // journal row can say retryable rather than guess from a missing status.
    ...(error && error.requestSent === false ? { requestSent: false } : {}),
    ...(error && typeof error.code === 'string' && error.code ? { code: error.code } : {}),
  };
}

function assertCrosswalk(crosswalk) {
  const has = (name) => crosswalk && typeof crosswalk[name] === 'function';
  if (!has('get') || !has('set') || !has('getInvoiceFile') || !has('setInvoiceFile')) {
    throw new Error(
      'importOrderHistory needs a persisted crosswalk with get(sourceId), set(sourceId, orderId), '
      + 'getInvoiceFile(sourceId) and setInvoiceFile(sourceId, fileId). It is not optional: a run that '
      + 'forgets it re-imports the store, and one that forgets the invoice file imports a second copy of a '
      + 'tax document. createProjectOrderCrosswalk({ projectDir }) provides all four over state/crosswalk/.',
    );
  }
}

// Fill every remaining stage with a named outcome once the order stage has failed. Nothing else
// is attempted: with no order there is nothing to attach a payment or a document to, and a payment
// that was never attempted because of an import failure is a FAILURE, not an ineligibility.
function failRemaining(outcomes, errors, { gate, refunds, evidence, cause }) {
  outcomes.payment = gate.eligible ? 'payment-failed' : gate.outcome;
  if (gate.eligible) errors.payment = { cause };
  outcomes.refunds = refunds.map((refund) => ({
    sourceId: refund.sourceId,
    sourceOccurrence: refund.sourceOccurrence,
    outcome: gate.eligible ? 'refund-failed' : 'refund-without-payment',
    ...(gate.eligible ? { error: { cause } } : {}),
  }));
  outcomes.invoice = evidence.invoice ? 'invoice-failed' : 'invoice-none-found';
  if (evidence.invoice) errors.invoice = { cause };
}

// ---- contact fields --------------------------
// A source email or phone Import Order refuses fails the WHOLE order. The policy: a
// contact detail is removed only when Import Order's own rejection NAMES that field, and the
// order is then sent once more without it. Never removed on a local or customer-path check
// alone, never rewritten, never replaced with an invented value. Every removal is a named
// finding carrying the field and a reason, never the value.
//
// The field list is READ from `domains/ecom/entities/order.json` -> `contactFields[]`, so the
// rules and the entity knowledge cannot drift apart.
const ORDER_ENTITY_JSON = path.join(__dirname, '..', 'domains', 'ecom', 'entities', 'order.json');
let CONTACT_FIELDS = null;
function orderContactFields() {
  if (CONTACT_FIELDS) return CONTACT_FIELDS;
  const entity = JSON.parse(fsSync.readFileSync(ORDER_ENTITY_JSON, 'utf8'));
  const fields = Array.isArray(entity.contactFields) ? entity.contactFields : [];
  if (fields.length === 0) throw new Error(`${ORDER_ENTITY_JSON} carries no contactFields[]; the contact-field rules read their list from there and will not guess one`);
  for (const field of fields) {
    if (field.kind !== 'email' && field.kind !== 'phone') {
      throw new Error(`contactFields[] entry ${field.targetPath} has kind ${JSON.stringify(field.kind)}; only "email" and "phone" are known`);
    }
  }
  CONTACT_FIELDS = Object.freeze(fields.map((field) => Object.freeze({ kind: String(field.kind), targetPath: String(field.targetPath) })));
  return CONTACT_FIELDS;
}

function readAtPath(object, dotted) {
  let node = object;
  for (const key of dotted.split('.')) {
    if (!isPlainObject(node)) return undefined;
    node = node[key];
  }
  return node;
}

// Copy-on-write down the path only; the caller's object is never mutated.
function withoutPath(object, dotted) {
  const [head, ...rest] = dotted.split('.');
  if (!isPlainObject(object) || !(head in object)) return object;
  if (rest.length === 0) {
    const next = { ...object };
    delete next[head];
    return next;
  }
  const child = withoutPath(object[head], rest.join('.'));
  return child === object[head] ? object : { ...object, [head]: child };
}

function presentValue(value) {
  if (value === undefined || value === null) return null;
  const text = String(value).trim();
  return text === '' ? null : text;
}

// Advisory only. Run on the SOURCE-DERIVED body, before the first send. The body is never
// changed; a suspect is a forecast, not a loss.
function checkOrderContactFields(order, { sourceId = null } = {}) {
  if (!isPlainObject(order)) throw new Error('checkOrderContactFields needs the mapped target order body as `order`');
  const findings = [];
  const id = sourceId === undefined || sourceId === null ? null : String(sourceId);
  const countryCode = presentValue(readAtPath(order, 'billingInfo.address.country'));
  for (const field of orderContactFields()) {
    const value = presentValue(readAtPath(order, field.targetPath));
    if (value === null) continue; // an absent detail is not a defect
    if (field.kind === 'email') {
      if (orderBuyer.normalizeEmail(value) === null) {
        findings.push({ code: 'order-contact-email-suspect', ...(id ? { sourceId: id } : {}), field: field.targetPath, reason: 'not-a-sendable-address' });
      }
    } else {
      const normalized = customerMember.normalizePhoneE164(value, countryCode);
      if (!normalized.ok) {
        findings.push({ code: 'order-contact-phone-suspect', ...(id ? { sourceId: id } : {}), field: field.targetPath, reason: String(normalized.reason) });
      }
    }
  }
  return { findings };
}

// Which contact fields did Import Order's rejection NAME? Only a 400 with a structured
// `fieldViolations[]` counts, and only an EXACT path match (after an optional leading `order.`
// request wrapper) against `contactFields[]`. Message text is never parsed. All or
// nothing: one violation that is not an identified contact field means no removal (null).
function identifyRejectedContactFields(error) {
  if (!error || error.status !== 400) return null;
  const violations = error.body && error.body.details && error.body.details.validationError
    && error.body.details.validationError.fieldViolations;
  if (!Array.isArray(violations) || violations.length === 0) return null;
  const known = new Set(orderContactFields().map((field) => field.targetPath));
  const paths = [];
  for (const violation of violations) {
    const raw = violation && typeof violation.field === 'string' ? violation.field : null;
    if (raw === null) return null;
    const field = raw.startsWith('order.') ? raw.slice('order.'.length) : raw;
    if (!known.has(field)) return null;
    if (!paths.includes(field)) paths.push(field);
  }
  return paths;
}

// ---- source orders with no line items -------------------------------------
// Import Order requires 1-300 lineItems. A source order that recorded none (items deleted at the
// source, a total with no lines) would fail terminally. Human-approved policy (2026-11-01):
// import it with ONE custom line "Items not recorded in source" priced at the
// order total, in the order's own currency, with no tax information invented, and hand each such
// order to cutover. Financial data, so this is a human-approved policy, not an engineering default.
const PLACEHOLDER_LINE_NAME = 'Items not recorded in source';
const PLACEHOLDER_LINE_ITEM_TYPE = 'not-recorded-in-source';
const PLACEHOLDER_GAP_CODE = 'order-line-items-not-recorded';
const PLACEHOLDER_GAP_ACTION = 'Each of these orders recorded no line items at the source, so it was imported with one custom line "Items not recorded in source" at the order total (no tax). Confirm the order total with the merchant; if the original items are known, note them on the order. Do not delete or re-import the order.';
function placeholderLineId(derivedId) {
  const hash = crypto.createHash('sha1').update(`replatform:ecom:order-line:${derivedId}:not-recorded`).digest();
  hash[6] = (hash[6] & 0x0f) | 0x50;
  hash[8] = (hash[8] & 0x3f) | 0x80;
  const hex = hash.toString('hex');
  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
}
function placeholderAmount(order) {
  const raw = order && order.priceSummary && order.priceSummary.total && order.priceSummary.total.amount;
  const n = Number(raw);
  return raw !== undefined && raw !== null && String(raw).trim() !== '' && Number.isFinite(n) && n >= 0 ? String(raw).trim() : null;
}
// An order with lineItems is returned unchanged. Pure: the caller's body is never mutated.
function withPlaceholderLineItem(order, { derivedId }) {
  if (!isPlainObject(order) || (Array.isArray(order.lineItems) && order.lineItems.length > 0)) return { order, placeholder: null };
  // No usable order total: the line is priced at 0 and the finding says so (totalMissing).
  const total = placeholderAmount(order), amount = total === null ? '0' : total;
  const line = {
    id: placeholderLineId(derivedId),
    quantity: 1,
    productName: { original: PLACEHOLDER_LINE_NAME },
    itemType: { custom: PLACEHOLDER_LINE_ITEM_TYPE },
    price: { amount },
    lineItemPrice: { amount },
  };
  return { order: { ...order, lineItems: [line] }, placeholder: { lineItemId: line.id, amount, currency: order.currency === undefined ? null : order.currency, ...(total === null ? { totalMissing: true } : {}) } };
}

// The composite. Returns outcomes; throws only for CALLER errors (a malformed contract), never for
// a target failure -- each stage's failure is a named outcome so a resumed run reconciles what
// landed and retries only what did not.
async function importOrderHistory(wix, {
  order,
  sourceId,
  sourceSiteHost,
  evidence,
  crosswalk,
  setupVerification = null,
  pacer = null,
  // Injectable only so the retry tests do not spend the delay ladder in real time.
  sleep = null,
  // The buyer, from resolveOrderBuyer -- stamped, so a hand-built memberId cannot reach
  // the order. Optional: an order with no buyer resolution imports with whatever contactId the
  // mapped body already carries, and never a memberId.
  buyer = null,
} = {}) {
  if (!wix || typeof wix.send !== 'function') throw new Error('importOrderHistory needs a Wix client');
  const sleepFor = sleep || realSleep;
  const findings_pre = [];
  if (!isPlainObject(order)) throw new Error('importOrderHistory needs the mapped target order body as `order`');
  assertCrosswalk(crosswalk);
  assertEvidence(evidence, { sourceId });
  const derivedId = deriveImportedOrderId({ sourceSiteHost, sourceId });
  if (order.id !== undefined && order.id !== derivedId) {
    throw new Error(`order.id is not the caller's to choose: got ${order.id}, this order derives to ${derivedId}. Omit it.`);
  }
  // buyerInfo.memberId is what member-facing reads authorize on, and Import Order stores any GUID
  // unvalidated (verified live 2026-09-05). So it is never the caller's to set on the body: it comes
  // through `buyer`, corroborated and stamped by resolveOrderBuyer, or not at all.
  orderBuyer.assertBodyBuyerInfo(order);
  // No buyer resolution is itself a counted outcome, so the buyer stage partitions the order
  // population like the payment stage does.
  let buyerOutcome = 'buyer-not-resolved';
  if (buyer !== null && buyer !== undefined) {
    if (!orderBuyer.verifyBuyerStamp(buyer)) throw new Error('`buyer` must be the unchanged result of resolveOrderBuyer (its stamp did not verify)');
    // The resolver corroborated the member against ONE order's billing email, and the stamp covers
    // that email. The BODY's email must be the same one: a result resolved for jane@ handed over
    // beside a body carrying victim@ would attribute the victim's order and invoice to Jane, with
    // the stamp verifying (review demonstrated it). Bound for every outcome -- a resolution made for
    // a different order is wrong whatever it decided -- and a linked result requires the body to
    // carry the email at all, so the two are never merely "both absent".
    const rawBodyEmail = order.buyerInfo && order.buyerInfo.email;
    const bodyEmail = orderBuyer.normalizeEmail(rawBodyEmail);
    const bodyHasEmail = rawBodyEmail !== undefined && rawBodyEmail !== null && String(rawBodyEmail).trim() !== '';
    if (buyer.email && bodyHasEmail && bodyEmail !== buyer.email) {
      throw new Error('`buyer` was resolved for a different billing email than order.buyerInfo.email carries; resolve the buyer from THIS order\'s billing email');
    }
    if (buyer.memberId && (!bodyHasEmail || bodyEmail !== buyer.email)) {
      throw new Error('a linked `buyer` requires order.buyerInfo.email to be the billing email the member was corroborated against; the body carries none or another');
    }
    const info = orderBuyer.buyerInfoFrom(buyer);
    // Replace, not merge: only the body's email survives beside what the resolver decided.
    const kept = order.buyerInfo && order.buyerInfo.email ? { email: order.buyerInfo.email } : {};
    order = { ...order, buyerInfo: { ...kept, ...(order.buyerInfo && order.buyerInfo.contactId && !info.contactId ? { contactId: order.buyerInfo.contactId } : {}), ...info } };
    buyerOutcome = buyer.outcome;
    for (const finding of buyer.findings || []) findings_pre.push(finding);
  }

  const findings = findings_pre;
  const errors = {};
  const placed = withPlaceholderLineItem(order, { derivedId });
  order = placed.order;
  if (placed.placeholder) findings.push({ code: PLACEHOLDER_GAP_CODE, sourceId: String(sourceId), ...placed.placeholder });
  const outcomes = { order: null, payment: null, refunds: [], invoice: null, buyer: buyerOutcome };

  // The gate runs FIRST and from the evidence structure, so a caller cannot mis-name a parameter
  // into a silent zero. It is pure: no target read is spent on an order the source never paid.
  const gate = paymentMapping.evaluatePaymentEligibility({
    sourceAmount: evidence.amount === undefined ? null : evidence.amount,
    paidDate: evidence.paidDate === undefined ? null : evidence.paidDate,
    altPaidDate: evidence.altPaidDate === undefined ? null : evidence.altPaidDate,
    distinctAmountCount: evidence.distinctAmountCount === undefined ? 1 : evidence.distinctAmountCount,
    sourceCurrency: evidence.currency === undefined ? null : evidence.currency,
    targetCurrency: order.currency === undefined ? null : order.currency,
    utcOffsetMinutes: evidence.utcOffsetMinutes === undefined ? null : evidence.utcOffsetMinutes,
    paidDateZone: evidence.paidDateZone === undefined || evidence.paidDateZone === null ? 'site-local' : evidence.paidDateZone,
    altPaidDateZone: evidence.altPaidDateZone === undefined || evidence.altPaidDateZone === null ? 'site-local' : evidence.altPaidDateZone,
    sourceStatus: evidence.status === undefined ? null : evidence.status,
  });
  findings.push(...(gate.findings || []));

  let payment = null;
  if (gate.eligible) {
    const built = paymentMapping.buildPaymentRecord({
      amount: gate.amount,
      createdDate: gate.createdDate,
      methodName: evidence.methodName === undefined ? null : evidence.methodName,
      providerTransactionId: evidence.providerTransactionId === undefined ? null : evidence.providerTransactionId,
      offlinePayment: evidence.offlinePayment,
      cardDisplay: evidence.cardDisplay === undefined ? null : evidence.cardDisplay,
    });
    payment = built.payment;
    findings.push(...(built.findings || []));
  }
  const refunds = withOccurrences(evidence.refunds || []);

  // ---- 1. The order. Crosswalk hit or miss, the TARGET is asked once by id. -------------------
  // A hit is not proof: the docs' own use of Bulk Delete Imported Orders is "clear a faulty
  // migration before re-importing", and a crosswalk that survived that must not report an order
  // the target no longer has. Only a readable 404 proves absence; an unreadable gateway
  // response must not authorize Import Order, which can replace an existing order.
  let orderId = derivedId;
  const readPacer = pacer || w.sharedTargetReadPacer(wix);
  const existsOnTarget = async (id) => {
    const read = await readPacer.read(() => w.getOrder(wix, id));
    if (read.ok) return { exists: true };
    if (read.error && read.error.status === 404 && read.error.outcomeKnown !== false) return { exists: false };
    return { exists: null, error: read.error };
  };
  const known = await crosswalk.get(sourceId);
  // The crosswalk's answer is trusted as the order's identity, so its SHAPE is not: a row object
  // where a string was expected became `orders/[object Object]/add-payment` in review. Only a
  // GUID-shaped string may stand for an order; anything else is a broken crosswalk, which is a
  // caller problem and stops the run rather than continuing history onto a nonsense id.
  if (known !== null && known !== undefined && known !== '' && !GUID.test(String(known))) {
    throw new Error(`the crosswalk returned ${JSON.stringify(known)} for source order ${sourceId}; a crosswalk value must be the Wix order id (a GUID string) or null`);
  }
  // A row from before deterministic ids (a Wix-minted id) is still THE order: honouring it is what
  // keeps an earlier migration from being re-imported under a derived id.
  const candidateId = known ? String(known) : derivedId;
  const probe = await existsOnTarget(candidateId);
  if (probe.exists === null) {
    // Cannot tell whether the order is there. Importing now could replace a merchant-edited order;
    // not importing loses nothing a retry cannot recover. So: a named outcome, no write.
    outcomes.order = ORDER_OUTCOMES.TARGET_READ_FAILED;
    errors.order = describeError(probe.error);
    failRemaining(outcomes, errors, { gate, refunds, evidence, cause: 'order-not-imported' });
    return { orderId: null, derivedId, outcomes, findings, errors, paymentId: null, invoice: null };
  }
  if (probe.exists) {
    orderId = candidateId;
    if (known && orderId !== derivedId) findings.push({ code: 'order-id-from-crosswalk', sourceId: String(sourceId), orderId });
    outcomes.order = ORDER_OUTCOMES.ALREADY_IMPORTED;
    if (!known) {
      // The crosswalk had lost it; adopt it.
      try { await crosswalk.set(sourceId, orderId); } catch (error) { errors.crosswalk = describeError(error); }
    }
  } else {
    let derivedExists = false;
    if (known) {
      // The crosswalk points at an order the target no longer has -- a cleared migration, or a
      // stale row. Before importing under the derived id, ask whether THAT order already exists:
      // Import Order with an existing id silently replaces it, and a merchant's edits with it
      // (review demonstrated exactly that). If it exists, adopt it and replace the row.
      const derivedProbe = await existsOnTarget(derivedId);
      if (derivedProbe.exists === null) {
        outcomes.order = ORDER_OUTCOMES.TARGET_READ_FAILED;
        errors.order = describeError(derivedProbe.error);
        failRemaining(outcomes, errors, { gate, refunds, evidence, cause: 'order-not-imported' });
        return { orderId: null, derivedId, outcomes, findings, errors, paymentId: null, invoice: null };
      }
      derivedExists = derivedProbe.exists === true;
      findings.push(derivedExists
        ? { code: 'order-crosswalk-row-stale', sourceId: String(sourceId), previousOrderId: String(known), orderId: derivedId }
        : { code: 'order-reimported-after-deletion', sourceId: String(sourceId), previousOrderId: String(known) });
    }
    if (derivedExists) {
      orderId = derivedId;
      outcomes.order = ORDER_OUTCOMES.ALREADY_IMPORTED;
    } else {
      try {
        // Retried on a transient failure, and safe to: the id is derived from the source and
        // `:296` refuses a caller-chosen one, so a second attempt re-sends the same identity. A
        // retry that comes back already-imported is a SUCCESS -- the existing ALREADY_IMPORTED
        // outcome covers it. Only the send is wrapped: the checks below it are permanent
        // refusals, not conditions that clear.
        const send = async (body) => {
          for (let attempt = 1; ; attempt += 1) {
            try {
              return await w.importOrder(wix, { ...body, id: derivedId });
            } catch (error) {
              if (attempt >= WRITE_RETRY_ATTEMPTS || !w.isTransientWixError(error)) throw error;
              await sleepFor(WRITE_RETRY_DELAYS_MS[attempt - 1]);
            }
          }
        };
        // Advisory, on the source-derived body, once, before the first send.
        // Not repeated for the retry below.
        findings.push(...checkOrderContactFields(order, { sourceId }).findings);
        let imported = null;
        let removed = [];
        try {
          imported = await send(order);
        } catch (error) {
          // One retry, only when the rejection names contact fields the body
          // actually carries. The first call was refused and created nothing, so the retry under
          // the same derived id is not a duplicate. The retry body is the SOURCE-DERIVED order
          // minus exactly those paths, and on a
          // member-linked order it keeps `buyerInfo.memberId`/`contactId` untouched.
          const paths = identifyRejectedContactFields(error);
          if (!paths || !paths.every((p) => readAtPath(order, p) !== undefined)) throw error;
          const retryBody = paths.reduce((body, p) => withoutPath(body, p), order);
          imported = await send(retryBody);
          removed = paths;
        }
        if (!imported || !imported.id) {
          throw new Error('Import Order returned no order id');
        }
        if (imported.id !== derivedId && !GUID.test(String(imported.id))) {
          // Cannot be recorded (the crosswalk accepts only GUIDs) and cannot be trusted. Reported
          // with the id so a human can find the order by number; the run does not continue history
          // onto it.
          throw new Error(`Import Order returned a non-GUID id ${JSON.stringify(imported.id)} for source order ${sourceId} (number ${order.number}); the order may exist on the target under it`);
        }
        if (imported.id !== derivedId) {
          // The order EXISTS, under an id we did not choose. Reporting a failure here would leave
          // no crosswalk row, and every re-run would import it again -- the one outcome this
          // module exists to prevent. So the target's id is adopted and recorded, the order counts
          // as imported, and the finding says the identity model did not hold on this target.
          orderId = String(imported.id);
          findings.push({ code: 'order-id-not-derived', sourceId: String(sourceId), orderId, derivedId });
        }
        outcomes.order = ORDER_OUTCOMES.IMPORTED;
        // One drop finding per removed path, only once the order landed without it. Field and
        // reason, never the value, the member id or the rejection's wording.
        const kinds = new Map(orderContactFields().map((field) => [field.targetPath, field.kind]));
        for (const field of removed) {
          findings.push({
            code: kinds.get(field) === 'email' ? 'order-contact-email-dropped' : 'order-contact-phone-dropped',
            sourceId: String(sourceId),
            field,
            reason: 'import-order-rejected-field',
            ...(field === 'buyerInfo.email' && buyerOutcome === orderBuyer.OUTCOMES.LINKED ? { memberLinkKept: true } : {}),
          });
        }
      } catch (error) {
        outcomes.order = ORDER_OUTCOMES.IMPORT_FAILED;
        errors.order = describeError(error);
        failRemaining(outcomes, errors, { gate, refunds, evidence, cause: 'order-not-imported' });
        return { orderId: null, derivedId, outcomes, findings, errors, paymentId: null, invoice: null };
      }
    }
      // Persisted BEFORE any further write. The one thing nothing else catches. If the write
      // itself fails the order is still on the target and the next run finds it by derived id, so
      // the run continues -- but the caller is told, because a crosswalk that silently stopped
      // persisting is a report that undercounts what landed.
      try {
        await crosswalk.set(sourceId, orderId);
      } catch (error) {
        errors.crosswalk = describeError(error);
      }
  }

  // A landed order that carries the placeholder line is a cutover item, never only a finding.
  if (placed.placeholder && orderId && [ORDER_OUTCOMES.IMPORTED, ORDER_OUTCOMES.ALREADY_IMPORTED].includes(outcomes.order)) {
    try {
      await w.recordWrittenGap(wix, { code: PLACEHOLDER_GAP_CODE, action: PLACEHOLDER_GAP_ACTION, operatorRole: 'Cutover Operator', severity: 'medium',
        detail: { targetId: orderId, orderNumber: order.number === undefined ? null : String(order.number), amount: placed.placeholder.amount, currency: placed.placeholder.currency, ...(placed.placeholder.totalMissing ? { totalMissing: true } : {}) } });
    } catch (error) { errors.cutoverItem = describeError(error); }
  }

  // ---- 2. Payment and refunds, from ONE reconciliation read. ---------------------------------
  let paymentId = null;
  if (!gate.eligible) {
    outcomes.payment = gate.outcome;
    outcomes.refunds = refunds.map((refund) => ({ sourceId: refund.sourceId, sourceOccurrence: refund.sourceOccurrence, outcome: 'refund-without-payment' }));
  } else {
    // The read and the write are retried as ONE pair or not at all. The read decides create-or-
    // adopt, and a failed write attempt is exactly what can make that decision stale -- the
    // attempt that failed may be what created the payment. Retrying the write alone would re-use
    // the pre-failure decision and add a second payment. `assertReconciledBinding`
    // (`wix-writers.js:3729`) refuses a read taken for a different order or a different payment
    // fingerprint, but it cannot detect a stale read for the right one.
    //
    // A `payment-target-read-failed` reconcile does NOT enter this loop: the pacer already
    // retried it internally and `writeOrderPayment` returns that outcome rather than throwing.
    let reconciled = await w.reconcileOrderPaymentTarget(wix, { orderId, payment, pacer });
    let written = null;
    try {
      for (let attempt = 1; ; attempt += 1) {
        try {
          written = await w.writeOrderPayment(wix, { orderId, payment, pacer, reconciled });
          break;
        } catch (error) {
          if (attempt >= WRITE_RETRY_ATTEMPTS || !w.isTransientWixError(error)) throw error;
          await sleepFor(WRITE_RETRY_DELAYS_MS[attempt - 1]);
          // Re-read before re-writing. Coming back RECONCILED means the failed attempt committed
          // after all, and the writer turns that into `payment-reconciled-existing` with no
          // second write -- which is the outcome, not a failure.
          reconciled = await w.reconcileOrderPaymentTarget(wix, { orderId, payment, pacer });
        }
      }
      outcomes.payment = written.outcome;
      paymentId = written.paymentId || null;
      if (written.error) errors.payment = describeError(written.error);
      // "Written" with no id is not written: the refund path would see CREATE still standing and
      // add the payment a second time. Demonstrated in review with an empty `paymentsIds`.
      if (outcomes.payment === 'payment-written' && !paymentId) {
        outcomes.payment = 'payment-failed';
        errors.payment = { cause: 'add-payment-returned-no-id' };
      }
    } catch (error) {
      outcomes.payment = 'payment-failed';
      errors.payment = describeError(error);
    }
    // No payment id means no payment to hang anything off, whatever the outcome's name: ambiguous
    // reconciliation carries no error object from the writer, so the cause is recorded here.
    if (!paymentId && !errors.payment) errors.payment = { cause: outcomes.payment };
    // The refund path sees the same read, updated with the payment this run just created so it
    // does not create a second one. A payment stage that failed leaves nothing to refund against.
    const forRefunds = paymentId && reconciled.outcome === paymentMapping.RECONCILE.CREATE
      ? { ...reconciled, outcome: paymentMapping.RECONCILE.RECONCILED, paymentId, matchedBy: 'written-this-run' }
      : reconciled;
    for (const refund of refunds) {
      const line = { sourceId: refund.sourceId, sourceOccurrence: refund.sourceOccurrence, outcome: null, refundId: null, paymentId: null };
      if (!paymentId) {
        // Refunds are REFUND outcomes. Letting the writer answer here returned the payment stage's
        // own code as the refund's, which the report counts as a payment bucket and never as a
        // refund that did not land.
        line.outcome = 'refund-failed';
        line.error = { cause: outcomes.payment };
      } else {
        try {
          const result = await w.ensureOrderPaymentAndRefund(wix, {
            orderId,
            payment,
            refundAmount: refund.amount,
            reason: refund.reason,
            sourceRefundId: refund.sourceId,
            sourceOccurrence: refund.sourceOccurrence,
            pacer,
            reconciled: forRefunds,
          });
          line.outcome = result.outcome;
          line.refundId = result.refundId || (result.refund && result.refund.id) || null;
          line.paymentId = result.paymentId || null;
        } catch (error) {
          line.outcome = 'refund-failed';
          line.error = describeError(error);
        }
      }
      outcomes.refunds.push(line);
    }
  }

  // ---- 3. The invoice document. ---------------------------------------------------------------
  let invoice = null;
  if (!evidence.invoice) {
    outcomes.invoice = 'invoice-none-found';
  } else {
    // A document that reached Media but whose order patch failed is remembered HERE, in the same
    // persisted state as the order id, not by the caller: a generated importer following the
    // documented loop without persisting it imported a second copy in review. The caller may still
    // pass one explicitly (an older project's state); the crosswalk's answer is the fallback.
    let pendingMediaFileId = evidence.invoice.pendingMediaFileId || null;
    let rememberedPending = null;
    if (!pendingMediaFileId) {
      try {
        const remembered = await crosswalk.getInvoiceFile(sourceId);
        // Either a bare id (older rows) or { fileId, sourceUrl }. A remembered file is only THIS
        // document's if it was imported from the same URL: a re-issued invoice under a new link
        // must not be "resumed" onto the old bytes (review demonstrated it).
        const rememberedId = typeof remembered === 'string' ? remembered : remembered && remembered.fileId;
        const rememberedUrl = remembered && typeof remembered === 'object' ? remembered.sourceUrl || null : null;
        if (rememberedId && String(rememberedId).trim() !== '') {
          if (!rememberedUrl || rememberedUrl === (evidence.invoice.sourceUrl || null)) { pendingMediaFileId = String(rememberedId); rememberedPending = pendingMediaFileId; }
          else findings.push({ code: 'invoice-pending-file-superseded', sourceId: String(sourceId), note: 'a remembered Media file was imported from a different URL and was not resumed' });
        }
      } catch (error) {
        errors.crosswalk = errors.crosswalk || describeError(error);
      }
    }
    try {
      invoice = await w.preserveOrderInvoiceDocument(wix, {
        orderId,
        sourceUrl: evidence.invoice.sourceUrl,
        invoiceNumber: evidence.invoice.invoiceNumber,
        approval: evidence.invoice.approval,
        setupVerification,
        sourceSiteHost,
        pendingMediaFileId,
      });
      outcomes.invoice = invoice.outcome;
      // The writer's findings (an over-length number or link, a key the order PATCH dropped) are
      // losses the report must count, and the report counts `findings`, not `invoice.findings`.
      for (const finding of invoice.findings || []) findings.push(finding);
      // Remember a READY-but-unrecorded file (bound to its URL); CLEAR the memory once the document
      // is settled or the remembered import is dead. Left in place, a FAILED file id was resumed
      // forever and the document never imported (review finding).
      const settled = ['invoice-preserved', 'invoice-already-preserved', 'invoice-number-only', 'invoice-import-failed'].includes(invoice.outcome);
      try {
        if (invoice.pendingMediaFileId && invoice.pendingMediaFileId !== pendingMediaFileId) {
          await crosswalk.setInvoiceFile(sourceId, invoice.pendingMediaFileId, { sourceUrl: evidence.invoice.sourceUrl || null });
        } else if (settled && (rememberedPending || (invoice.outcome === 'invoice-import-failed' && pendingMediaFileId))) {
          await crosswalk.setInvoiceFile(sourceId, null, { sourceUrl: null });
        }
      } catch (error) {
        errors.crosswalk = errors.crosswalk || describeError(error);
      }
    } catch (error) {
      outcomes.invoice = 'invoice-failed';
      errors.invoice = describeError(error);
    }
  }

  return { orderId, derivedId, outcomes, findings, errors, paymentId, invoice };
}

// A crosswalk over the project's own state/crosswalk/crosswalk.ndjson, in the row shape and key
// convention the rest of the runtime uses (`<sourceSystem>:<sourceEntityType>:<sourceId>`, as in
// lib/import-recovery.js), so recovery tooling sees these rows and these rows see its. Loaded
// once, appended per order (O(1) -- the last row per key wins), so a large store does not rewrite
// its whole crosswalk seven thousand times.
//
// The loader is deliberately NOT lib/local-state's: that one throws on any unparsable line and on
// any invalid row of any entity type, which turns a process killed mid-append -- the crash this
// module exists to survive -- into a run that fails every order after it. Here a TRAILING partial
// line (no newline terminator, not parseable) is dropped and reported; any other bad line still
// throws, because that is corruption, not a crash.
function createProjectOrderCrosswalk({ projectDir, sourceSystem = 'wordpress', sourceEntityType = 'order' } = {}) {
  if (!projectDir) throw new Error('createProjectOrderCrosswalk needs the migration projectDir');
  const filePath = localState.crosswalkPath(projectDir);
  const pendingPath = path.join(path.dirname(filePath), 'pending-invoice-files.ndjson');
  const key = (sourceId) => `${sourceSystem}:${sourceEntityType}:${String(sourceId)}`;
  const index = new Map();
  // Bytes of COMPLETE lines already indexed. The file is append-only, so a refresh reads from here
  // rather than re-parsing seven thousand rows -- and a MISS always refreshes first, because
  // another process (or lib/local-state's upsert) may have appended a row since we last looked.
  // Review demonstrated the alternative: a cached index returning null for a legacy row written
  // moments earlier, and a second order imported.
  let offset = 0;
  let lineCount = 0;
  let loaded = false;
  let inode = null;
  const state = { droppedPartialLine: null, droppedPendingPartialLine: null };

  // The file is append-only for THIS adapter, but lib/local-state's upsertCrosswalkRow rewrites
  // and compacts it (temp file + rename). A rewrite that shrank the file below our offset made the
  // incremental read return nothing and a legacy row stay invisible -- review demonstrated a
  // second order imported that way. So every refresh stats first: a new inode or a smaller file
  // means "start over", not "nothing new".
  async function statFile() {
    try {
      const st = await fs.stat(filePath);
      return { size: st.size, ino: st.ino };
    } catch (error) {
      if (error && error.code === 'ENOENT') return { size: 0, ino: null };
      throw error;
    }
  }

  async function readFrom(position) {
    let handle;
    try {
      handle = await fs.open(filePath, 'r');
    } catch (error) {
      if (error && error.code === 'ENOENT') return '';
      throw error;
    }
    try {
      const { size } = await handle.stat();
      if (size <= position) return '';
      const buffer = Buffer.alloc(size - position);
      await handle.read(buffer, 0, buffer.length, position);
      return buffer;
    } finally {
      await handle.close();
    }
  }

  async function refresh() {
    const st = await statFile();
    if ((inode !== null && st.ino !== inode) || st.size < offset) {
      index.clear();
      offset = 0;
      lineCount = 0;
    }
    inode = st.ino;
    const chunkBuffer = await readFrom(offset);
    if (!chunkBuffer || chunkBuffer.length === 0) return;
    // Split on the BYTE, not the decoded string: a tail torn inside a multibyte character decodes
    // to U+FFFD and mis-measures the bytes to truncate (review demonstrated a glued, fatal file).
    const lastNewline = chunkBuffer.lastIndexOf(0x0a);
    const completeBytes = lastNewline === -1 ? 0 : lastNewline + 1;
    const tailBytes = chunkBuffer.length - completeBytes;
    const parts = completeBytes > 0 ? chunkBuffer.subarray(0, completeBytes).toString('utf8').split('\n') : [''];
    if (completeBytes > 0) parts.pop(); // the trailing '' after the final newline
    const tail = tailBytes > 0 ? chunkBuffer.subarray(completeBytes).toString('utf8') : '';
    for (const raw of parts) {
      lineCount += 1;
      const line = raw.replace(/\r$/, '').trim();
      if (!line) continue;
      let row;
      try {
        row = JSON.parse(line);
      } catch (error) {
        throw new Error(`${filePath}:${lineCount} invalid NDJSON: ${error.message}`);
      }
      if (row && row.targetEntityType === 'ecom/order' && typeof row.sourceStableKey === 'string' && typeof row.targetId === 'string') {
        index.set(row.sourceStableKey, row.targetId);
      }
    }
    offset += completeBytes;
    if (tailBytes > 0 && tail.trim()) {
      // A last line with no newline: either a complete row from a writer that omits the
      // terminator, or a line torn by a kill mid-append. A torn line is TRUNCATED on disk, not just
      // skipped -- skipped, the next append would glue a row onto it and corrupt the file for every
      // later reader (review demonstrated this too).
      let row = null;
      try { row = JSON.parse(tail.trim()); } catch (error) { row = null; }
      if (row) {
        // A complete row another writer left unterminated. Indexed; the terminator is added by
        // set() just before our next append, so the file is never touched only to tidy it.
        lineCount += 1;
        if (row.targetEntityType === 'ecom/order' && typeof row.sourceStableKey === 'string' && typeof row.targetId === 'string') {
          index.set(row.sourceStableKey, row.targetId);
        }
        offset += tailBytes;
        needsTerminator = true;
      } else {
        // Truncate only if nothing has been appended since we read: a neighbour's row landing
        // between the read and the truncate would otherwise be deleted. One process per project
        // crosswalk is the supported model (lib/local-state has a state lock for the runtime); this
        // check narrows the window, it does not close it.
        const now = await statFile();
        if (now.ino === inode && now.size === offset + tailBytes) {
          await fs.truncate(filePath, offset);
          state.droppedPartialLine = { line: lineCount + 1, length: tail.length };
        }
      }
    }
  }
  let needsTerminator = false;

  // The pending-invoice sibling file gets the SAME crash discipline as the main crosswalk. Review
  // demonstrated the alternative: a row torn by a kill, the next append glued onto it, one
  // unparsable line holding two pending file ids, both silently ignored -- and a tax document
  // imported twice. A torn TAIL is truncated on disk; a bad line anywhere else is corruption and
  // throws; a complete row left unterminated is read and terminated before the next append.
  async function readPendingRows() {
    let buffer;
    try {
      buffer = await fs.readFile(pendingPath);
    } catch (error) {
      if (!error || error.code !== 'ENOENT') throw error;
      return { rows: [], needsTerminator: false };
    }
    const lastNewline = buffer.lastIndexOf(0x0a);
    const completeBytes = lastNewline === -1 ? 0 : lastNewline + 1;
    const complete = completeBytes > 0 ? buffer.subarray(0, completeBytes).toString('utf8').split('\n') : [];
    if (complete.length > 0) complete.pop(); // the '' after the final newline
    const rows = [];
    complete.forEach((raw, i) => {
      const line = raw.replace(/\r$/, '').trim();
      if (!line) return;
      try { rows.push(JSON.parse(line)); } catch (error) { throw new Error(`${pendingPath}:${i + 1} invalid NDJSON: ${error.message}`); }
    });
    const tail = buffer.subarray(completeBytes).toString('utf8');
    let pendingNeedsTerminator = false;
    if (tail.trim()) {
      let row = null;
      try { row = JSON.parse(tail.trim()); } catch (error) { row = null; }
      if (row) {
        rows.push(row);
        pendingNeedsTerminator = true;
      } else {
        await fs.truncate(pendingPath, completeBytes);
        state.droppedPendingPartialLine = { line: complete.length + 1, length: tail.length };
      }
    }
    return { rows, needsTerminator: pendingNeedsTerminator };
  }

  async function ensureLoaded() {
    if (!loaded) {
      await refresh();
      loaded = true;
    }
  }

  return {
    async get(sourceId) {
      await ensureLoaded();
      const hit = index.get(key(sourceId));
      if (hit) return hit;
      await refresh();
      return index.get(key(sourceId)) || null;
    },
    async set(sourceId, targetId) {
      await ensureLoaded();
      if (needsTerminator) {
        await fs.appendFile(filePath, '\n', 'utf8');
        needsTerminator = false;
      }
      await localState.appendCrosswalkRow(projectDir, {
        schemaVersion: localState.SCHEMA_VERSION,
        sourceSystem,
        sourceEntityType,
        sourceId: String(sourceId),
        sourceStableKey: key(sourceId),
        targetSystem: 'wix',
        targetEntityType: 'ecom/order',
        targetId: String(targetId),
        status: 'imported',
        updatedAt: new Date().toISOString(),
      });
      index.set(key(sourceId), String(targetId));
      await refresh(); // pick up our own row's bytes (and anything a neighbour appended)
    },
    // A Media file that reached READY but whose order patch failed, remembered per source order so
    // the resume records THAT file rather than importing another. Kept in a sibling file, read in
    // full on every ask: it only ever holds the failures, so it stays small, and a stale in-memory
    // copy here would cost a duplicated tax document.
    async getInvoiceFile(sourceId) {
      const { rows } = await readPendingRows();
      let found = null;
      for (const row of rows) {
        if (row && row.sourceStableKey === key(sourceId)) found = row.fileId ? { fileId: row.fileId, sourceUrl: row.sourceUrl || null } : null; // last row wins; a null row clears
      }
      return found;
    },
    async setInvoiceFile(sourceId, fileId, { sourceUrl = null } = {}) {
      // Repair first: a torn tail is truncated and an unterminated complete row gets its newline,
      // so this append always starts a clean line.
      const { needsTerminator } = await readPendingRows();
      await fs.mkdir(path.dirname(pendingPath), { recursive: true });
      if (needsTerminator) await fs.appendFile(pendingPath, '\n', 'utf8');
      await fs.appendFile(pendingPath, `${JSON.stringify({ sourceStableKey: key(sourceId), fileId: fileId === null ? null : String(fileId), sourceUrl: sourceUrl === null ? null : String(sourceUrl), updatedAt: new Date().toISOString() })}\n`, 'utf8');
    },
    // What the loaders had to drop, if anything -- a caller may want to report it.
    droppedPartialLine() { return state.droppedPartialLine; },
    droppedPendingPartialLine() { return state.droppedPendingPartialLine; },
  };
}

// The attempt-journal row for one importOrderHistory result -- the only place that decides it, so
// a generated runner does not. The order is `imported` exactly when the target holds it (the result
// carries `orderId`), with that id and with every failed payment, refund or invoice stage as a
// retryable finding; a rerun reconciles the order by id and retries only those stages. An order
// that was not created never carries a targetId: `derivedId` is where it WOULD be, not evidence
// that it is, and travels as `failure.intendedTargetId`. Status from the kept error, per
// lib/multi-step-attempt.js.
const LANDED_ORDER_OUTCOMES = new Set([ORDER_OUTCOMES.IMPORTED, ORDER_OUTCOMES.ALREADY_IMPORTED]);
const stageFailed = (outcome) => typeof outcome === 'string' && (outcome.endsWith('-failed') || outcome === 'payment-reconciliation-ambiguous');

function orderHistoryAttempt(result, { sourceStableKey } = {}) {
  if (!result || !result.outcomes || !Object.values(ORDER_OUTCOMES).includes(result.outcomes.order)) {
    throw new Error(`orderHistoryAttempt needs an importOrderHistory result; got order outcome ${JSON.stringify(result && result.outcomes && result.outcomes.order)}`);
  }
  const { outcomes, errors = {} } = result;
  const landed = LANDED_ORDER_OUTCOMES.has(outcomes.order) && Boolean(result.orderId);
  const subSteps = [
    { stage: 'payment', outcome: outcomes.payment, failed: stageFailed(outcomes.payment), error: errors.payment },
    ...(outcomes.refunds || []).map((refund) => ({ stage: 'refund', outcome: refund.outcome, failed: stageFailed(refund.outcome), error: refund.error })),
    { stage: 'invoice', outcome: outcomes.invoice, failed: stageFailed(outcomes.invoice), error: errors.invoice },
    ...(errors.crosswalk ? [{ stage: 'crosswalk', outcome: 'crosswalk-write-failed', failed: true, error: errors.crosswalk }] : []),
    // The placeholder-line order landed, but its cutover item could not be filed.
    ...(errors.cutoverItem ? [{ stage: 'cutover-item', outcome: 'cutover-item-write-failed', failed: true, error: errors.cutoverItem }] : []),
  ].filter((step) => step.outcome);
  const base = landed
    ? { outcome: outcomes.order, targetId: result.orderId }
    // A target read that could not decide stopped before Import Order: nothing was written.
    : { outcome: outcomes.order, intendedTargetId: result.derivedId || null, error: errors.order || null, writeAttempted: outcomes.order !== ORDER_OUTCOMES.TARGET_READ_FAILED };
  return require('../../../lib/multi-step-attempt.js').classifyMultiStepAttempt({
    sourceStableKey, operation: 'importOrder', base, subSteps, findings: result.findings || [],
  });
}

module.exports = {
  ORDER_OUTCOMES,
  PLACEHOLDER_LINE_NAME,
  PLACEHOLDER_GAP_CODE,
  withPlaceholderLineItem,
  orderHistoryAttempt,
  EVIDENCE_KEYS,
  REFUND_KEYS,
  INVOICE_KEYS,
  deriveImportedOrderId,
  normalizeSourceSiteHost,
  assertEvidence,
  checkOrderContactFields,
  identifyRejectedContactFields,
  importOrderHistory,
  createProjectOrderCrosswalk,
};