@wix/agent-skills 1.33.0 → 1.34.0

package/skills/wix-replatform/resources/rp-target-wix/lib/domain-knowledge.js

@@ -11,11 +11,19 @@ const CLASSIFICATIONS = new Set([
   'setup-config',
   'skip-by-default',
   'unsupported-native-gap',
+  // For manual-mapping: a complete, decided mapping with no write for our code to make — the entity
+  // carries `manualSteps` instead of a working `preferredWrite`. Deliberately not added to
+  // NATIVE_CLASSIFICATIONS below: import codegen must never treat this as a write target.
+  'manual-mapping',
 ]);
 const ID_POLICIES = new Set(['client-assigned', 'server-assigned', 'natural-key', 'not-applicable']);
 const VERIFICATIONS = new Set(['verified-live', 'docs', 'source-review', 'internal-only', 'unverified', 'none']);
 const RELIABILITY = new Set(['reliable', 'partially-reliable', 'unreliable', 'unknown']);
+const SURVEY_VERDICTS = new Set(['claimed', 'not-importable', 'not-relevant', 'gap', 'unreviewed']);
+const NATIVE_CLASSIFICATIONS = new Set(['native', 'native-plus-cms']);
 const SAFE_MODE_CONTACT_KINDS = new Set(['email', 'phone']);
