@wix/agent-skills 1.36.0 → 1.36.1

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

@@ -1,94 +0,0 @@
-'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

@@ -1,107 +0,0 @@
-'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

@@ -1,81 +0,0 @@
-'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

@@ -1,334 +0,0 @@
-'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,
-};