@wix/agent-skills 1.33.0 → 1.34.0

package/skills/wix-replatform/resources/rp-target-wix/lib/stores-category-attach.js

@@ -0,0 +1,221 @@
+'use strict';
+
+// Product category attachment: write, then verify -- the identical discipline
+// stores-inventory.js already applies to stock, now applied to the category-membership link.
+//
+// THE FAILURE THIS GUARDS AGAINST: a generated importer's call site passed
+// `bulkAddItemToCategories(wix, categoryIds, [productId])` -- THREE positional arguments to a
+// function declared `(wix, payload)`. JS drops the extra argument silently, so `payload` became
+// the bare `categoryIds` array; destructuring `{ productId, categoryIds }` off an array yields
+// `undefined` for both fields on every single call. Every request this importer ever sent to
+// `/categories/v1/bulk/categories/add-item` carried two undefined required fields. Wix almost
+// certainly rejected every one, and the call site's own `catch {}` swallowed every failure with a
+// comment that falsely claimed it was "reported via completion mismatch" -- nothing tracked this
+// step at all, so the loss was invisible end to end: no retro, no QA, no completion-report
+// mismatch, ever. This file exists so that failure mode cannot recur unseen: the write call below
+// takes the exact shape the writer declares, and nothing is marked attached until a fresh read
+// confirms it.
+//
+// `bulkAddItemToCategories` is an ADD, not a replace/set -- a product may legitimately carry other
+// category memberships from elsewhere (or from an earlier partial run). The read-back check below
+// only ever confirms "every expected categoryId is present in the actual set", never exact
+// equality; never do a set-equality check here.
+
+const w = require('./wix-writers.js');
+
+const OUTCOMES = ['category-attach-written', 'category-attach-reconciled-existing', 'category-attach-unverified', 'category-attach-failed'];
+
+function identity(value, name) {
+  if (typeof value !== 'string' || !value.trim()) throw new Error(`Category attachment requires ${name}`);
+  return value;
+}
+
+// A row exists only for a product that needs at least one category attached. A product with
+// nothing to attach is never given a row at all -- it is not a gap, there is nothing orthogonal
+// to track -- so an empty/missing categoryIds array is a caller bug, not a valid empty state.
+function categoryIdsOf(value) {
+  if (!Array.isArray(value) || !value.length) {
+    throw new Error('Category attachment requires at least one categoryId; a product with nothing to attach should not be passed as a row');
+  }
+  return [...new Set(value.map((id, index) => identity(id, `categoryIds[${index}]`)))];
+}
+
+function hasAllCategories(actual, expected) {
+  if (!actual) return false;
+  return expected.every((id) => actual.has(id));
+}
+
+// VERIFIED (2026-08-12, wix-writers.js queryAllStoresProducts): `fields: ['DIRECT_CATEGORIES_INFO']`
+// as a sibling of `query` (not nested inside it) on POST /stores/v3/products/query returns
+// `directCategoriesInfo.categories[]` per product; a plain query omits categories entirely. The
+// per-item shape of that array is not itself pinned down by that verification, so this treats an
+// entry as either a bare category-id string or an `{ id }` object and takes whichever is present
+// -- defensive, not a guess that silently drops a real id either way.
+async function queryOneProductCategories(wix, productId) {
+  const response = await wix.send(w.buildQueryStoresProductsRequest(
+    { filter: { id: { $eq: productId } }, cursorPaging: { limit: 1 } },
+    ['DIRECT_CATEGORIES_INFO'],
+  ));
+  if (!response || !Array.isArray(response.products)) throw new Error('Malformed category query response');
+  const product = response.products.find((p) => p && p.id === productId);
+  if (!product) return null;
+  const categories = (product.directCategoriesInfo && Array.isArray(product.directCategoriesInfo.categories))
+    ? product.directCategoriesInfo.categories : [];
+  return new Set(categories.map((c) => (typeof c === 'string' ? c : c && c.id)).filter(Boolean));
+}
+
+// Best-effort only: a failed or inconclusive pre-read never blocks the write path, it only costs
+// the no-write optimization below. Correctness lives entirely in the post-write verify step.
+async function preCheckExisting(wix, rows) {
+  const pending = rows.slice();
+  let index = 0;
+  async function worker() {
+    while (index < pending.length) {
+      const row = pending[index++];
+      try {
+        const actual = await queryOneProductCategories(wix, row.productId);
+        if (hasAllCategories(actual, row.categoryIds)) row.alreadySatisfied = true;
+      } catch { /* unknown -- fall through to the write path */ }
+    }
+  }
+  await Promise.all(Array.from({ length: Math.min(4, pending.length) }, () => worker()));
+}
+
+// A write receipt is never proof -- see stores-inventory.js's verifyCatalogInventory for the same
+// discipline applied to stock. Bounded retries, worker-pool concurrency, independent per product.
+async function verifyCategoryAttachment(wix, rows, { verifyAttempts = 3, sleep = (ms) => new Promise((r) => setTimeout(r, ms)) } = {}) {
+  const pending = rows.slice();
+  let index = 0;
+  async function worker() {
+    while (index < pending.length) {
+      const row = pending[index++];
+      for (let attempt = 0; attempt < verifyAttempts; attempt++) {
+        try {
+          const actual = await queryOneProductCategories(wix, row.productId);
+          if (hasAllCategories(actual, row.categoryIds)) {
+            row.outcome = 'category-attach-written';
+            delete row.error;
+            break;
+          }
+          row.outcome = 'category-attach-unverified';
+          row.error = actual ? 'Category read-back is missing one or more expected categoryIds' : 'Product missing from category read-back';
+        } catch (error) {
+          row.outcome = 'category-attach-unverified';
+          row.error = error.message;
+        }
+        if (attempt + 1 < verifyAttempts) await sleep(250 * (attempt + 1));
+      }
+    }
+  }
+  await Promise.all(Array.from({ length: Math.min(4, pending.length) }, () => worker()));
+}
+
+// rows: [{ productId, categoryIds, sourceKey? }] -- one row per product needing at least one
+// category attached. Never swallows a write error silently: every per-row failure is caught,
+// recorded with its message, and left `failed` rather than disappearing into a wrapping catch.
+async function reconcileCategoryAttachment(wix, rows, { verifyAttempts = 3, sleep = (ms) => new Promise((r) => setTimeout(r, ms)) } = {}) {
+  if (!Array.isArray(rows)) throw new Error('Category attachment rows must be an array');
+  if (!Number.isInteger(verifyAttempts) || verifyAttempts < 1 || verifyAttempts > 5) throw new Error('verifyAttempts must be 1-5');
+  const seen = new Set();
+  const normalized = rows.map((row, index) => {
+    if (!row || typeof row !== 'object' || Array.isArray(row)) throw new Error(`Category attachment rows[${index}] must be an object`);
+    const productId = identity(row.productId, 'productId');
+    if (seen.has(productId)) throw new Error('Duplicate input product identity');
+    seen.add(productId);
+    const categoryIds = categoryIdsOf(row.categoryIds);
+    const sourceKey = row.sourceKey === undefined || row.sourceKey === null ? null : identity(row.sourceKey, 'sourceKey');
+    return { productId, categoryIds, sourceKey, outcome: 'category-attach-unverified' };
+  });
+  if (!normalized.length) return buildCategoryAttachReport(normalized);
+
+  // Step 1: skip the write for a product whose existing categories already satisfy the intended
+  // set -- the "reconciled-existing" twin of stores-inventory's no-write rerun.
+  await preCheckExisting(wix, normalized);
+  const pending = [];
+  for (const row of normalized) {
+    if (row.alreadySatisfied) { row.outcome = 'category-attach-reconciled-existing'; delete row.alreadySatisfied; }
+    else pending.push(row);
+  }
+
+  // Step 2: write. The endpoint takes exactly ONE item plus its category ids -- never a batch of
+  // products -- so a per-row try/catch IS the correlation; there is no bulk response to misread.
+  // This is the exact call the failure above got wrong: { productId, categoryIds }, nothing else.
+  const written = [];
+  for (const row of pending) {
+    try {
+      await w.bulkAddItemToCategories(wix, { productId: row.productId, categoryIds: row.categoryIds });
+      written.push(row);
+    } catch (error) {
+      row.outcome = 'category-attach-failed';
+      row.error = error.message;
+    }
+  }
+
+  // Step 3: read-back verify. Never mark a row attached off the write call's own success alone.
+  await verifyCategoryAttachment(wix, written, { verifyAttempts, sleep });
+
+  return buildCategoryAttachReport(normalized);
+}
+
+function buildCategoryAttachReport(rows) {
+  const counts = Object.fromEntries(OUTCOMES.map((key) => [key, 0]));
+  for (const row of rows) {
+    if (!OUTCOMES.includes(row.outcome)) throw new Error('Unknown category-attach outcome');
+    counts[row.outcome]++;
+  }
+  return {
+    rows,
+    counts,
+    complete: rows.length > 0 && counts['category-attach-failed'] === 0 && counts['category-attach-unverified'] === 0,
+    status: rows.length === 0 ? 'no-data' : (counts['category-attach-failed'] || counts['category-attach-unverified']) ? 'partial' : 'complete',
+  };
+}
+
+async function persistCategoryAttachReport(file, report) {
+  const fs = require('node:fs/promises');
+  const path = require('node:path');
+  const crypto = require('node:crypto');
+  await fs.mkdir(path.dirname(file), { recursive: true });
+  const temp = `${file}.${crypto.randomUUID()}.tmp`;
+  try {
+    await fs.writeFile(temp, `${JSON.stringify(report, null, 2)}\n`, { mode: 0o600 });
+    await fs.rename(temp, file);
+  } finally { await fs.rm(temp, { force: true }); }
+}
+
+// Turns a buildCategoryAttachReport() result into stageResiduals[] rows -- the orthogonal-axis
+// mechanism completion-report.js already applies to orders' payment/refund/invoice sub-stages
+// (see its doctrine comment above STAGE_RESIDUAL_OUTCOMES). A product whose import the entity row
+// already counts as `imported` can still carry zero of its categories; the completeness arithmetic
+// cannot see that on its own, so this is what makes it visible. Only ever emitted for the two
+// failure-shaped outcomes -- a product that attached cleanly, or already carried its categories,
+// contributes no residual row at all.
+//
+// `sourceKey` is optional on an input row (see reconcileCategoryAttachment's normalization), but a
+// residual group must always carry SOME identifier a human/operator can act on -- a nonzero
+// `count` with an empty `sourceKeys[]` is unactionable. `productId` is always present on every
+// row (it is required, never optional), so it is the fallback identifier when no sourceKey was
+// supplied: a target id is still enough to act on, and silently dropping it would be strictly
+// worse.
+function collectCategoryAttachStageResiduals(report, { entity = 'product', stage = 'category-attach' } = {}) {
+  if (!report || !Array.isArray(report.rows)) throw new Error('category-attach report rows must be an array');
+  const groups = new Map();
+  for (const row of report.rows) {
+    if (row.outcome !== 'category-attach-unverified' && row.outcome !== 'category-attach-failed') continue;
+    if (!groups.has(row.outcome)) groups.set(row.outcome, { entity, stage, outcome: row.outcome, count: 0, sourceKeys: new Set() });
+    const group = groups.get(row.outcome);
+    group.count += 1;
+    group.sourceKeys.add(row.sourceKey || row.productId);
+  }
+  return [...groups.values()].map((row) => ({ ...row, sourceKeys: [...row.sourceKeys] }));
+}
+
+module.exports = {
+  OUTCOMES,
+  hasAllCategories,
+  queryOneProductCategories,
+  reconcileCategoryAttachment,
+  buildCategoryAttachReport,
+  persistCategoryAttachReport,
+  collectCategoryAttachStageResiduals,
+};