+const BLOCKED_DEPENDENCY_DEGRADATIONS = new Set(['warning', 'deferred']);
+const MANUAL_STEP_ACTORS = new Set(['merchant', 'external', 'wix-automatable']);
 const WRITER_IDS = new Set(Object.keys(wixWriters).filter((name) => typeof wixWriters[name] === 'function'));
 
 function knowledgeRoot(rootDir = path.resolve(__dirname, '..')) {
@@ -66,6 +74,7 @@ function generateIndex(domainsDir) {
     domains: {},
     sourceAliasIndex: {},
     routeAliasIndex: {},
+    capabilityIndex: {},
     flags: {},
   };
 
@@ -85,6 +94,10 @@ function generateIndex(domainsDir) {
         reliabilityFlags: (entity.reliability && entity.reliability.flags) || [],
         summary: firstPitfallOrGuidance(entity),
       };
+      if (entity.capability) {
+        if (!index.capabilityIndex[entity.capability]) index.capabilityIndex[entity.capability] = [];
+        index.capabilityIndex[entity.capability].push(`${domain}/${entityId}`);
+      }
       for (const alias of entity.sourceAliases || []) {
         const key = `${alias.sourceSystem}:${alias.sourceEntity}`;
         if (!index.sourceAliasIndex[key]) index.sourceAliasIndex[key] = [];
@@ -107,7 +120,7 @@ function generateIndex(domainsDir) {
     };
   }
 
-  for (const collection of [index.sourceAliasIndex, index.routeAliasIndex, index.flags]) {
+  for (const collection of [index.sourceAliasIndex, index.routeAliasIndex, index.capabilityIndex, index.flags]) {
     for (const key of Object.keys(collection)) collection[key] = Array.from(new Set(collection[key])).sort();
   }
 
@@ -147,6 +160,42 @@ function validateKnowledge(domainsDir) {
         errors.push(`${domain}/domain.json: defaultImportOrder references missing entity ${entityId}`);
       }
     }
+    // REACHABILITY, the other direction — and the one that actually bites. The check above
+    // catches an order naming an entity that does not exist, which fails loudly. The reverse
+    // fails SILENTLY: an entity that is authored, has a verified writer, is covered by tests,
+    // and is named in no import order at all. Nothing errors, every test passes, and a run
+    // simply never writes it. That is how three separate entities shipped unreachable
+    // (ecom/shipping-option, ecom/pickup-location, site/business-contact) — each found only
+    // when a migrated site was missing the data and a human noticed.
+    //
+    // Rule: an entity with a writerId MUST be in its domain's defaultImportOrder. An entity
+    // with `writerId: null` has nothing to run and is legitimately absent, so the exclusion is
+    // derived from the entity's own contract rather than a hand-maintained opt-out list that
+    // would drift the same way.
+    const entitiesPath = path.join(domainsDir, domain, 'entities');
+    if (fs.existsSync(entitiesPath)) {
+      const order = new Set(domainJson.defaultImportOrder || []);
+      for (const fileName of fs.readdirSync(entitiesPath).filter((f) => f.endsWith('.json')).sort()) {
+        const entityId = fileName.replace(/\.json$/, '');
+        if (order.has(entityId)) continue;
+        let entityJson = null;
+        try {
+          entityJson = JSON.parse(fs.readFileSync(path.join(entitiesPath, fileName), 'utf8'));
+        } catch (error) {
+          continue; // the entity's own parse error is reported by validateEntity
+        }
+        if (entityJson && entityJson.preferredWrite && entityJson.preferredWrite.writerId) {
+          errors.push(`${domain}/domain.json: entity ${entityId} has writerId ${entityJson.preferredWrite.writerId} but is not in defaultImportOrder — a writer nothing runs migrates nothing. Add it to the order, or set preferredWrite.writerId to null if it genuinely cannot be written yet.`);
+        }
+      }
+    }
+    if (fs.existsSync(entitiesPath)) {
+      const entities = listEntityFiles(entitiesPath).map((fileName) => ({
+        id: fileName.replace(/\.json$/, ''),
+        dependsOn: loadEntity(domainsDir, domain, fileName.replace(/\.json$/, '')).dependsOn,
+      }));
+      errors.push(...validateDependsOnPromotion(domain, domainJson.dependsOnRequired, entities));
+    }
     validateEvidence(domainJson.evidence || [], `${domain}/domain.json`, errors);
 
     for (const fileName of listEntityFiles(path.join(domainsDir, domain))) {
@@ -155,6 +204,8 @@ function validateKnowledge(domainsDir) {
       const label = `${domain}/entities/${fileName}`;
       validateEntity(entity, domain, entityId, label, errors);
     }
+
+    validateDocsSurvey(domainsDir, domain, domainJson, errors);
   }
 
   if (!index) {
@@ -168,9 +219,285 @@ function validateKnowledge(domainsDir) {
     validateIndexConsistency(index, domainsDir, errors);
   }
 
+  validateDependsOn(domainsDir, errors);
+
   return { ok: errors.length === 0, errors, generatedIndex: generated };
 }
 
+function validateDependsOnPromotion(domain, dependsOnRequired, entities) {
+  const errors = [];
+  if (typeof dependsOnRequired !== 'boolean') {
+    errors.push(`${domain}/domain.json: dependsOnRequired must be a boolean`);
+    return errors;
+  }
+  const undeclared = entities.filter((entity) => entity.dependsOn === undefined);
+  if (dependsOnRequired && undeclared.length) {
+    for (const entity of undeclared) {
+      errors.push(`${domain}/domain.json: dependsOnRequired is true but ${domain}/entities/${entity.id}.json has no dependsOn; review and declare its dependencies`);
+    }
+  }
+  if (!dependsOnRequired && undeclared.length === 0) {
+    errors.push(`${domain}/domain.json: dependsOnRequired is false but every entity is declared; promote this domain by setting dependsOnRequired to true`);
+  }
+  return errors;
+}
+
+// The dependsOn graph across every entity that has it. Pure disk read, no validation —
+// `validateDependsOn` (ref resolution, cycles) and `checkScope` (rp-mapper's review-gate check)
+// both build on this so the graph is assembled exactly once, the same way, everywhere it's needed.
+function buildDependsOnGraph(domainsDir) {
+  const graph = new Map(); // ref -> dependsOn refs
+  for (const domain of listDomainDirs(domainsDir)) {
+    for (const fileName of listEntityFiles(path.join(domainsDir, domain))) {
+      const entityId = fileName.replace(/\.json$/, '');
+      const entity = loadEntity(domainsDir, domain, entityId);
+      if (entity.dependsOn === undefined) continue;
+      const ref = `${domain}/${entityId}`;
+      graph.set(ref, Array.isArray(entity.dependsOn) ? entity.dependsOn : []);
+    }
+  }
+  return graph;
+}
+
+// dependsOn is optional only in a domain that has not yet been promoted. Once a
+// domain's explicit dependsOnRequired flag is true, validateKnowledge rejects an undeclared
+// entity; in every domain a present declaration must resolve and the graph must stay acyclic.
+// Builds its own local graph rather than calling buildDependsOnGraph afterward — this function
+// already reads and parses every entity file once for ref-resolution/array-type checks, so
+// reusing that same read for cycle detection (instead of a second full read+parse pass) halves
+// the I/O of every `domain-knowledge-validate.js` run.
+function validateDependsOn(domainsDir, errors) {
+  const graph = new Map();
+  for (const domain of listDomainDirs(domainsDir)) {
+    for (const fileName of listEntityFiles(path.join(domainsDir, domain))) {
+      const entityId = fileName.replace(/\.json$/, '');
+      const entity = loadEntity(domainsDir, domain, entityId);
+      const label = `${domain}/entities/${fileName}`;
+      if (entity.dependsOn === undefined) continue;
+      if (!Array.isArray(entity.dependsOn)) {
+        errors.push(`${label}: dependsOn must be an array when present`);
+        continue;
+      }
+      graph.set(`${domain}/${entityId}`, entity.dependsOn);
+      for (const [ref, mode] of Object.entries(entity.dependencyModes || {})) {
+        if (mode !== 'per-record' || !entity.dependsOn.includes(ref) || !Array.isArray(entity.dependencyReferenceFields?.[ref]) || !entity.dependencyReferenceFields[ref].length) errors.push(`dependency_mode_invalid:${domain}/${entityId}:${ref}`);
+        const [producerDomain, producerEntity] = ref.split('/');
+        if (fs.existsSync(path.join(domainsDir, producerDomain || '', 'entities', `${producerEntity}.json`)) && loadEntity(domainsDir, producerDomain, producerEntity).target?.classification === 'setup-config') errors.push(`dependency_mode_invalid:${domain}/${entityId}:${ref}`);
+      }
+      for (const dep of entity.dependsOn) {
+        const segments = String(dep).split('/');
+        const [depDomain, depEntity] = segments;
+        if (segments.length !== 2 || !depDomain || !depEntity || !fs.existsSync(path.join(domainsDir, depDomain, 'entities', `${depEntity}.json`))) {
+          errors.push(`${label}: dependsOn entry "${dep}" does not resolve to an entity file`);
+        }
+      }
+    }
+  }
+
+  const cycle = findCycle(graph);
+  if (cycle) errors.push(`dependsOn graph has a cycle: ${cycle.join(' -> ')}`);
+}
+
+function findCycle(graph) {
+  const WHITE = 0;
+  const GRAY = 1;
+  const BLACK = 2;
+  const color = new Map();
+  const stack = [];
+
+  function visit(node) {
+    color.set(node, GRAY);
+    stack.push(node);
+    for (const next of graph.get(node) || []) {
+      const state = color.get(next) || WHITE;
+      if (state === GRAY) return [...stack, next];
+      if (state === WHITE && graph.has(next)) {
+        const found = visit(next);
+        if (found) return found;
+      }
+    }
+    stack.pop();
+    color.set(node, BLACK);
+    return null;
+  }
+
+  for (const node of graph.keys()) {
+    if ((color.get(node) || WHITE) === WHITE) {
+      const found = visit(node);
+      if (found) return found;
+    }
+  }
+  return null;
+}
+
+// Every entity ref that actually exists on disk, regardless of whether it has dependsOn authored.
+// checkScope needs this to tell "unknown ref" (not in this set) apart from "known but unreviewed"
+// (in this set, absent from the dependsOn graph).
+function listAllEntityRefs(domainsDir) {
+  const refs = [];
+  for (const domain of listDomainDirs(domainsDir)) {
+    for (const fileName of listEntityFiles(path.join(domainsDir, domain))) {
+      refs.push(`${domain}/${fileName.replace(/\.json$/, '')}`);
+    }
+  }
+  return refs;
+}
+
+// The rp-mapper review-gate check, as a pure function (the caller does not compute the transitive
+// closure, and unknown refs and never-reviewed entities are never passed as though they were
+// "reviewed, no dependencies").
+// Given every real entity ref, the dependsOn graph, and the plan's own selected scope (only —
+// the caller does not pre-expand anything), this walks dependsOn edges outward itself and reports
+// three distinct, non-overlapping failure categories. `checkScope` below is the disk-reading
+// wrapper `rp-mapper`/an agent/the CLI actually calls.
+function computeScopeCheck(allRefs, graph, selectedRefs) {
+  const selectedSet = new Set((selectedRefs || []).map((ref) => String(ref)));
+  const unknownRefs = new Set(Array.from(selectedSet).filter((ref) => !allRefs.has(ref)));
+  const validSelected = Array.from(selectedSet).filter((ref) => allRefs.has(ref));
+
+  const visited = new Set();
+  const queue = [...validSelected];
+  const unreviewedRefs = [];
+  const missingByRef = new Map();
+
+  while (queue.length) {
+    const ref = queue.shift();
+    if (visited.has(ref)) continue;
+    visited.add(ref);
+
+    if (!allRefs.has(ref)) {
+      // Reached only via a dependsOn edge (never itself in selectedRefs, or `selectedSet` would
+      // already have caught it above) — a dangling/typo'd ref, not merely unreviewed.
+      unknownRefs.add(ref);
+      continue;
+    }
+
+    if (!graph.has(ref)) {
+      // Reachable, resolves to a real entity, but dependsOn has never been authored at all —
+      // fail-closed: "not yet reviewed" is not the same fact as "reviewed, no dependencies."
+      unreviewedRefs.push(ref);
+      continue;
+    }
+
+    const deps = graph.get(ref);
+    const missing = deps.filter((dep) => !selectedSet.has(dep));
+    if (missing.length) missingByRef.set(ref, missing);
+    for (const dep of deps) {
+      if (!visited.has(dep)) queue.push(dep);
+    }
+  }
+
+  const missingDependencies = Array.from(missingByRef.entries())
+    .map(([ref, missing]) => ({ ref, missing }))
+    .sort((a, b) => a.ref.localeCompare(b.ref));
+
+  return {
+    ok: unknownRefs.size === 0 && missingDependencies.length === 0 && unreviewedRefs.length === 0,
+    unknownRefs: Array.from(unknownRefs).sort(),
+    missingDependencies,
+    unreviewedRefs: unreviewedRefs.sort(),
+  };
+}
+
+// Disk-reading wrapper — this is what `domain-knowledge-validate.js --check-scope` and rp-mapper's
+// review gate should call, passing only the plan's own selected scope. See computeScopeCheck for
+// the pure algorithm and why each failure category exists.
+function checkScope(domainsDir, selectedRefs) {
+  return computeScopeCheck(new Set(listAllEntityRefs(domainsDir)), buildDependsOnGraph(domainsDir), selectedRefs);
+}
+
+// The live backlog: every entity that has never had dependsOn authored at all (field
+// absent, not merely empty). Non-blocking by design — this is a report, not a validation error.
+// `node domain-knowledge-validate.js --list-missing-deps` is the intended way to read it, so the
+// backlog never drifts out of sync with a hand-maintained list the way a markdown table would.
+function listMissingDependsOn(domainsDir) {
+  const missing = [];
+  for (const domain of listDomainDirs(domainsDir)) {
+    for (const fileName of listEntityFiles(path.join(domainsDir, domain))) {
+      const entityId = fileName.replace(/\.json$/, '');
+      const entity = loadEntity(domainsDir, domain, entityId);
+      if (entity.dependsOn === undefined) missing.push(`${domain}/${entityId}`);
+    }
+  }
+  return missing.sort();
+}
+
+// Every domain with entities carries a docs survey in which every
+// docs-menu surface is triaged, and its native entities cite their object
+// page. The backfill completed 2026-08-11, so a missing survey is an error.
+function validateDocsSurvey(domainsDir, domain, domainJson, errors) {
+  const surveyPath = path.join(domainsDir, domain, 'docs-survey.json');
+  const hasEntities = listEntityFiles(path.join(domainsDir, domain)).length > 0;
+  if (!fs.existsSync(surveyPath)) {
+    if (hasEntities) errors.push(`${domain}: missing docs-survey.json; run docs-survey-sync.js ${domain} and triage`);
+    return;
+  }
+
+  const label = `${domain}/docs-survey.json`;
+  const survey = readJson(surveyPath);
+  requireFields(survey, ['schemaVersion', 'domain', 'fetchedAt', 'roots', 'surfaces'], label, errors);
+  if (survey.schemaVersion !== 1) errors.push(`${label}: schemaVersion must be 1`);
+  if (survey.domain !== domain) errors.push(`${label}: domain must match directory`);
+
+  const declaredRoots = JSON.stringify([...(domainJson.docsRoots || [])].sort());
+  const surveyRoots = JSON.stringify([...(survey.roots || [])].sort());
+  if (declaredRoots !== surveyRoots) {
+    errors.push(`${label}: roots must match ${domain}/domain.json docsRoots; re-run docs-survey-sync.js ${domain}`);
+  }
+
+  for (const surface of survey.surfaces || []) {
+    const surfaceLabel = `${label}: ${surface.id || '<missing id>'}`;
+    requireFields(surface, ['id', 'title', 'url', 'verdict'], surfaceLabel, errors);
+    if (surface.removed) {
+      errors.push(`${surfaceLabel}: surface no longer in the docs menu; delete the entry or revisit the facts that cited it`);
+      continue;
+    }
+    if (!SURVEY_VERDICTS.has(surface.verdict)) {
+      errors.push(`${surfaceLabel}: invalid verdict ${surface.verdict}`);
+      continue;
+    }
+    if (surface.verdict === 'unreviewed') {
+      errors.push(`${surfaceLabel}: unreviewed surface; triage it (claimed / not-importable / not-relevant / gap)`);
+      continue;
+    }
+    if (!surface.reviewedOn) errors.push(`${surfaceLabel}: triaged surface must carry reviewedOn`);
+    if (surface.verdict === 'claimed') {
+      if (!Array.isArray(surface.refs) || surface.refs.length === 0) {
+        errors.push(`${surfaceLabel}: claimed surface must list refs[]`);
+      } else {
+        for (const ref of surface.refs) {
+          const [refDomain, refEntity] = String(ref).split('/');
+          if (!refDomain || !refEntity || !fs.existsSync(path.join(domainsDir, refDomain, 'entities', `${refEntity}.json`))) {
+            errors.push(`${surfaceLabel}: claimed ref ${ref} does not resolve to an entity file`);
+          }
+        }
+      }
+    }
+    if ((surface.verdict === 'not-importable' || surface.verdict === 'not-relevant') && !surface.reason) {
+      errors.push(`${surfaceLabel}: ${surface.verdict} requires a reason`);
+    }
+    if (surface.verdict === 'gap' && (!surface.reason || !surface.tracking)) {
+      errors.push(`${surfaceLabel}: gap requires reason and tracking`);
+    }
+  }
+
+  for (const fileName of listEntityFiles(path.join(domainsDir, domain))) {
+    const entityId = fileName.replace(/\.json$/, '');
+    const entity = loadEntity(domainsDir, domain, entityId);
+    if (!NATIVE_CLASSIFICATIONS.has(entity.target && entity.target.classification)) continue;
+    const citesObjectPage = (entity.evidence || []).some(
+      (item) => typeof item.url === 'string' && /-object$/.test(item.url.replace(/\.md$/, ''))
+    );
+    // A surface with no …-object reference page (e.g. Comments, which has no
+    // REST reference at all) declares objectPageException with the reason —
+    // explicit and greppable, never silent.
+    const hasException = typeof entity.objectPageException === 'string' && entity.objectPageException.length > 0;
+    if (!citesObjectPage && !hasException) {
+      errors.push(`${domain}/entities/${fileName}: native target must cite its docs object page (…-object URL) in evidence[], or declare objectPageException with a reason`);
+    }
+  }
+}
+
 function requireFields(value, fields, label, errors) {
   for (const field of fields) {
     if (value[field] === undefined) errors.push(`${label}: missing required field ${field}`);
@@ -197,10 +524,79 @@ function validateEntity(entity, domain, entityId, label, errors) {
   for (const alias of entity.sourceAliases || []) {
     if (!alias.sourceSystem || !alias.sourceEntity) errors.push(`${label}: sourceAliases entries must include sourceSystem and sourceEntity`);
   }
+  if (entity.target && entity.target.classification === 'manual-mapping') {
+    validateManualMapping(entity, label, errors);
+  } else if (entity.manualSteps !== undefined) {
+    errors.push(`${label}: manualSteps is only allowed when target.classification is manual-mapping`);
+  }
   validateSafeModeContactFields(entity.safeModeContactFields, label, errors);
+  validateBlockedSourceDependencies(entity, label, errors);
   validateEvidence(entity.evidence || [], label, errors);
 }
 
+function validateBlockedSourceDependencies(entity, label, errors) {
+  if (entity.blockedSourceDependencies === undefined) return;
+  if (!Array.isArray(entity.blockedSourceDependencies)) {
+    errors.push(`${label}: blockedSourceDependencies must be an array when present`);
+    return;
+  }
+  const pitfallCodes = new Set((entity.pitfalls || []).map((pitfall) => pitfall.code));
+  const seen = new Set();
+  entity.blockedSourceDependencies.forEach((dependency, index) => {
+    const dependencyLabel = `${label}: blockedSourceDependencies[${index}]`;
+    if (!dependency || typeof dependency !== 'object' || Array.isArray(dependency)) {
+      errors.push(`${dependencyLabel} must be an object`);
+      return;
+    }
+    for (const field of ['sourceEntityRef', 'degradedField', 'pitfallCode', 'degradation']) {
+      if (!dependency[field] || typeof dependency[field] !== 'string') errors.push(`${dependencyLabel}.${field} must be a non-empty string`);
+    }
+    if (dependency.sourceEntityRef && !/^plugin\.[^.]+\.[^.]+$/.test(dependency.sourceEntityRef)) {
+      errors.push(`${dependencyLabel}.sourceEntityRef must use plugin.<slug>.<entity>`);
+    }
+    if (dependency.pitfallCode && !pitfallCodes.has(dependency.pitfallCode)) {
+      errors.push(`${dependencyLabel}.pitfallCode ${dependency.pitfallCode} does not resolve in this entity's pitfalls[]`);
+    }
+    if (dependency.degradation && !BLOCKED_DEPENDENCY_DEGRADATIONS.has(dependency.degradation)) {
+      errors.push(`${dependencyLabel}.degradation must be warning or deferred`);
+    }
+    const key = `${dependency.sourceEntityRef}:${dependency.degradedField}`;
+    if (seen.has(key)) errors.push(`${dependencyLabel} duplicates ${key}`);
+    seen.add(key);
+  });
+}
+
+// For manual-mapping: a manual-mapping entity performs no write, so its preferredWrite must
+// be structurally inert (nothing for import codegen to accidentally call), and its manualSteps
+// must actually contain a runbook — an empty or missing one would render nothing to the
+// merchant, which is worse than not classifying it manual-mapping at all.
+function validateManualMapping(entity, label, errors) {
+  const pw = entity.preferredWrite || {};
+  if (pw.endpoint !== null) errors.push(`${label}: manual-mapping requires preferredWrite.endpoint === null`);
+  if (pw.writerId !== null) errors.push(`${label}: manual-mapping requires preferredWrite.writerId === null`);
+  if (pw.verification !== 'none') errors.push(`${label}: manual-mapping requires preferredWrite.verification === 'none'`);
+  if (pw.importSafe !== false) errors.push(`${label}: manual-mapping requires preferredWrite.importSafe === false`);
+  if (pw.bulk !== false) errors.push(`${label}: manual-mapping requires preferredWrite.bulk === false`);
+
+  const manualSteps = entity.manualSteps;
+  if (!manualSteps || typeof manualSteps !== 'object') {
+    errors.push(`${label}: manual-mapping requires a manualSteps object`);
+    return;
+  }
+  if (!Array.isArray(manualSteps.steps) || manualSteps.steps.length === 0) {
+    errors.push(`${label}: manualSteps.steps must be a non-empty array`);
+    return;
+  }
+  manualSteps.steps.forEach((step, index) => {
+    if (!step || !MANUAL_STEP_ACTORS.has(step.actor)) {
+      errors.push(`${label}: manualSteps.steps[${index}].actor must be one of ${Array.from(MANUAL_STEP_ACTORS).join(', ')}`);
+    }
+    if (!step || typeof step.text !== 'string' || step.text.trim() === '') {
+      errors.push(`${label}: manualSteps.steps[${index}].text must be a non-empty string`);
+    }
+  });
+}
+
 function validateSafeModeContactFields(fields, label, errors) {
   if (fields === undefined) return;
   if (!Array.isArray(fields)) {
@@ -351,6 +747,15 @@ function listFlagged(domainsDir, flag) {
   });
 }
 
+// Lazily required: domain-knowledge is loaded by tooling that has no need for the schema library,
+// and a hard dependency at module load is how one domain file breaks everything (learned the hard
+// way when a generic library loaded an eCommerce entity at init).
+function stampSetupRequirement(requirement) {
+  if (!requirement || requirement.kind !== 'extendedFieldSchema') return requirement;
+  // eslint-disable-next-line global-require
+  return require('./data-extension-schema.js').stampRequirement(requirement);
+}
+
 function summarizeEntities(domainsDir, refs, { includeEvidence = false } = {}) {
   return refs.map((ref) => {
     const entity = readEntityByRef(domainsDir, ref);
@@ -362,18 +767,64 @@ function summarizeEntities(domainsDir, refs, { includeEvidence = false } = {}) {
       reliability: entity.reliability,
       pitfalls: entity.pitfalls,
       mappingGuidance: entity.mappingGuidance,
-      setupRequirements: entity.setupRequirements || [],
+      // Stamped HERE, at the producer the shipped path actually uses. The stamp used to live only
+      // on a domain adapter that setup discovery never calls, so the real chain emitted unstamped
+      // requirements and every invoice write was refused by a guard that was working correctly.
+      setupRequirements: (entity.setupRequirements || []).map(stampSetupRequirement),
       fieldContracts: entity.fieldContracts || [],
+      blockedSourceDependencies: entity.blockedSourceDependencies || [],
+      extendedFields: entity.extendedFields || null,
     };
     if (includeEvidence) summary.evidence = entity.evidence;
     return summary;
   });
 }
 
+// Compact cross-adapter view consumed by the WordPress plugin knowledge base so plugin
+// profiles can be validated against real Wix target refs and capability claims without
+// each adapter re-reading the other's tree.
+function knowledgeSummary(domainsDir) {
+  const index = loadIndex(domainsDir);
+  const knownRefs = new Set();
+  const verificationByRef = new Map();
+  // manual-mapping entities only — lets classifyCoverage tell a manual-mapping
+  // target apart from a real write target using only this compact summary, with no need to
+  // re-read the full rp-target-wix entity tree from the WordPress side.
+  const manualStepsByRef = new Map();
+  const blockedSourceDependenciesByRef = new Map();
+  for (const [domain, domainEntry] of Object.entries(index.domains || {})) {
+    for (const entityId of Object.keys(domainEntry.entities || {})) {
+      const ref = `${domain}/${entityId}`;
+      knownRefs.add(ref);
+      const entity = loadEntity(domainsDir, domain, entityId);
+      verificationByRef.set(ref, entity.preferredWrite && entity.preferredWrite.verification);
+      if (entity.target && entity.target.classification === 'manual-mapping' && entity.manualSteps) {
+        manualStepsByRef.set(ref, entity.manualSteps);
+      }
+      if (Array.isArray(entity.blockedSourceDependencies) && entity.blockedSourceDependencies.length > 0) {
+        blockedSourceDependenciesByRef.set(ref, entity.blockedSourceDependencies);
+      }
+    }
+  }
+  const capabilityRefs = new Map(Object.entries(index.capabilityIndex || {}));
+  return { knownRefs, capabilityRefs, verificationByRef, manualStepsByRef, blockedSourceDependenciesByRef };
+}
+
 module.exports = {
   knowledgeRoot,
   generateIndex,
+  knowledgeSummary,
   validateKnowledge,
+  validateDependsOnPromotion,
+  validateDependsOn,
+  validateEntity,
+  validateBlockedSourceDependencies,
+  buildDependsOnGraph,
+  findCycle,
+  listAllEntityRefs,
+  computeScopeCheck,
+  checkScope,
+  listMissingDependsOn,
   writeJson,
   listDomains,
   listEntities,

package/skills/wix-replatform/resources/rp-target-wix/lib/gift-card-balance-reconciliation.js

@@ -0,0 +1,119 @@
+'use strict';
+
+const { isBlank } = require('./value-utils.js');
+
+// rp-target-wix — balance-reconciliation REPORTING, not a write path.
+//
+// Wix's gift-cards API has no balance-increase/credit method (the "no-credit-API
+// finding": create, send-email, query/search, disable, find-by-email, redeem, void — nothing that
+// raises a balance). The only correction for a card already created wrong is disable-and-replace,
+// a code change that alters the customer-facing code and needs its own human sign-off (see
+// gift-cards/gift-card.json's pitfalls) — never a silent balance patch. This module therefore only
+// ever REPORTS drift; it never proposes "replay the difference," which is exactly the
+// double-decrement risk that is ruled out (a card must never be built by
+// gift-card-build.js twice under different balance policies).
+//
+// BLOCKED on input: `sourceBalance` below is meant to come from
+// the bridge plugin, which is code-only and not yet installed/live-tested on any real
+// site. This module is ready to consume that data the moment it exists.
+
+function normalizeMoney(value) {
+  if (isBlank(value)) return null;
+  const numeric = Number(value);
+  if (!Number.isFinite(numeric)) return null;
+  return Math.round(numeric * 100) / 100;
+}
+
+// One card's reconciliation row. `policy` records which balance policy the card was
+// CREATED under — required, because the correct verdict for an identical mismatch differs by
+// policy: under Policy A (face value, no replay) an overstatement is the known, accepted
+// consequence of that choice; the same mismatch under Policy B (verified balance at creation) or
+// Policy C (face value, then corrected by replaying real order-linked redemptions — see
+// gift-card-redemption-build.js) means the card was born wrong, or its replay is incomplete/wrong,
+// and needs investigation, not passive acceptance. Policy C is included here alongside B, not
+// given its own "in-progress replay" leniency: a reconciliation check is the caller's to run only
+// once replay is believed complete, not this module's to guess at.
+function buildBalanceReconciliationRow({ sourceNumber, policy, sourceBalance, wixBalance } = {}) {
+  if (isBlank(sourceNumber)) {
+    return {
+      sourceNumber: sourceNumber == null ? null : sourceNumber,
+      ok: false,
+      gap: { code: 'missing-source-number', summary: 'sourceNumber is required to report a reconciliation row against.' },
+    };
+  }
+  if (policy !== 'A' && policy !== 'B' && policy !== 'C') {
+    return {
+      sourceNumber,
+      ok: false,
+      gap: { code: 'invalid-policy', summary: `policy must be "A", "B", or "C" — got ${JSON.stringify(policy)}.` },
+    };
+  }
+
+  const source = normalizeMoney(sourceBalance);
+  if (source === null) {
+    return {
+      sourceNumber,
+      ok: false,
+      gap: { code: 'unavailable-source-balance', summary: `no verified current balance available for card ${sourceNumber} from the bridge plugin — report this card as unreconciled rather than assuming it matches.` },
+    };
+  }
+  const wix = normalizeMoney(wixBalance);
+  if (wix === null) {
+    return {
+      sourceNumber,
+      ok: false,
+      gap: { code: 'unavailable-wix-balance', summary: `no Wix balance available for card ${sourceNumber} — read it back via Get Gift Card before reconciling.` },
+    };
+  }
+
+  const drift = Math.round((wix - source) * 100) / 100;
+  if (drift === 0) {
+    return { sourceNumber, ok: true, policy, sourceBalance: source, wixBalance: wix, drift: 0, verdict: 'matches', action: 'none' };
+  }
+
+  if (policy === 'A' && drift > 0) {
+    return {
+      sourceNumber,
+      ok: false,
+      policy,
+      sourceBalance: source,
+      wixBalance: wix,
+      drift,
+      verdict: 'expected-overstatement',
+      action: 'disable-and-replace-or-accept',
+      summary: `card ${sourceNumber} shows ${wix} in Wix but ${source} at the source — the known, accepted overstatement of Policy A (face value at creation, no replay). Correcting it requires disabling and replacing the card (no balance-credit API exists), which changes the customer-facing code and needs its own human sign-off.`,
+    };
+  }
+
+  // Any other direction/policy combination is not a shape any policy's documented behavior
+  // produces on its own (e.g. Policy A showing a Wix balance BELOW the source, or any mismatch at
+  // all under Policy B/C) — a real anomaly, not something to explain away.
+  return {
+    sourceNumber,
+    ok: false,
+    policy,
+    sourceBalance: source,
+    wixBalance: wix,
+    drift,
+    verdict: 'unexpected-drift',
+    action: 'investigate',
+    summary: `card ${sourceNumber} shows ${wix} in Wix vs ${source} at the source (drift ${drift}) under Policy ${policy} — not a shape any policy's documented behavior explains; investigate before accepting or correcting it.`,
+  };
+}
+
+function buildBalanceReconciliationReport(cards) {
+  const rows = (cards || []).map((card) => buildBalanceReconciliationRow(card));
+  const mismatches = rows.filter((row) => !row.ok);
+  return {
+    totalCards: rows.length,
+    matched: rows.length - mismatches.length,
+    mismatches,
+    rows,
+  };
+}
+
+module.exports = {
+  normalizeMoney,
+  buildBalanceReconciliationRow,
+  buildBalanceReconciliationReport,
+};