@wix/agent-skills 1.33.1 → 1.34.0

package/skills/wix-replatform/lib/read-back-reads.js

@@ -0,0 +1,94 @@
+'use strict';
+
+class ReadBackBudgetError extends Error {
+  constructor(reason = 'read-budget-exhausted') {
+    super(reason);
+    this.code = reason;
+  }
+}
+class ReadBackReads {
+  constructor(client, {
+    now = () => performance.now(),
+    sleep = ms => new Promise(r => setTimeout(r, ms)),
+    budgetMs = 600000,
+    settlementMs = 60000,
+    pacingMs = 200
+  } = {}) {
+    Object.assign(this, {
+      client,
+      now,
+      sleep,
+      budgetMs,
+      settlementMs,
+      pacingMs
+    });
+    this.stats = {
+      attempts: 0,
+      timeouts: 0,
+      readMs: 0,
+      pacingMs: 0,
+      retryMs: 0,
+      settlementMs: 0
+    };
+    this.nextAt = 0;
+    this.queue = Promise.resolve();
+    this.wix = {
+      send: request => this.send(request)
+    };
+  }
+  remaining() {
+    return Math.max(0, this.budgetMs - ['readMs', 'pacingMs', 'retryMs', 'settlementMs'].reduce((n, k) => n + this.stats[k], 0));
+  }
+  async timed(kind, fn) {
+    const start = this.now();
+    try {
+      return await fn();
+    } finally {
+      this.stats[kind] += Math.max(0, this.now() - start);
+    }
+  }
+  async wait(ms, kind) {
+    if (ms > this.remaining()) throw new ReadBackBudgetError();
+    await this.timed(kind, () => this.sleep(ms));
+    if (this.remaining() <= 0) throw new ReadBackBudgetError();
+  }
+  async settle() {
+    if (this.settlementMs - this.stats.settlementMs < 60000) throw new ReadBackBudgetError('media-settlement-exhausted');
+    await this.wait(60000, 'settlementMs');
+  }
+  send(request) {
+    const task = this.queue.then(() => this.attempt(request));
+    this.queue = task.catch(() => {});
+    return task;
+  }
+  async attempt(request) {
+    for (let i = 0; i < 4; i++) {
+      if (this.remaining() <= 0) throw new ReadBackBudgetError();
+      const delay = Math.max(0, this.nextAt - this.now());
+      if (delay) await this.wait(delay, 'pacingMs');
+      this.stats.attempts++;
+      try {
+        const result = await this.timed('readMs', () => this.client.send(require('../resources/rp-target-wix/lib/wix-writers').buildBoundedReadRequest(request, Math.min(10000, this.remaining()))));
+        this.nextAt = this.now() + this.pacingMs;
+        return result;
+      } catch (e) {
+        this.nextAt = this.now() + this.pacingMs;
+        if (e.readTimedOut) this.stats.timeouts++;
+        if (e.status === 401 || e.status === 403) {
+          e.code = e.status === 401 ? 'auth-failed' : 'permission-denied';
+          throw e;
+        }
+        const retry = e.readTimedOut || !e.status || [429, 500, 502, 503, 504].includes(e.status) || e.status >= 200 && e.status < 300 && e.outcomeKnown === false || e.status === 404 && e.outcomeKnown === true;
+        if (!retry || i === 3) {
+          e.code ||= retry ? 'read-unavailable' : 'read-rejected';
+          throw e;
+        }
+        await this.wait(e.status === 429 && e.retryAfterMs != null ? e.retryAfterMs : 1000 * 2 ** i, 'retryMs');
+      }
+    }
+  }
+}
+module.exports = {
+  ReadBackReads,
+  ReadBackBudgetError
+};

package/skills/wix-replatform/lib/read-back-state.js

