@wix/agent-skills 1.33.0 → 1.34.0

package/skills/wix-replatform/resources/rp-target-wix/lib/order-history.js

@@ -0,0 +1,1027 @@
+'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 } : {}),
+  };
+}
+
+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` -> `safeModeContactFields[]`,
+// the same list safe mode replaces, so the two 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.safeModeContactFields) ? entity.safeModeContactFields : [];
+  if (fields.length === 0) throw new Error(`${ORDER_ENTITY_JSON} carries no safeModeContactFields[]; 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(`safeModeContactFields[] 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 `buildImportOrderRequest`
+// applies safe mode: safe mode's mocks always pass, so a check placed after it would report zero
+// suspects on every rehearsal. 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 `safeModeContactFields[]`. 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;
+}
+
+// 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,
+  safeModeOptions = undefined,
+  // 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 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();
+  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 }, safeModeOptions);
+            } 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
+        // (where safe mode is applied). 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 -- safe mode still applies to what remains -- 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);
+      }
+  }
+
+  // ---- 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;
+      // 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; },
+  };
+}
+
+module.exports = {
+  ORDER_OUTCOMES,
+  EVIDENCE_KEYS,
+  REFUND_KEYS,
+  INVOICE_KEYS,
+  deriveImportedOrderId,
+  normalizeSourceSiteHost,
+  assertEvidence,
+  checkOrderContactFields,
+  identifyRejectedContactFields,
+  importOrderHistory,
+  createProjectOrderCrosswalk,
+};