package/skills/wix-replatform/resources/rp-target-wix/lib/stores-inventory.js

@@ -0,0 +1,248 @@
+'use strict';
+
+const BASE = 'https://www.wixapis.com/stores/v3';
+const own = (obj, key) => Object.prototype.hasOwnProperty.call(obj, key);
+const BATCH_LIMIT = 1000;
+const OUTCOMES = ['reconciled', 'created', 'updated', 'failed', 'unverified'];
+
+// Inventory's tracking method is a oneof. trackQuantity is derived, never writable.
+function stockPayload(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('Inventory needs an explicit tracking method');
+  if (Object.keys(value).some((key) => !['inStock', 'quantity', 'trackQuantity'].includes(key))) throw new Error('Unsupported inventory stock field');
+  const hasStock = own(value, 'inStock');
+  const hasQuantity = own(value, 'quantity');
+  if (hasStock === hasQuantity) throw new Error('Inventory needs exactly one of inStock or quantity');
+  if (hasStock && typeof value.inStock !== 'boolean') throw new Error('inStock must be boolean');
+  if (hasQuantity && (!Number.isInteger(value.quantity) || value.quantity < 0 || value.quantity > 99999)) {
+    throw new Error('Inventory quantity must be an integer from 0 to 99999');
+  }
+  if (own(value, 'trackQuantity') && value.trackQuantity !== hasQuantity) throw new Error('Conflicting trackQuantity');
+  return hasStock ? { inStock: value.inStock } : { quantity: value.quantity };
+}
+
+function inventoryForVariant(variant, { inStock } = {}) {
+  const has = (key) => own(variant, key) && variant[key] != null && variant[key] !== '';
+  if (has('inventoryTracked') && typeof variant.inventoryTracked !== 'boolean') throw new Error('inventoryTracked must be boolean');
+  if (has('inStock') && typeof variant.inStock !== 'boolean') throw new Error('inStock must be boolean');
+  if (variant.inventoryTracked === true || (has('inventoryQuantity') && variant.inventoryTracked !== false)) {
+    const result = stockPayload({ quantity: variant.inventoryQuantity });
+    if (has('inStock') && variant.inStock !== (result.quantity > 0)) throw new Error('Conflicting inventory status and quantity');
+    return result;
+  }
+  if (variant.inventoryTracked === false && has('inventoryQuantity')) throw new Error('Untracked inventory cannot carry a quantity');
+  if (has('inStock')) return stockPayload({ inStock: variant.inStock });
+  if (variant.inventoryTracked === false) throw new Error('Untracked inventory needs explicit inStock');
+  if (inStock !== undefined) return stockPayload({ inStock });
+  return null;
+}
+
+function identity(value, name) {
+  if (typeof value !== 'string' || !value.trim()) throw new Error(`Inventory requires ${name}`);
+  return value;
+}
+
+async function resolveInventoryLocationDetails(wix, locationId) {
+  const filter = locationId ? { id: identity(locationId, 'locationId') } : { defaultLocation: true };
+  const response = await wix.send(require('./wix-writers').buildQueryInventoryLocationsRequest(filter));
+  const rows = response && response.storesLocations;
+  if (!Array.isArray(rows) || rows.length !== 1 || !rows[0].id ||
+      (locationId ? rows[0].id !== locationId : rows[0].defaultLocation !== true)) {
+    throw new Error('Inventory location must resolve to exactly one matching Stores location');
+  }
+  if (typeof rows[0].defaultLocation !== 'boolean') throw new Error('Stores location omitted its default-location status');
+  return rows[0];
+}
+
+async function resolveInventoryLocation(wix, locationId) {
+  return (await resolveInventoryLocationDetails(wix, locationId)).id;
+}
+
+// Complete, bounded read: missing payloads and repeating cursors never mean an empty target.
+async function readInventory(wix, rows, locationId) {
+  const wanted = new Map(rows.map((r) => [r.variantId, r]));
+  const found = new Map();
+  const cursors = new Set();
+  let cursor;
+  do {
+    const response = await wix.send(require('./wix-writers').buildQueryInventoryItemsRequest({ ...(!cursor ? { filter: { variantId: { $in: [...wanted.keys()] }, locationId } } : {}), cursorPaging: { limit: BATCH_LIMIT, ...(cursor ? { cursor } : {}) } }));
+    if (!response || !Array.isArray(response.inventoryItems) || !response.pagingMetadata || typeof response.pagingMetadata !== 'object') throw new Error('Malformed inventory query response');
+    for (const item of response.inventoryItems) {
+      const expected = wanted.get(item.variantId);
+      if (!expected || item.productId !== expected.productId || item.locationId !== locationId || !item.id) {
+        throw new Error('Inventory query returned a mismatched identity');
+      }
+      if (found.has(item.variantId)) throw new Error('Duplicate inventory identity');
+      found.set(item.variantId, item);
+    }
+    cursor = response.pagingMetadata && response.pagingMetadata.cursors && response.pagingMetadata.cursors.next;
+    if (response.pagingMetadata.hasNext === true && !cursor) throw new Error('Inventory query omitted its next cursor');
+    if (cursor && (typeof cursor !== 'string' || cursors.has(cursor))) throw new Error('Invalid inventory paging cursor');
+    if (cursor) cursors.add(cursor);
+    // At most one row per requested variant/location. A full extra page cannot be legitimate.
+    if (cursors.size > rows.length + 1) throw new Error('Inventory query exceeded its bounded population');
+  } while (cursor);
+  return found;
+}
+
+function matchesInventory(item, inventory) {
+  if (!item || (item.preorderInfo && item.preorderInfo.enabled)) return false;
+  const tracked = own(inventory, 'quantity');
+  const available = tracked ? inventory.quantity > 0 : inventory.inStock;
+  return item.trackQuantity === tracked &&
+    (tracked ? item.quantity === inventory.quantity : item.inStock === inventory.inStock) &&
+    item.availabilityStatus === (available ? 'IN_STOCK' : 'OUT_OF_STOCK');
+}
+
+// Catalog is a separate event-driven projection of default-location inventory.
+// Check exact variant IDs even on no-write reruns; never rewrite stock to force propagation.
+async function verifyCatalogInventory(wix, rows, { verifyAttempts = 3, sleep = (ms) => new Promise((r) => setTimeout(r, ms)) } = {}) {
+  const groups = new Map();
+  for (const row of rows) {
+    if (!['reconciled', 'created', 'updated'].includes(row.outcome)) continue;
+    if (!groups.has(row.productId)) groups.set(row.productId, []);
+    groups.get(row.productId).push({ row, inventoryOutcome: row.outcome });
+  }
+  const pending = [...groups.entries()];
+  let index = 0;
+  async function worker() {
+    while (index < pending.length) {
+      const [productId, entries] = pending[index++];
+      for (let attempt = 0; attempt < verifyAttempts; attempt++) {
+        try {
+          const response = await wix.send(require('./wix-writers').buildGetStoresProductRequest(productId));
+          const product = response && response.product;
+          if (!product || product.id !== productId || !product.variantsInfo || !Array.isArray(product.variantsInfo.variants)) {
+            throw new Error('Catalog read omitted the expected product/variants');
+          }
+          const variants = new Map();
+          for (const variant of product.variantsInfo.variants) {
+            if (!variant.id || variants.has(variant.id)) throw new Error('Catalog read returned invalid or duplicate variant identity');
+            variants.set(variant.id, variant);
+          }
+          for (const { row, inventoryOutcome } of entries) {
+            const variant = variants.get(row.variantId);
+            const expected = own(row.inventory, 'quantity') ? row.inventory.quantity > 0 : row.inventory.inStock;
+            const status = variant && variant.inventoryStatus;
+            const matches = status && status.inStock === expected && status.preorderEnabled === false;
+            row.catalogVerification = { status: matches ? 'verified' : 'unverified', expectedInStock: expected,
+              actualInStock: status && typeof status.inStock === 'boolean' ? status.inStock : null };
+            row.outcome = matches ? inventoryOutcome : 'unverified';
+            if (matches) delete row.error;
+            else row.error = 'Catalog variant availability does not confirm default-location inventory';
+          }
+          if (entries.every(({ row }) => row.catalogVerification.status === 'verified')) break;
+        } catch (error) {
+          for (const { row } of entries) Object.assign(row, { outcome: 'unverified', error: error.message, catalogVerification: { status: 'unverified' } });
+        }
+        if (attempt + 1 < verifyAttempts) await sleep(500 * (attempt + 1));
+      }
+    }
+  }
+  await Promise.all(Array.from({ length: Math.min(4, pending.length) }, () => worker()));
+  return rows;
+}
+
+function correlateBulk(response, input) {
+  const bulk = require('./bulk-results');
+  const result = bulk.correlateBulk(response, input, bulk.adapters.inventory);
+  if (result.defects.length || result.unaccounted || result.undetailedFailures) {
+    throw new Error('Inventory bulk response has invalid correlation or does not account for every input');
+  }
+  return result.results.map(r => ({ row: r.input, success: r.success, error: r.raw.itemMetadata.error || null }));
+}
+
+function buildInventoryReport(rows, gaps = []) {
+  const counts = Object.fromEntries(OUTCOMES.map((key) => [key, 0]));
+  for (const row of rows) {
+    if (!OUTCOMES.includes(row.outcome)) throw new Error('Unknown inventory outcome');
+    counts[row.outcome]++;
+  }
+  counts['decision-needed'] = gaps.length;
+  return { rows, gaps, counts, intended: rows.length + gaps.length,
+    complete: rows.length > 0 && counts.failed === 0 && counts.unverified === 0 && gaps.length === 0,
+    status: rows.length + gaps.length === 0 ? 'no-data' : counts.failed || counts.unverified || gaps.length ? 'partial' : 'complete' };
+}
+
+async function persistInventoryReport(file, report) {
+  const fs = require('node:fs/promises');
+  const path = require('node:path');
+  const crypto = require('node:crypto');
+  await fs.mkdir(path.dirname(file), { recursive: true });
+  const temp = `${file}.${crypto.randomUUID()}.tmp`;
+  try {
+    await fs.writeFile(temp, `${JSON.stringify(report, null, 2)}\n`, { mode: 0o600 });
+    await fs.rename(temp, file);
+  } finally { await fs.rm(temp, { force: true }); }
+}
+
+// Input IDs come from the product/variant crosswalk, including products created on earlier runs.
+// Query and verify even after inline product/inventory create; a product receipt isn't stock proof.
+async function reconcileInventory(wix, input, { locationId, gaps = [], expectedCount, verifyAttempts = 3, sleep = (ms) => new Promise((r) => setTimeout(r, ms)) } = {}) {
+  if (!Array.isArray(input) || !Array.isArray(gaps)) throw new Error('Inventory rows and gaps must be arrays');
+  if (!Number.isInteger(expectedCount) || expectedCount < 0 || expectedCount !== input.length + gaps.length) {
+    throw new Error('Inventory rows and gaps must account for the explicit source-variant expectedCount');
+  }
+  if (!Number.isInteger(verifyAttempts) || verifyAttempts < 1 || verifyAttempts > 5) throw new Error('verifyAttempts must be 1–5');
+  const seen = new Set();
+  const rows = input.map((row) => {
+    const productId = identity(row.productId, 'productId');
+    const variantId = identity(row.variantId, 'variantId');
+    if (seen.has(variantId)) throw new Error('Duplicate input variant identity');
+    seen.add(variantId);
+    return { productId, variantId, inventory: stockPayload(row.inventory), outcome: 'unverified' };
+  });
+  if (!rows.length) return buildInventoryReport(rows, gaps);
+  let resolved, isDefault;
+  try { const location = await resolveInventoryLocationDetails(wix, locationId); resolved = location.id; isDefault = location.defaultLocation; }
+  catch (error) { return buildInventoryReport(rows.map((r) => ({ ...r, outcome: 'failed', error: error.message })), gaps); }
+  for (let start = 0; start < rows.length; start += BATCH_LIMIT) {
+    const batch = rows.slice(start, start + BATCH_LIMIT);
+    let existing;
+    try { existing = await readInventory(wix, batch, resolved); }
+    catch (error) { for (const row of batch) Object.assign(row, { outcome: 'failed', error: error.message }); continue; }
+    const create = [], update = [];
+    for (const row of batch) {
+      row.locationId = resolved;
+      const item = existing.get(row.variantId);
+      if (item && item.preorderInfo && item.preorderInfo.enabled) {
+        Object.assign(row, { outcome: 'failed', error: 'Existing preorder policy requires a mapping decision' });
+      } else if (matchesInventory(item, row.inventory)) {
+        Object.assign(row, { outcome: 'reconciled', inventoryItemId: item.id });
+      } else if (!item) create.push(row);
+      else if (item.revision == null) Object.assign(row, { outcome: 'failed', error: 'Inventory update needs a current revision' });
+      else { row.inventoryItemId = item.id; row.revision = item.revision; update.push(row); }
+    }
+    for (const [operation, pending] of [['create', create], ['update', update]]) {
+      if (!pending.length) continue;
+      try {
+        const inventoryItems = pending.map((row) => operation === 'create'
+          ? { productId: row.productId, variantId: row.variantId, locationId: resolved, ...row.inventory }
+          : { inventoryItem: { id: row.inventoryItemId, revision: row.revision, ...row.inventory } });
+        const response = await wix.send(require('./wix-writers').buildBulkInventoryItemsRequest(operation, inventoryItems));
+        for (const result of correlateBulk(response, pending)) {
+          if (result.success) result.row.writeOutcome = operation === 'create' ? 'created' : 'updated';
+          else Object.assign(result.row, { outcome: 'failed', error: result.error || 'Inventory item write failed' });
+        }
+      } catch (error) { for (const row of pending) Object.assign(row, { outcome: 'failed', error: error.message }); }
+    }
+    const written = batch.filter((r) => r.writeOutcome && r.outcome !== 'failed');
+    if (!written.length) continue;
+    for (let attempt = 0; attempt < verifyAttempts; attempt++) {
+      try {
+        const back = await readInventory(wix, written, resolved);
+        for (const row of written) {
+          const item = back.get(row.variantId);
+          if (matchesInventory(item, row.inventory)) { Object.assign(row, { outcome: row.writeOutcome, inventoryItemId: item.id }); delete row.error; delete row.inventoryVerification; }
+          else Object.assign(row, { outcome: 'unverified', error: item ? 'Inventory read-back differs from intended tracking, stock or availability' : 'Inventory item missing from read-back', inventoryVerification: { expected: row.inventory, actual: item ? { trackQuantity: item.trackQuantity, inStock: item.inStock, quantity: item.quantity, availabilityStatus: item.availabilityStatus } : null } });
+        }
+        if (written.every((r) => r.outcome !== 'unverified')) break;
+      } catch (error) { for (const row of written) Object.assign(row, { outcome: 'unverified', error: error.message }); }
+      if (attempt + 1 < verifyAttempts) await sleep(250 * (attempt + 1));
+    }
+  }
+  if (isDefault) await verifyCatalogInventory(wix, rows, { verifyAttempts, sleep });
+  else for (const row of rows) row.catalogVerification = { status: 'not-applicable', reason: 'non-default-location' };
+  return buildInventoryReport(rows, gaps);
+}
+
+module.exports = { stockPayload, inventoryForVariant, resolveInventoryLocation, readInventory, matchesInventory, verifyCatalogInventory, correlateBulk, reconcileInventory, buildInventoryReport, persistInventoryReport, BATCH_LIMIT };