@@ -0,0 +1,107 @@
+'use strict';
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const local = require('./local-state');
+const FILE = 'execution/read-back-gate.json';
+async function readJson(projectDir, name, fallback) {
+  try {
+    return JSON.parse(await fs.readFile(path.join(projectDir, name), 'utf8'));
+  } catch (e) {
+    if (e.code === 'ENOENT' && fallback !== undefined) return structuredClone(fallback);
+    throw e;
+  }
+}
+async function atomic(projectDir, name, value) {
+  const file = path.join(projectDir, name),
+    temp = `${file}.${crypto.randomUUID()}.tmp`;
+  await fs.mkdir(path.dirname(file), {
+    recursive: true
+  });
+  try {
+    await fs.writeFile(temp, JSON.stringify(value, null, 2) + '\n', {
+      mode: 0o600
+    });
+    await fs.rename(temp, file);
+  } finally {
+    await fs.rm(temp, {
+      force: true
+    });
+  }
+}
+// Use the project's existing lock. Contending local writers retry instead of losing updates.
+const localQueues = new Map();
+function locked(projectDir, fn) {
+  const key = path.resolve(projectDir),
+    previous = localQueues.get(key) || Promise.resolve();
+  const task = previous.catch(() => {}).then(() => acquire(projectDir, fn));
+  localQueues.set(key, task);
+  return task.finally(() => {
+    if (localQueues.get(key) === task) localQueues.delete(key);
+  });
+}
+async function acquire(projectDir, fn) {
+  const deadline = Date.now() + 30000;
+  for (;;) {
+    try {
+      return await local.withStateLock(projectDir, fn);
+    } catch (e) {
+      if (!/state lock already held/.test(e.message) || Date.now() >= deadline) throw e;
+      await new Promise(r => setTimeout(r, crypto.randomInt(10, 40)));
+    }
+  }
+}
+async function load(projectDir) {
+  let state;
+  try {
+    state = await readJson(projectDir, FILE);
+  } catch (e) {
+    if (e.code !== 'ENOENT') throw new Error('gate history unreadable', {
+      cause: e
+    });
+    const store = require('./write-verification-state');
+    let hasHistory = false;
+    const snapshot = await readJson(projectDir, 'state/write-verification.json', null);
+    if (snapshot) {
+      const recovered = await store.load(projectDir, snapshot.siteId);
+      hasHistory = Object.values(recovered.rows).some(r => r.kind === 'read-back-gate');
+    } else {
+      // An un-compacted journal also proves a gate existed.
+      let files = [];
+      try {
+        files = await fs.readdir(path.join(projectDir, 'state/write-verification-journal'));
+      } catch (err) {
+        if (err.code !== 'ENOENT') throw err;
+      }
+      for (const file of files.filter(f => f.endsWith('.json'))) {
+        const delta = await readJson(projectDir, `state/write-verification-journal/${file}`);
+        if (Object.values(delta.rows || {}).some(r => r.kind === 'read-back-gate')) hasHistory = true;
+      }
+    }
+    if (hasHistory) throw new Error('gate history unreadable');
+    state = {
+      schemaVersion: 1,
+      observedLosses: [],
+      runs: {}
+    };
+  }
+  if (state.schemaVersion !== 1 || !Array.isArray(state.observedLosses) || !state.runs || Array.isArray(state.runs)) throw new Error('gate history unreadable');
+  return state;
+}
+async function update(projectDir, mutate) {
+  return locked(projectDir, async () => {
+    const state = await load(projectDir);
+    const result = await mutate(state);
+    await atomic(projectDir, FILE, state);
+    return result;
+  });
+}
+module.exports = {
+  FILE,
+  readJson,
+  atomic,
+  locked,
+  load,
+  update
+};

package/skills/wix-replatform/lib/read-back-summary.js

