@wix/agent-skills 1.33.0 → 1.34.0

package/skills/wix-replatform/lib/orchestration-state.js

@@ -3,10 +3,13 @@
 const fs = require('node:fs/promises');
 const path = require('node:path');
 const crypto = require('node:crypto');
+const { getDecisionValue, isExplicitUserOneClick } = require('./orchestration-decisions.js');
+const { ensureLedger } = require('./expectations-ledger.js');
+const cmsFallback = require('./plugin-cms-fallback.js');
 
 const SCHEMA_VERSION = 1;
 
-const RUN_STATUS = new Set(['running', 'completed', 'partial', 'blocked', 'failed']);
+const RUN_STATUS = new Set(['running', 'completed', 'partial', 'blocked', 'failed', 'cancel_requested', 'canceled', 'interrupted']);
 const ACTIVE_PHASE = new Set(['orchestration', 'discovery', 'mapping', 'setup', 'codegen', 'execution']);
 const ORCHESTRATION_STATES = new Set([
   'initialized',
@@ -15,30 +18,43 @@ const ORCHESTRATION_STATES = new Set([
   'awaiting_credentials',
   'awaiting_files',
   'awaiting_destination_strategy',
+  'destination_running',
   'preflight_running',
   'preflight_blocked',
+  'quick_mode_adapter_resolution_required',
+  'quick_mode_preflight_required',
+  'quick_mode_plan_required',
+  'quick_mode_reverification_required',
   'discovery_running',
   'discovery_complete',
   'mapping_running',
   'awaiting_mapping_approval',
   'mapping_approved',
   'setup_discovery_running',
+  'awaiting_website_scope',
+  'website_handoff_running',
   'setup_complete',
   'codegen_running',
   'awaiting_execution_approval',
   'execution_approved',
   'executing_setup',
   'executing_import',
+  'storefront_running',
+  'finalizing',
   'completed',
   'partial',
   'blocked',
   'failed',
+  'cancel_requested',
+  'canceled',
+  'interrupted',
 ]);
 const PHASE_STATUS = new Set(['not_started', 'running', 'complete', 'partial', 'blocked', 'failed']);
 const EXECUTION_ITEM_STATUS = new Set(['not_started', 'running', 'complete', 'partial', 'blocked', 'failed', 'skipped']);
 const APPROVAL_STATUS = new Set(['pending', 'approved', 'rejected', 'provisional']);
-const APPROVAL_ACTOR = new Set(['user', 'system', null]);
-const DECISION_SOURCE = new Set(['user', 'deterministic_inference', 'prior_artifact']);
+const APPROVAL_ACTOR = new Set(['user', 'system', 'agent', null]);
+// `context` and `not_asked` are the business-type sources; other keys keep using the first three.
+const DECISION_SOURCE = new Set(['user', 'deterministic_inference', 'prior_artifact', 'context', 'not_asked']);
 
 function nowIso(date = new Date()) {
   return date.toISOString();
@@ -200,6 +216,10 @@ function validateRun(run, errors) {
   if ((isAwaitingState(run.currentState) || run.currentState === 'blocked') && run.needsUserInput !== true) {
     pushError(errors, 'run_needs_user_input', 'needsUserInput must be true for awaiting_* and blocked states');
   }
+  if (['cancel_requested', 'canceled', 'interrupted'].includes(run.currentState) &&
+      !['cancel_requested', 'canceled', 'interrupted'].includes(run.status)) {
+    pushError(errors, 'run_cancellation_status', `${run.currentState} requires matching cancellation status`);
+  }
 }
 
 function validateCheckpoints(checkpoints, errors) {
@@ -250,13 +270,25 @@ function validateApprovals(approvals, errors) {
     if (!Array.isArray(item.artifactRefs)) {
       pushError(errors, `approval_${approvalType}_artifact_refs`, `${approvalType} approval artifactRefs must be an array`);
     }
+    if (Array.isArray(item.artifactRefs)) {
+      for (const ref of item.artifactRefs) {
+        if (typeof ref === 'string' && ref.length) continue;
+        if (!ref || typeof ref !== 'object' || Array.isArray(ref) || ref.kind !== 'census-reconciliation' || ref.path !== 'mapping/review/census-reconciliation.json' || !/^[0-9a-f]{64}$/i.test(ref.sha256 || '')) {
+          pushError(errors, `approval_${approvalType}_artifact_ref_invalid`, `${approvalType} approval contains an invalid artifact reference`);
+        }
+      }
+    }
     if (approvalType === 'execution' && item.status === 'provisional') {
       pushError(errors, 'approval_execution_provisional', 'execution approval must not be provisional');
     }
   }
 }
 
-function validateDecisions(decisions, errors) {
+// `quarantined` collects malformed `pluginCmsFallback:*` entries. That one family (exact,
+// case-sensitive prefix) is never honored when malformed and never fails the run: the entry
+// counts as "no valid answer" everywhere and the capability is asked again at the mapping
+// review. Every other key keeps the fail-closed checks below.
+function validateDecisions(decisions, errors, quarantined = []) {
   if (!decisions || typeof decisions !== 'object') {
     pushError(errors, 'decisions_missing', 'decisions.json is missing or not an object');
     return;
@@ -268,6 +300,11 @@ function validateDecisions(decisions, errors) {
     if (key === 'schemaVersion') {
       continue;
     }
+    if (cmsFallback.isCmsFallbackDecisionKey(key)) {
+      const shape = cmsFallback.cmsFallbackDecisionShape(key, value);
+      if (!shape.ok) quarantined.push({ key, problem: shape.problem });
+      continue;
+    }
     if (!value || typeof value !== 'object') {
       pushError(errors, 'decision_entry_invalid', `decision ${key} must be an object`);
       continue;
@@ -276,44 +313,56 @@ function validateDecisions(decisions, errors) {
   }
 }
 
+function isObjectValue(value) {
+  return Boolean(value) && typeof value === 'object';
+}
+
+// Each check reads only its own sub-object and is skipped when that sub-object is
+// missing: the per-file validators already report it (`*_missing`), and reading
+// `.status` of a missing entry would throw instead of returning the error list.
 function validateCrossArtifactInvariants(artifacts, errors) {
   const { run, checkpoints, approvals } = artifacts;
   if (!run || !checkpoints || !approvals) {
     return;
   }
-  if (run.currentState === 'preflight_running' || run.currentState === 'preflight_blocked' || run.currentState === 'awaiting_destination_strategy') {
+  const mappingCheckpoint = isObjectValue(checkpoints.mapping) ? checkpoints.mapping : null;
+  const mappingApproval = isObjectValue(approvals.mapping) ? approvals.mapping : null;
+  const executionApproval = isObjectValue(approvals.execution) ? approvals.execution : null;
+  if (run.currentState === 'preflight_running' || run.currentState === 'preflight_blocked' || run.currentState === 'awaiting_destination_strategy' || run.currentState === 'destination_running') {
     if (run.activePhase !== 'orchestration') {
       pushError(errors, 'state_phase_preflight', `${run.currentState} requires activePhase=orchestration`);
     }
   }
-  if (run.currentState === 'mapping_running' && checkpoints.mapping.status === 'not_started') {
+  if (run.currentState === 'mapping_running' && mappingCheckpoint && mappingCheckpoint.status === 'not_started') {
     pushError(errors, 'state_mapping_checkpoint', 'mapping_running requires mapping checkpoint status to be started');
   }
-  if (run.currentState === 'awaiting_mapping_approval' && approvals.mapping.status !== 'pending') {
+  if (run.currentState === 'awaiting_mapping_approval' && mappingApproval && mappingApproval.status !== 'pending') {
     pushError(errors, 'state_mapping_approval_pending', 'awaiting_mapping_approval requires approvals.mapping.status=pending');
   }
-  if (run.currentState === 'mapping_approved' && !['approved', 'provisional'].includes(approvals.mapping.status)) {
+  if (run.currentState === 'mapping_approved' && mappingApproval && !['approved', 'provisional'].includes(mappingApproval.status)) {
     pushError(errors, 'state_mapping_approved', 'mapping_approved requires approvals.mapping.status=approved|provisional');
   }
-  if (run.currentState === 'awaiting_execution_approval' && approvals.execution.status !== 'pending') {
+  if (run.currentState === 'awaiting_execution_approval' && executionApproval && executionApproval.status !== 'pending') {
     pushError(errors, 'state_execution_approval_pending', 'awaiting_execution_approval requires approvals.execution.status=pending');
   }
   if (['execution_approved', 'executing_setup', 'executing_import', 'completed'].includes(run.currentState) &&
-      approvals.execution.status !== 'approved') {
+      executionApproval && executionApproval.status !== 'approved') {
     pushError(errors, 'state_execution_approved', `${run.currentState} requires approvals.execution.status=approved`);
   }
 }
 
 function validateArtifacts(artifacts) {
   const errors = [];
+  const quarantined = [];
   validateRun(artifacts.run, errors);
   validateCheckpoints(artifacts.checkpoints, errors);
   validateApprovals(artifacts.approvals, errors);
-  validateDecisions(artifacts.decisions, errors);
+  validateDecisions(artifacts.decisions, errors, quarantined);
   validateCrossArtifactInvariants(artifacts, errors);
   return {
     ok: errors.length === 0,
     errors,
+    quarantined,
   };
 }
 
@@ -326,6 +375,7 @@ async function appendEvent(projectDir, event) {
 }
 
 async function initArtifacts(projectDir, { projectId = path.basename(projectDir), timestamp = nowIso() } = {}) {
+  await ensureLedger(projectDir);
   const dirPath = orchestrationDir(projectDir);
   await mkdirp(dirPath);
   const run = createRun(projectId, timestamp);
@@ -363,7 +413,8 @@ async function loadArtifacts(projectDir) {
   };
 }
 
-function updateDecisionObject(decisions, key, value, { source = 'user', rationale = null, timestamp = nowIso() } = {}) {
+function updateDecisionObject(decisions, key, value, { source = 'user', rationale = null, timestamp = nowIso(), evidenceRef = null } = {}) {
+  assertGenericDecisionKey(key);
   if (!DECISION_SOURCE.has(source)) {
     throw new Error(`invalid decision source: ${source}`);
   }
@@ -372,10 +423,97 @@ function updateDecisionObject(decisions, key, value, { source = 'user', rational
     decidedAt: timestamp,
     source,
     rationale,
+    ...(evidenceRef ? { evidenceRef } : {}),
   };
   return decisions;
 }
 
+function assertGenericDecisionKey(key) {
+  if (cmsFallback.isCmsFallbackDecisionKey(key)) {
+    throw new Error(`${key} is a CMS-fallback answer and is written only by \`orchestration-state.js decide-cms-fallback\` (it binds the answer to the exact proposal shown); the generic decide command cannot record it`);
+  }
+}
+
+/**
+ * The only writer of `pluginCmsFallback:<capability>`. Reads the proposal from the capability's
+ * current plugin-coverage row — the exact text shown at the mapping review — and binds the
+ * answer to it. In the same save it resets the mapping approval to pending, so the router
+ * regenerates the plan; it never deletes artifacts. Mutates `artifacts` and returns the event
+ * to append.
+ */
+function recordPluginCmsFallbackDecision(artifacts, {
+  capability,
+  value,
+  approvedBy,
+  coverageRow,
+  registerEntry = undefined,
+  pluginsRoot = undefined,
+  rationale = null,
+  timestamp = nowIso(),
+} = {}) {
+  if (!artifacts || !artifacts.decisions || !artifacts.approvals) {
+    throw new Error('artifacts.decisions and artifacts.approvals are required');
+  }
+  // One-click/unattended runs never record this answer, approval or decline. Any
+  // automationMode that normalizes to one_click blocks it, whatever its source, so the row
+  // stays pending with zero CMS writes.
+  if (getDecisionValue(artifacts.decisions, 'automationMode') === 'one_click') {
+    throw new Error('decide-cms-fallback is not allowed in a one-click/unattended run (automationMode=one_click): the CMS-fallback row stays pending and is reported for cutover');
+  }
+  if (!capability || typeof capability !== 'string') throw new Error('decide-cms-fallback requires --capability');
+  if (!cmsFallback.DECISION_VALUES.has(value)) {
+    throw new Error(`decide-cms-fallback --value must be approved or declined (got: ${value})`);
+  }
+  if (typeof approvedBy !== 'string' || approvedBy.trim().length === 0) {
+    throw new Error('decide-cms-fallback requires a non-empty --approved-by naming who answered');
+  }
+  const row = coverageRow;
+  if (!row || row.capability !== capability || !cmsFallback.isEligibleCmsFallbackRow(row)
+      || !(row.status === 'pending' || cmsFallback.isApprovedCmsFallbackRow(row))) {
+    throw new Error(`no eligible CMS-fallback row for ${capability} in plugin-coverage.json; there is nothing to approve or decline`);
+  }
+  const entry = registerEntry !== undefined
+    ? registerEntry
+    : cmsFallback.eligibilityByCapability(cmsFallback.loadCmsFallbackRegisters(pluginsRoot).cmsFallbackEligible).get(capability) || null;
+  if (!entry) {
+    throw new Error(`${capability} has no signed entry in cms-fallback-eligible.json; rerun reclassification first`);
+  }
+  const proposal = cmsFallback.proposalFromRow(row);
+  const proposalDigest = cmsFallback.cmsFallbackProposalDigest({ capability, ...proposal });
+  const currentDigest = cmsFallback.cmsFallbackProposalDigest(entry);
+  if (row.cmsFallback.proposalDigest !== currentDigest || proposalDigest !== currentDigest) {
+    throw new Error(`plugin-coverage.json is stale for ${capability}: its proposal differs from the current cms-fallback-eligible.json entry; rerun reclassification (wp-discovery.js --reclassify-coverage) and ask again`);
+  }
+  const key = cmsFallback.decisionKey(capability);
+  artifacts.decisions[key] = {
+    value,
+    decidedAt: timestamp,
+    source: 'user',
+    rationale: rationale || null,
+    approvedBy: approvedBy.trim(),
+    proposal,
+    proposalDigest,
+  };
+  if (artifacts.approvals.mapping && artifacts.approvals.mapping.status !== 'pending') {
+    updateApprovalObject(artifacts.approvals, 'mapping', 'pending', {
+      artifactRefs: artifacts.approvals.mapping.artifactRefs || [],
+      notes: `${key} changed`,
+      timestamp,
+    });
+  }
+  return {
+    key,
+    event: {
+      id: randomId('evt'),
+      timestamp,
+      phase: artifacts.run ? artifacts.run.activePhase : 'mapping',
+      state: artifacts.run ? artifacts.run.currentState : null,
+      type: 'decision.recorded',
+      payload: { key, value },
+    },
+  };
+}
+
 function updateApprovalObject(approvals, approvalType, status, { artifactRefs = [], notes = null, decidedBy = 'user', timestamp = nowIso() } = {}) {
   if (!approvals[approvalType]) {
     throw new Error(`unknown approval type: ${approvalType}`);
@@ -396,6 +534,40 @@ function updateApprovalObject(approvals, approvalType, status, { artifactRefs =
   return approvals;
 }
 
+function isOneClickArtifacts(artifacts) {
+  return isExplicitUserOneClick(artifacts && artifacts.decisions ? artifacts.decisions : {});
+}
+
+function autoApproveOneClick(artifacts, approvalType, { artifactRefs = [], notes = null, timestamp = nowIso() } = {}) {
+  if (!artifacts || !artifacts.approvals) {
+    throw new Error('artifacts.approvals is required');
+  }
+  const automationMode = getDecisionValue(artifacts.decisions || {}, 'automationMode');
+  if (automationMode === 'one_click' && !isOneClickArtifacts(artifacts)) {
+    return { ok: false, changed: false, reason: 'automation_mode_not_explicit_user_one_click' };
+  }
+  if (!isOneClickArtifacts(artifacts)) {
+    return { ok: false, changed: false, reason: 'automation_mode_not_one_click' };
+  }
+  const current = artifacts.approvals[approvalType];
+  if (!current) {
+    throw new Error(`unknown approval type: ${approvalType}`);
+  }
+  if (current.status === 'rejected') {
+    return { ok: false, changed: false, reason: 'approval_rejected' };
+  }
+  if (current.status === 'approved') {
+    return { ok: true, changed: false, reason: 'already_approved' };
+  }
+  updateApprovalObject(artifacts.approvals, approvalType, 'approved', {
+    artifactRefs,
+    notes,
+    decidedBy: 'agent',
+    timestamp,
+  });
+  return { ok: true, changed: true, reason: 'auto_approved' };
+}
+
 function updateCheckpointObject(checkpoints, phase, patch, timestamp = nowIso()) {
   if (!checkpoints[phase]) {
     throw new Error(`unknown checkpoint phase: ${phase}`);
@@ -449,7 +621,11 @@ module.exports = {
   validateArtifacts,
   appendEvent,
   updateDecisionObject,
+  assertGenericDecisionKey,
+  recordPluginCmsFallbackDecision,
   updateApprovalObject,
+  autoApproveOneClick,
+  isOneClickArtifacts,
   updateCheckpointObject,
   transitionRun,
 };

package/skills/wix-replatform/lib/order-reference-readiness.js

@@ -0,0 +1,30 @@
+'use strict';
+// API acceptance is insufficient: every selected rule requires observed dashboard fidelity.
+function proven(cell, aspect) { return cell?.accepted === true && cell.dashboardVerified === true && cell[aspect + 'Fidelity'] === true; }
+function selectOrderReferenceMapping(cells = require('../resources/rp-target-wix/domains/ecom/entities/order.json').importReferenceCanary?.cells || []) {
+  const byId = new Map((cells || []).map(cell => [cell.cell, cell]));
+  const baseline = byId.get(1), blockers = [];
+  if (!proven(baseline, 'shipping')) blockers.push('order-shipping-reference-unverified');
+  if (!proven(baseline, 'tax')) blockers.push('order-tax-reference-unverified');
+  if (blockers.length) return { verified: false, blockers, setupEdgeMode: 'task-complete' };
+  let carrier = true, code = true, taxGroup = true;
+  if (proven(byId.get(2), 'shipping')) carrier = code = false;
+  else if (proven(byId.get(8), 'shipping')) carrier = false;
+  else if (proven(byId.get(9), 'shipping')) code = false;
+  if (proven(byId.get(3), 'tax')) taxGroup = false;
+  if (!carrier && !code && !taxGroup && !(proven(byId.get(4), 'shipping') && proven(byId.get(4), 'tax'))) carrier = code = taxGroup = true;
+  const signatures = { 1: [true, true, true], 2: [false, false, true], 3: [true, true, false], 4: [false, false, false], 8: [false, true, true], 9: [true, false, true] };
+  let selected = [...byId.values()].find(cell => JSON.stringify(signatures[cell.cell] || cell.selectedReferences) === JSON.stringify([carrier, code, taxGroup]));
+  if (!selected || !proven(selected, 'shipping') || !proven(selected, 'tax')) return { verified: false, blockers: ['order-shipping-reference-unverified', 'order-tax-reference-unverified'], setupEdgeMode: 'task-complete', requiredCombination: [carrier, code, taxGroup] };
+  return { verified: true, carrier, code, taxGroup, selectedCell: selected.cell, blockers: [], setupEdgeMode: 'task-complete' };
+}
+function orderShippingReadiness(order, mapping = selectOrderReferenceMapping(), { logistics } = {}) {
+  const lines = order.shipping_lines || [];
+  if (!Array.isArray(lines) || lines.length > 1) return { deferred: true, reason: 'order-multiple-shipping-lines', severity: 'blocker' };
+  if (!lines.length && !(order.tax_lines || []).length) return { shippingInfo: undefined };
+  if (!mapping?.verified) return { deferred: true, reason: mapping?.blockers?.[0] || 'order-shipping-reference-unverified', severity: 'blocker' };
+  if (!lines.length) return { shippingInfo: undefined };
+  const line = lines[0];
+  return { shippingInfo: { title: line.method_title, cost: { price: { amount: String(line.total) } }, ...(logistics ? { logistics } : {}) }, requiredReferences: { carrier: mapping.carrier, code: mapping.code, taxGroup: mapping.taxGroup } };
+}
+module.exports = { selectOrderReferenceMapping, orderShippingReadiness };

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

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