package/skills/wix-replatform/resources/rp-target-wix/lib/stores-verification.js

@@ -3,6 +3,7 @@
 const fs = require('fs');
 const path = require('path');
 const w = require('./wix-writers');
+const verification = require('./write-verification');
 
 const DEFAULT_VERIFIED_SUBSCRIPTION_PATHS = [
   'product.subscriptionDetails',
@@ -115,18 +116,23 @@ async function verifyStoresSubscriptionCreate({ wix, siteId, artifactPath, probe
 
   let createdProduct;
   try {
+    const expected = verification.subscriptionExpected(createRequest.body.product);
     createdProduct = (await wix.send(createRequest)).product;
     artifact.probeRecordId = createdProduct && createdProduct.id;
-    if (!artifact.probeRecordId) throw new Error('create response did not include product.id');
+    if (!require('./bulk-results').opaqueId(artifact.probeRecordId) || createdProduct._dryRunPlaceholder) throw new Error('create response did not include a live product.id');
+    artifact.valueEvidence = { expected, targetId: artifact.probeRecordId, actual: null };
+    await writeArtifact(artifactPath, artifact);
 
     const getRequest = w.buildGetStoresProductRequest(artifact.probeRecordId);
     artifact.readback = { endpoint: getRequest.url, method: getRequest.method };
     const readProduct = (await wix.send(getRequest)).product;
     artifact.verifiedPaths = verifyPaths({ product: readProduct }, DEFAULT_VERIFIED_SUBSCRIPTION_PATHS);
     artifact.constraintsDiscovered = w.STORES_SUBSCRIPTION_CONTRACT.constraints.map((constraint) => ({ ...constraint }));
-    artifact.status = artifact.verifiedPaths.every((entry) => entry.present) ? 'passed' : 'failed';
+    artifact.valueEvidence.actual = readProduct;
+    artifact.comparison = verification.verifySubscriptionEvidence(artifact.valueEvidence);
+    artifact.status = artifact.comparison.verified ? 'passed' : 'failed';
     if (artifact.status === 'failed') {
-      artifact.warnings.push('Subscription readback did not include every expected nested path.');
+      artifact.warnings.push('Subscription readback identity or values do not match the submitted product.');
     }
   } catch (error) {
     artifact.status = 'failed';
@@ -225,6 +231,82 @@ async function verifyStoresDeleteProbe({ wix, siteId, artifactPath, productId }
   return writeArtifact(artifactPath, artifact);
 }
 
+// Runs only against an explicitly selected, already-muted test target. All products are
+// synthetic and hidden. The artifact is saved as IDs are acquired so cleanup is recoverable.
+async function verifyStoresInventoryImport({ wix, siteId, artifactPath } = {}) {
+  const inventory = require('./stores-inventory.js');
+  const build = require('./wix-build.js');
+  const artifact = artifactBase({ command: 'stores inventory-import', siteId, endpoint: '/stores/v3/bulk/inventory-items/create', method: 'POST' });
+  artifact.probeProductIds = [];
+  artifact.checks = [];
+  let stockWrites = 0;
+  const client = wix;
+  wix = { ...client, send(request) {
+    if (request.method !== 'GET' && /\/inventory-items(?:\/|$)/.test(request.url) && !request.url.endsWith('/query')) stockWrites++;
+    return client.send(request);
+  } };
+  const check = (name, passed, detail) => {
+    artifact.checks.push({ name, passed, detail });
+    writeArtifact(artifactPath, artifact);
+    if (!passed) throw new Error(`Inventory probe failed: ${name}`);
+  };
+  const marker = `inventory-probe-${Date.now()}`;
+  const payload = (index, stock) => build.buildProduct({ name: `${marker}-${index}`, visible: false, productType: 'PHYSICAL', variants: [{ price: 1, ...(stock || {}) }] });
+  try {
+    const mute = await w.getSiteMuteState(wix);
+    if (!mute || mute.muted !== true) throw new Error('Inventory probe requires an already-muted disposable test target');
+    const locationId = await inventory.resolveInventoryLocation(wix);
+    const rows = [];
+    for (const [index, state] of [{ inStock: true }, { inStock: false }, { quantity: 0 }, { quantity: 7 }].entries()) {
+      const product = await w.createStoresProduct(wix, payload(index));
+      if (!product || !product.id) throw new Error('Probe product create returned no identity');
+      artifact.probeProductIds.push(product.id); writeArtifact(artifactPath, artifact);
+      const variants = product.variantsInfo && product.variantsInfo.variants;
+      if (!Array.isArray(variants) || variants.length !== 1 || !variants[0].id) throw new Error('Probe product did not return one variant identity');
+      rows.push({ productId: product.id, variantId: variants[0].id, inventory: state });
+    }
+    const created = await inventory.reconcileInventory(wix, rows, { locationId, expectedCount: 4, verifyAttempts: 5 });
+    check('mixed stock create and read-back', created.complete && created.counts.created === 4, created);
+    const changed = rows.map((r, i) => ({ ...r, inventory: i % 2 ? { inStock: false } : { quantity: 3 } }));
+    const updated = await inventory.reconcileInventory(wix, changed, { locationId, expectedCount: 4, verifyAttempts: 5 });
+    check('revisioned updates and tracking-mode changes', updated.complete && updated.counts.updated === 3, updated);
+    const beforeRerun = stockWrites;
+    const rerun = await inventory.reconcileInventory(wix, changed, { locationId, expectedCount: 4 });
+    check('matching rerun performs no stock writes', rerun.complete && rerun.counts.reconciled === 4 && stockWrites === beforeRerun, { ...rerun, observedStockWrites: stockWrites - beforeRerun });
+    const singleProduct = await w.createStoresProduct(wix, payload('single'));
+    if (!singleProduct || !singleProduct.id) throw new Error('Single probe missing product identity');
+    artifact.probeProductIds.push(singleProduct.id); writeArtifact(artifactPath, artifact);
+    const singleRow = { productId: singleProduct.id, variantId: singleProduct.variantsInfo.variants[0].id, inventory: { inStock: false } };
+    await w.createInventoryItem(wix, { productId: singleRow.productId, variantId: singleRow.variantId, inStock: false, trackQuantity: false });
+    const single = await inventory.reconcileInventory(wix, [singleRow], { locationId, expectedCount: 1 });
+    check('single-create helper and read-back', single.complete && single.counts.reconciled === 1, single);
+    const bulk = await w.bulkCreateStoresProductsWithInventory(wix, [payload('inline-false', { inStock: false }), payload('inline-quantity', { inventoryTracked: true, inventoryQuantity: 5 })], { returnEntity: true });
+    for (const result of bulk.results) if (result.success && result.productId) artifact.probeProductIds.push(result.productId);
+    writeArtifact(artifactPath, artifact);
+    check('inline bulk product creation', bulk.succeeded.length === 2 && bulk.unaccounted === 0, { successes: bulk.succeeded.length, unaccounted: bulk.unaccounted });
+    const inlineRows = bulk.succeeded.map((r) => {
+      const variants = r.product && r.product.variantsInfo && r.product.variantsInfo.variants;
+      if (!variants || variants.length !== 1 || !variants[0].id) throw new Error('Inline probe missing variant identity');
+      return { productId: r.productId, variantId: variants[0].id, inventory: r.inputProduct.variantsInfo.variants[0].inventoryItem };
+    });
+    const inline = await inventory.reconcileInventory(wix, inlineRows, { locationId, expectedCount: 2 });
+    check('inline stock persisted without repair', inline.complete && inline.counts.reconciled === 2, inline);
+    artifact.status = 'passed';
+  } catch (error) { artifact.status = 'failed'; artifact.error = error.message; }
+  finally {
+    artifact.cleanup = { attempted: artifact.probeProductIds.length > 0, status: artifact.probeProductIds.length ? 'deleted' : 'not_applicable', failedProductIds: [] };
+    for (const id of artifact.probeProductIds) {
+      try { await w.deleteStoresProduct(wix, id); }
+      catch (_) { artifact.cleanup.failedProductIds.push(id); }
+    }
+    if (artifact.cleanup.failedProductIds.length) {
+      artifact.cleanup.status = 'failed'; artifact.status = 'failed';
+      artifact.recoveryInstructions.push('Delete only the probe product IDs listed in cleanup.failedProductIds.');
+    }
+  }
+  return writeArtifact(artifactPath, artifact);
+}
+
 module.exports = {
   DEFAULT_VERIFIED_SUBSCRIPTION_PATHS,
   defaultProbeProduct,
@@ -235,4 +317,5 @@ module.exports = {
   verifyStoresProductCount,
   verifyStoresProductBySourceMarker,
   verifyStoresDeleteProbe,
+  verifyStoresInventoryImport,
 };