@@ -0,0 +1,81 @@
+'use strict';
+
+const state = require('./read-back-state');
+const FIELD_CATEGORIES = ['verified', 'changed', 'dropped', 'refused', 'unverifiable', 'guardDropped', 'notExercised'];
+const numeric = (object, keys) => Object.fromEntries(keys.filter(key => typeof object?.[key] === 'number' && Number.isFinite(object[key])).map(key => [key, Math.max(0, object[key])]));
+function identity(value) {
+  if (!value) return null;
+  return { userId: value.userId || null, displayName: value.displayName || null, source: value.source || null, observedAt: value.observedAt || null };
+}
+function acknowledgement(value) {
+  if (!value) return { status: 'pending' };
+  return { status: value.status, requestId: value.requestId || null, answeredAt: value.answeredAt || null, recordedBy: identity(value.recordedBy) };
+}
+function currentEntries(gate) {
+  return Object.entries(gate.runs || {}).flatMap(([runId, run]) => Object.entries(run.entities || {}).filter(([entity, item]) => !(item.supersededBy && gate.runs[item.supersededBy]?.entities?.[entity])).map(([entity, item]) => ({ runId, entity, item })));
+}
+function projectReadBackSummary(gate, { entity: filter } = {}) {
+  const runs = new Map();
+  let observedLossCount = 0;
+  for (const { runId, entity, item } of currentEntries(gate)) {
+    if (filter && filter !== entity) continue;
+    if (!runs.has(runId)) runs.set(runId, []);
+    if (item.gated === false) {
+      const declared = require('./read-back-gate').declaration(entity, item);
+      if (declared.gated) throw new Error('Gated entity cannot be reported as a non-gated declaration');
+      runs.get(runId).push({ ...declared, status: 'not-covered' });
+      continue;
+    }
+    const guardDropped = item.guardDropped || [];
+    const guardPaths = [...new Set(guardDropped.map(row => row.path).filter(Boolean))].sort();
+    const fieldCounts = Object.fromEntries(FIELD_CATEGORIES.map(kind => [kind, kind === 'guardDropped' ? guardPaths.length : new Set(item.paths?.[kind] || []).size]));
+    const losses = (gate.observedLosses || []).filter(row => row.entity === entity);
+    observedLossCount += losses.length;
+    runs.get(runId).push({
+      entity, gated: true, status: item.status, stopReason: item.stopReason || null,
+      canaryCount: item.canaries?.length || 0, endOfRunVerified: item.endOfRunVerified === true,
+      fieldCounts, observedPathCounts: fieldCounts,
+      guardDropped: { recordCount: new Set(guardDropped.map(row => row.sourceId)).size, paths: guardPaths },
+      observedLossCount: losses.length,
+      approvedOmissions: (item.approvedOmissions || []).map(row => ({ path: row.path, kind: row.kind, recordCount: row.recordCount, approvedBy: identity(row.approvedBy), merchantAcknowledgement: acknowledgement(row.merchantAcknowledgement) })),
+      pendingSettlementCount: (item.settlements || []).filter(row => row.status !== 'passed').length,
+      timing: numeric(item.timing, ['elapsedMs', 'preparationMs', 'writeMs', 'activeReadMs']),
+      retryStats: numeric(item.retryStats, ['attempts', 'timeouts', 'readMs', 'pacingMs', 'retryMs', 'settlementMs', 'remainingMs'])
+    });
+  }
+  return { schemaVersion: 1, status: runs.size ? 'recorded' : 'not-run', observedLossCount, runs: [...runs].map(([runId, entities]) => ({ runId, entities: entities.sort((a, b) => a.entity.localeCompare(b.entity)) })) };
+}
+async function recordDeclaration(projectDir, runId, entity, options) {
+  const declared = require('./read-back-gate').declaration(entity, options);
+  if (declared.gated) throw new Error('Gated entity requires ReadBackGate; a declaration cannot bypass it');
+  if (typeof runId !== 'string' || !runId.trim() || typeof entity !== 'string' || !entity.trim()) throw new Error('Declaration requires run and entity');
+  return state.update(projectDir, gate => {
+    // Never overwrite earlier gate evidence, including a stopped or superseded row.
+    const history = Object.values(gate.runs).flatMap(run => Object.entries(run.entities || {})).filter(([name]) => name === entity);
+    if (history.some(([, item]) => item.gated !== false || item.status !== 'not-covered')) throw new Error('Declaration cannot replace existing gate history');
+    for (const [previousId, previous] of Object.entries(gate.runs)) {
+      if (previousId !== runId && Object.hasOwn(previous.entities || {}, entity)) previous.entities[entity].supersededBy = runId;
+    }
+    const run = Object.hasOwn(gate.runs, runId) ? gate.runs[runId] : { entities: {} };
+    gate.runs = { ...gate.runs, [runId]: { ...run, entities: { ...run.entities, [entity]: { ...declared, status: 'not-covered' } } } };
+    return declared;
+  });
+}
+function renderReadBackSummary(summary) {
+  const lines = ['', '## Read-Back Verification', '', `- Status: ${summary.status}.`];
+  for (const run of summary.runs) for (const item of run.entities) {
+    lines.push('', `### ${item.entity} (${run.runId})`, '');
+    if (!item.gated) {
+      lines.push(`- Outside the four-entity field gate; verification: ${item.verificationKind}; reason: ${item.reason}.`);
+      continue;
+    }
+    lines.push(`- Gate: ${item.status}; final record verified: ${item.endOfRunVerified ? 'yes' : 'no'}${item.stopReason ? `; reason: ${item.stopReason}` : ''}.`);
+    lines.push(`- Field counts: ${Object.entries(item.fieldCounts).map(([key, value]) => `${key}: ${value}`).join('; ')}.`);
+    lines.push(`- Guard-dropped: ${item.guardDropped.recordCount} records; ${item.guardDropped.paths.length} paths. Pending settlements: ${item.pendingSettlementCount}.`);
+    lines.push(`- Timing: ${Object.entries(item.timing).map(([key, value]) => `${key}: ${value} ms`).join('; ') || 'not recorded'}.`);
+    lines.push(`- Read activity: ${Object.entries(item.retryStats).map(([key, value]) => `${key}: ${value}`).join('; ') || 'not recorded'}.`);
+    for (const omission of item.approvedOmissions) lines.push(`- Approved omission: ${omission.path} (${omission.kind}, ${omission.recordCount == null ? 'unknown' : omission.recordCount} records); approved by ${omission.approvedBy?.displayName || 'not recorded'} (${omission.approvedBy?.userId || 'no stable id'}); merchant acknowledgement: ${omission.merchantAcknowledgement.status}.`);
+  }
+  return lines;
+}
+module.exports = { FIELD_CATEGORIES, currentEntries, projectReadBackSummary, recordDeclaration, renderReadBackSummary };

