Subchapter 45.121

Payments Outcome Registry

Execution Manifest Validate

Execution State Prepare

170 more in the appendix

Raw file

wix/skills

lib/payments-outcome-registry.js

JavaScript207 lines10 KB

1'use strict';
2
3// Every outcome and finding code the payments path can produce, in one frozen place.
4//
5// This exists because of a specific repeated failure: a writer gained an outcome, the report never
6// gained a line for it, and a run could lose work while the approval read clean. It happened four
7// times. The first fix was a hand-maintained list, which drifted. The second was a test that
8// SCRAPED the writer source for `outcome: 'literal'`, which missed `invoice-number-only` because
9// that one is produced by a ternary — a green test and a silently unreportable outcome, which is
10// worse than the list it replaced.
11//
12// So: the codes live here, both sides import them, and neither can add one the other has not seen.
13// A registry cannot be out of date with itself.

payments-outcome-registry.js on GitHub

// Mutually exclusive per-order payment outcomes. Their sum must equal the discovered population,

// so a new reason belongs HERE rather than folded into an existing bucket.

const PAYMENT_OUTCOMES = Object.freeze([

'payment-written',

'payment-reconciled-existing',

'payment-not-written-no-amount',

'payment-not-written-no-paid-date',

'payment-not-written-multi-payment',

'payment-not-written-currency-mismatch',

'payment-reconciliation-ambiguous',

'payment-target-read-failed',

'payment-failed',

]);

// Outcomes a writer returns that are NOT the per-order payment partition: refund results, invoice

// results, and internal bookkeeping. Everything a writer can hand back must appear in one of the

// three lists, or the report has nowhere to put it.

const WRITER_OUTCOMES = Object.freeze([

'refund-written',

'refund-reconciled-existing',

'refund-without-payment',

'refund-still-settling',

'invoice-preserved',

'invoice-already-preserved',

'invoice-number-only',

'invoice-none-found',

'invoice-import-failed',

'invoice-import-not-ready',

'invoice-import-read-failed',

// The Media file is READY but the order patch failed; the file id rides back as

// pendingMediaFileId so the resume does not import a second copy.

'invoice-fields-write-failed',

'invoice-fields-not-provisioned',

'invoice-preservation-not-approved',

'invoice-preservation-declined',

'invoice-document-url-unsafe',

// The order-history composite's own outcomes. The ORDER stage has four; a stage that threw after

// the order existed is a named partial-failure outcome rather than an exception, so a resumed

// run reconciles the order and retries only what failed.

'order-imported',

'order-already-imported',

'order-import-failed',

'order-target-read-failed',

'refund-failed',

'invoice-failed',

// The buyer stage -- which member, if any, an imported order was attributed to.

// These PARTITION the order population (see BUYER_OUTCOMES); `buyer-not-resolved` is the

// composite's answer when no buyer was supplied.

'buyer-member-linked',

'buyer-guest',

'buyer-contact-only',

'buyer-member-not-imported',

'buyer-member-email-mismatch',

'buyer-not-resolved',

// Product category attachment (stores-category-attach.js). The identical orthogonal-axis shape

// as the order sub-stages above, but for products: a product the entity row already counts as

// `imported` can still carry zero of its categories, invisibly, unless this stage is tracked on

// its own. The failure this guards against: a 3-argument call site silently dropped

// every category-attach write's payload to `{ productId: undefined, categoryIds: undefined }`,

// every request almost certainly failed, and a wrapping `catch {}` hid it completely -- a

// completion report showed `product: reconciled, mismatch: false` while no product actually

// carried its categories live.

'category-attach-written',

'category-attach-reconciled-existing',

'category-attach-unverified',

'category-attach-failed',

// Internal: a target read that carried no mapped payment, and the pre-create verdict.

'target-read',

'create',

]);

// Nested findings — attached to a result rather than returned as its outcome. They count too: an

// over-length link is a loss the merchant should see even though the document was preserved.

const FINDING_CODES = Object.freeze([

'payment-status-conflict',

'paid-date-disagreement',

'paid-date-timezone-assumed',

'paid-date-unparseable',

'reference-without-paid-date',

'no-transaction-reference',

'ambiguous-transaction-reference',

'incompatible-gateway-metadata',

'unverified-gateway-key',

'reference-over-length',

'method-name-over-length',

'card-display-over-length',

'unclassified-method',

'unmapped-gateway-family',

'refund-weak-signal',

'refund-date-not-preserved',

'refund-line-detail-not-preserved',

'invoice-link-over-length',

// Live-verified 2026-10-27: Update Order silently drops an over-maxLength value, so the writer

// checks the number itself, and reports any key the PATCH response does not carry back.

'invoice-number-over-length',

'invoice-field-dropped',

'saved-cards-not-transferred',

'redacted-source-values',

// Order-history composite: the order's id came from a crosswalk row rather than being derived from the source

// id -- an order imported before deterministic ids, or by another tool. Counted so a store

// where every row says this is visibly an import from before deterministic ids rather than a derivation bug.

'order-id-from-crosswalk',

// Order-history composite: Import Order returned an id other than the one supplied. The target's id is adopted

// and persisted so re-runs converge; the finding says the identity model did not hold here.

'order-id-not-derived',

// Order-history composite: a crosswalk row pointed at an order the target no longer has (a cleared migration),

// so the order was imported again under the derived id and the row replaced.

'order-reimported-after-deletion',

// Order-history composite: a crosswalk row pointed at a missing order while the DERIVED-id order exists; the

// existing order was adopted and the row replaced, nothing imported.

'order-crosswalk-row-stale',

// Order-history composite: a remembered Media file came from a different source URL and was not resumed.

'invoice-pending-file-superseded',

// Buyer stage: crosswalk values that could not be used as ids.

'buyer-member-id-not-guid',

'buyer-contact-id-not-guid',

// Import Order refused an order on a contact field its rejection NAMED, so that

// field was removed and the order sent once more. The row names

// the field and the reason, never the value. Registering a code is what gives it a report line

// (REPORTABLE feeds ADDITIONAL_COUNTS), including a zero line on a clean run. The `order-`/

// `buyer-` prefixes are load-bearing: payments-report-lines-test.js scans writer source for

// exactly those prefixes, and a code it cannot see is a code nothing can count.

'order-contact-email-dropped',

'order-contact-phone-dropped',

// A WARNING, not a loss: a local check dislikes a source email or phone, which is

// kept and sent unchanged. Reported as its own line; never summed with the drops above.

'order-contact-email-suspect',

'order-contact-phone-suspect',

// The order carried an email `normalizeEmail` refused, so a named customer became

// an anonymous guest. A finding, NOT an outcome: the buyer partition is unchanged.

'buyer-email-unusable',

// A source order with no line items was imported with one custom "Items not recorded in source"

// line at the order total (human-approved policy); each is also a Cutover Operator item.

'order-line-items-not-recorded',

]);

// Mutually exclusive per-order buyer outcomes. When a report carries any of them, they

// must sum to the order population, like the payment partition.

const BUYER_OUTCOMES = Object.freeze([

'buyer-member-linked',

'buyer-guest',

'buyer-contact-only',

'buyer-member-not-imported',

'buyer-member-email-mismatch',

'buyer-not-resolved',

]);

// Actions the invoice preservation plan assigns per document. They are not outcomes, but they

// travel the same chain -- plan action becomes the writer's approval -- so registering them keeps

// producer and consumer on one vocabulary rather than two that happen to agree.

const PLAN_ACTIONS = Object.freeze([

'preserve',

'offer-preservation',

'reference-only',

'refused',

]);

// Causes attached to a partial-failure outcome (`errors.<stage>.cause`) by the order-history composite.

// Not outcomes and not counted, but handed back to callers, so they are registered here rather than

// living as stray literals the scan cannot account for.

const CAUSE_CODES = Object.freeze([

'order-not-imported',

'add-payment-returned-no-id',

]);

// What the report must carry a line for: every writer outcome that is not internal bookkeeping,

// plus every nested finding. Zero-valued lines are emitted, so absence of a line is a defect.

//

// The four category-attach-* codes are WRITER_OUTCOMES (so stageResiduals can validate them --

// see completion-report.js's STAGE_RESIDUAL_OUTCOMES), but they are deliberately listed here too:

// `REPORTABLE` feeds `rp-execution-policy/payments-report.js`'s ADDITIONAL_COUNTS, which is the

// PAYMENTS plan report -- a product-category outcome has no business appearing as a merchant-facing

// line on a document about payment providers and invoices. Product category attachment is reported

// through completion-report.js's stageResiduals mechanism directly (see

// collectCategoryAttachStageResiduals in stores-category-attach.js), which is the correct and only

// channel for it.

const INTERNAL_ONLY = Object.freeze(['target-read', 'create',

'category-attach-written', 'category-attach-reconciled-existing', 'category-attach-unverified', 'category-attach-failed']);

const REPORTABLE = Object.freeze([

...WRITER_OUTCOMES.filter((code) => !INTERNAL_ONLY.includes(code)),

...FINDING_CODES,

]);

module.exports = {

PAYMENT_OUTCOMES,

BUYER_OUTCOMES,

PLAN_ACTIONS,

CAUSE_CODES,

WRITER_OUTCOMES,

FINDING_CODES,

INTERNAL_ONLY,

REPORTABLE,

};