package/skills/wix-replatform/lib/rerun-conflicts.js

@@ -0,0 +1,334 @@
+'use strict';
+
+// What happens when a rerun's update collides with a change somebody
+// made in Wix since the previous import.
+//
+// The whole point of this module is that it CANNOT resolve a conflict on its own. There is no
+// "fetch the latest revision and retry" function here, deliberately: that is the one behaviour
+// is forbidden outright, because it silently overwrites a merchant's own edit with source
+// data and leaves no trace that a decision was ever made. Every path out of a conflict runs
+// through a recorded user answer, including in one-click mode.
+
+const crypto = require('node:crypto');
+
+// Do not label every HTTP 409 or validation/auth error a revision conflict. A 409 on this
+// platform also means ALREADY_EXISTS (product tags) and other non-revision states, so the code
+// is what classifies, not the status.
+//
+// ONLY live-observed codes belong here. `INVALID_REVISION` is the one this repo has actually
+// seen: a real 409 INVALID_REVISION from addDeliveryRegion on a stale
+// delivery-profile revision, and wix-writers.js:2859 documents it. Codes for Products v3 and
+// Contacts v5 conflicts have NOT been observed, so they are deliberately absent rather than
+// guessed — a guessed allowlist is untestable (every test would feed it a code it already
+// contains) and silently downgrades a real conflict to an ordinary failure.
+//
+// Two things make an incomplete list safe rather than catastrophic:
+//   1. `revisionConflictCodes` is injectable, so the entity's declared classification (the accepted mapping declares a
+//      conflict-error classification per entity) drives it.
+//   2. An UNRECOGNIZED failure on a revision-carrying update is classified
+//      `possible_revision_conflict`, never `other`. It goes to a human instead of being
+//      swallowed. That is the fail-safe for exactly the case a test cannot predict.
+const OBSERVED_REVISION_CONFLICT_CODES = new Set(['INVALID_REVISION']);
+
+// Kept as the historical export name; now sourced from the observed set only.
+const REVISION_CONFLICT_CODES = OBSERVED_REVISION_CONFLICT_CODES;
+
+const CONFLICT_CHOICES = new Set(['override', 'keep']);
+
+// Enforcement, not documentation. "Each entity needs a verified update
+// operation and conflict protection; if either is unavailable, report the changed record for
+// review rather than overwriting it through its create/import operation."
+//
+// Orders are named explicitly because the failure mode is silent data loss, and live evidence
+// recorded it: Update Order exposes a restricted field set with no general revision
+// parameter, and re-sending Import Order with the same id REPLACES the whole body, clearing
+// omitted fields. A future importer must not be able to route a changed order through this flow
+// just because the prose said not to.
+const UPDATE_DENIED_ENTITIES = new Map([
+  ['ecom/order', 'Update Order exposes a restricted field set and no general revision parameter, and a same-id Import Order is an unguarded whole-body replacement that clears omitted fields. Report the changed order for review.'],
+  ['ecom/order-line-item', 'Written through the parent order, which has no revision-protected update path.'],
+  ['ecom/order-line-item-options', 'Written through the parent order, which has no revision-protected update path.'],
+  ['ecom/order-applied-discount', 'Written through the parent order, which has no revision-protected update path.'],
+  ['ecom/order-merchant-note', 'Written through the parent order, which has no revision-protected update path.'],
+  ['ecom/order-refund', 'Written through the parent order, which has no revision-protected update path.'],
+]);
+
+// `declaredUpdateWriters` comes from the accepted mapping: { 'stores/product': { writerId,
+// revisionParam } }. An entity absent from it has no verified update path as far as this run is
+// concerned, which is a review outcome — never a create/import fallback.
+function updateSupportFor(entityRef, { declaredUpdateWriters = {} } = {}) {
+  if (!entityRef || typeof entityRef !== 'string') {
+    return { supported: false, action: 'report_for_review', reason: 'no_entity_ref' };
+  }
+  if (UPDATE_DENIED_ENTITIES.has(entityRef)) {
+    return {
+      supported: false,
+      action: 'report_for_review',
+      reason: 'update_path_unsafe_for_entity',
+      detail: UPDATE_DENIED_ENTITIES.get(entityRef),
+      neverFallBackToCreate: true,
+    };
+  }
+  const declared = declaredUpdateWriters[entityRef];
+  if (!declared || !declared.writerId) {
+    return { supported: false, action: 'report_for_review', reason: 'no_verified_update_writer' };
+  }
+  if (!declared.revisionParam) {
+    // A verified writer with no revision parameter has no conflict protection, which is
+    // required alongside the writer itself.
+    return { supported: false, action: 'report_for_review', reason: 'no_conflict_protection' };
+  }
+  return {
+    supported: true,
+    action: 'update',
+    writerId: declared.writerId,
+    revisionParam: declared.revisionParam,
+  };
+}
+
+function errorCodeOf(error) {
+  if (!error || typeof error !== 'object') {
+    return null;
+  }
+  const details = error.details || (error.body && error.body.details) || {};
+  const applicationError = details.applicationError || {};
+  return (
+    applicationError.code
+    || error.code
+    || (error.body && error.body.code)
+    || null
+  );
+}
+
+function httpStatusOf(error) {
+  if (!error || typeof error !== 'object') {
+    return null;
+  }
+  return error.status ?? error.httpStatus ?? error.statusCode ?? null;
+}
+
+// Returns the classification only — never a remedy.
+//
+// `entityConflictCodes` lets the accepted mapping declare this entity's real conflict codes
+// (declared per entity in the accepted mapping). `sentRevision` says whether the failed call actually carried a revision: when it did,
+// an unrecognized failure that could plausibly be a concurrency error becomes
+// `possible_revision_conflict` and goes to a human, because classifying it `other` would skip
+// the override/keep flow that is the whole point of this flow.
+function classifyUpdateError(error, { entityConflictCodes = null, sentRevision = false } = {}) {
+  const code = errorCodeOf(error);
+  const status = httpStatusOf(error);
+  const upper = code ? String(code).toUpperCase() : null;
+  const known = new Set([
+    ...OBSERVED_REVISION_CONFLICT_CODES,
+    ...(Array.isArray(entityConflictCodes) ? entityConflictCodes.map((c) => String(c).toUpperCase()) : []),
+  ]);
+  if (upper && known.has(upper)) {
+    return { kind: 'revision_conflict', code, httpStatus: status, matchedBy: OBSERVED_REVISION_CONFLICT_CODES.has(upper) ? 'observed' : 'declared' };
+  }
+  if (status === 401 || status === 403) {
+    return { kind: 'auth', code, httpStatus: status };
+  }
+  if (status === 404) {
+    return { kind: 'not_found', code, httpStatus: status };
+  }
+  // A 409 on a revision-carrying update is the ambiguous case the allowlist cannot settle. It is
+  // NOT auto-treated as a conflict (that would let a real ALREADY_EXISTS drive an override), and
+  // NOT dropped to `other` either. It is surfaced for review with its real code intact.
+  if (status === 409 && sentRevision) {
+    return {
+      kind: 'possible_revision_conflict',
+      code,
+      httpStatus: status,
+      needsHumanClassification: true,
+      note: 'A 409 on a revision-carrying update whose code is not in the observed or declared conflict list. Do not auto-retry; classify it, then add the code to the entity\'s declared conflict codes.',
+    };
+  }
+  if (status === 400 || status === 422 || status === 428) {
+    return { kind: 'validation', code, httpStatus: status };
+  }
+  // Everything else keeps its real API error and stays an ordinary failure.
+  return { kind: 'other', code, httpStatus: status };
+}
+
+function stableStringify(value) {
+  if (value === null || typeof value !== 'object') {
+    return JSON.stringify(value ?? null);
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map(stableStringify).join(',')}]`;
+  }
+  return `{${Object.keys(value).sort().map((k) => `${JSON.stringify(k)}:${stableStringify(value[k])}`).join(',')}}`;
+}
+
+function fingerprint(parts) {
+  return crypto.createHash('sha256').update(stableStringify(parts)).digest('hex').slice(0, 32);
+}
+
+// What the user is shown. Identity, the real error, both revisions, the source version, and
+// the fields that would change — including whole-array replacements, which are the ones most
+// likely to destroy Wix-only data (for Products, arrays require complete intended
+// contents).
+function buildConflictReview({
+  sourceStableKey,
+  targetId,
+  entity,
+  error,
+  savedTargetRevision = null,
+  currentTargetRevision = null,
+  sourceVersion = null,
+  sourceHash = null,
+  proposedFields = {},
+  currentTargetValues = {},
+  entityConflictCodes = null,
+  sentRevision = true,
+} = {}) {
+  if (!sourceStableKey || !targetId) {
+    throw new Error('buildConflictReview: sourceStableKey and targetId are required');
+  }
+  // A review is only ever built for a call that carried a revision, so sentRevision defaults true.
+  const classification = classifyUpdateError(error, { entityConflictCodes, sentRevision });
+  const changes = [];
+  for (const key of Object.keys(proposedFields).sort()) {
+    const to = proposedFields[key];
+    const from = currentTargetValues[key];
+    const replacesArray = Array.isArray(to);
+    if (stableStringify(from) === stableStringify(to)) {
+      continue;
+    }
+    changes.push({
+      field: key,
+      currentWixValue: from,
+      proposedValue: to,
+      // Flagged because an array write is a replacement, not a merge: anything present in Wix
+      // and absent from `to` disappears.
+      replacesEntireArray: replacesArray,
+    });
+  }
+  const review = {
+    entity: entity || null,
+    sourceStableKey,
+    targetId,
+    classification,
+    error: {
+      code: classification.code,
+      httpStatus: classification.httpStatus,
+      message: (error && (error.message || error.msg)) || null,
+    },
+    savedTargetRevision: savedTargetRevision || null,
+    reviewedTargetRevision: currentTargetRevision || null,
+    sourceVersion: sourceVersion ?? null,
+    sourceHash: sourceHash ?? null,
+    changes,
+    // Approval binds to the source values, the proposed writes AND the reviewed Wix
+    // revision together. Any of the three moving invalidates it.
+    bindingFingerprint: fingerprint({
+      sourceStableKey,
+      targetId,
+      sourceVersion: sourceVersion ?? null,
+      sourceHash: sourceHash ?? null,
+      proposedFields,
+      reviewedTargetRevision: currentTargetRevision || null,
+    }),
+  };
+  return review;
+}
+
+// Record the user's answer. `choice` is asked once for the presented record, never per
+// field. No answer at all is not modelled here on purpose — an unanswered conflict stays
+// unresolved, which is the absence of a record rather than a third choice.
+function recordConflictDecision({ review, choice, decidedBy = null, decidedAt = null } = {}) {
+  if (!review || !review.bindingFingerprint) {
+    throw new Error('recordConflictDecision: a review from buildConflictReview is required');
+  }
+  if (!CONFLICT_CHOICES.has(choice)) {
+    throw new Error(`recordConflictDecision: choice must be one of ${Array.from(CONFLICT_CHOICES).join(', ')}`);
+  }
+  return {
+    kind: 'rerun_conflict_decision',
+    choice,
+    sourceStableKey: review.sourceStableKey,
+    targetId: review.targetId,
+    entity: review.entity,
+    sourceVersion: review.sourceVersion,
+    sourceHash: review.sourceHash,
+    reviewedTargetRevision: review.reviewedTargetRevision,
+    bindingFingerprint: review.bindingFingerprint,
+    decidedBy: decidedBy || null,
+    decidedAt: decidedAt || null,
+  };
+}
+
+// An approval authorizes exactly the write that was reviewed. Re-checked immediately before
+// the retry — if the source changed again, or Wix moved again, or the proposed body differs, the
+// answer no longer applies and the user is asked again.
+function approvalApplies({ decision, review } = {}) {
+  if (!decision || !review) {
+    return { applies: false, reason: 'missing_decision_or_review' };
+  }
+  if (decision.sourceStableKey !== review.sourceStableKey || decision.targetId !== review.targetId) {
+    return { applies: false, reason: 'different_record' };
+  }
+  if (decision.bindingFingerprint !== review.bindingFingerprint) {
+    return { applies: false, reason: 'reviewed_state_changed' };
+  }
+  return { applies: true, reason: 'binding_matches', choice: decision.choice };
+}
+
+// The override write plan. It uses the revision the user actually reviewed — never an
+// omitted revision, and never a freshly fetched one the user never saw.
+function buildOverrideWritePlan({ decision, review } = {}) {
+  const check = approvalApplies({ decision, review });
+  if (!check.applies) {
+    return { ok: false, reason: check.reason, askAgain: true };
+  }
+  if (decision.choice !== 'override') {
+    return { ok: false, reason: 'not_an_override_decision', askAgain: false };
+  }
+  if (!review.reviewedTargetRevision) {
+    // Without a reviewed revision there is nothing to write against, and omitting the revision
+    // is exactly the unguarded overwrite this flow forbids.
+    return { ok: false, reason: 'no_reviewed_revision', askAgain: true };
+  }
+  return {
+    ok: true,
+    targetId: review.targetId,
+    revision: review.reviewedTargetRevision,
+    fields: review.changes.reduce((acc, change) => {
+      acc[change.field] = change.proposedValue;
+      return acc;
+    }, {}),
+  };
+}
+
+// A keep-Wix answer is remembered against the exact source change and the exact Wix
+// state that were reviewed — and it lives in the recovery log, NOT as a crosswalk baseline,
+// because the source version was never applied to Wix. Reusing it more broadly would silently
+// swallow a later, different change.
+function keepDecisionApplies({ decision, sourceVersion = null, sourceHash = null, currentTargetRevision = null } = {}) {
+  if (!decision || decision.choice !== 'keep') {
+    return { applies: false, reason: 'not_a_keep_decision' };
+  }
+  const sameSourceChange = stableStringify(decision.sourceVersion ?? null) === stableStringify(sourceVersion ?? null)
+    && stableStringify(decision.sourceHash ?? null) === stableStringify(sourceHash ?? null);
+  if (!sameSourceChange) {
+    return { applies: false, reason: 'new_source_change' };
+  }
+  if (stableStringify(decision.reviewedTargetRevision ?? null) !== stableStringify(currentTargetRevision ?? null)) {
+    return { applies: false, reason: 'wix_changed_again' };
+  }
+  return { applies: true, reason: 'same_source_change_and_wix_state' };
+}
+
+module.exports = {
+  REVISION_CONFLICT_CODES,
+  OBSERVED_REVISION_CONFLICT_CODES,
+  UPDATE_DENIED_ENTITIES,
+  updateSupportFor,
+  CONFLICT_CHOICES,
+  classifyUpdateError,
+  buildConflictReview,
+  recordConflictDecision,
+  approvalApplies,
+  buildOverrideWritePlan,
+  keepDecisionApplies,
+};