@wix/agent-skills 1.15.1 → 1.16.0

package/skills/wix-replatform/resources/rp-target-wix/domains/members/entities/member.json

@@ -0,0 +1,53 @@
+{
+  "schemaVersion": 1,
+  "domain": "members",
+  "entity": "member",
+  "displayName": "Site Member",
+  "target": {
+    "classification": "native-plus-cms",
+    "nativeEntity": "Member",
+    "verifiedFqdn": null,
+    "idPolicy": "server-assigned",
+    "crosswalkRequired": true
+  },
+  "sourceAliases": [
+    { "sourceSystem": "wordpress", "sourceEntity": "user", "routes": ["/wp/v2/users"], "confidence": "medium" },
+    { "sourceSystem": "woocommerce", "sourceEntity": "customer", "routes": ["/wc/v3/customers"], "confidence": "medium" },
+    { "sourceSystem": "wix", "sourceEntity": "member", "routes": ["Members APIs"], "confidence": "high" }
+  ],
+  "preferredWrite": {
+    "surface": "Members V1",
+    "endpoint": "POST /members/v1/members",
+    "writerId": "createMember",
+    "verification": "verified-live",
+    "importSafe": false,
+    "bulk": false
+  },
+  "safeModeContactFields": [
+    {
+      "kind": "email",
+      "targetPath": "member.loginEmail",
+      "source": "target-schema",
+      "notes": "Members V1 login email in the create-member request body."
+    }
+  ],
+  "fallbacks": [
+    { "classification": "crm", "when": "Use Contacts for person records that do not need login identity." },
+    { "classification": "cms", "when": "Use for author profiles or member metadata not represented by Members APIs." }
+  ],
+  "reliability": { "status": "unreliable", "flags": ["IMPORT_UNRELIABLE"] },
+  "pitfalls": [
+    { "code": "passwords-never-imported", "severity": "warning", "summary": "Passwords are NOT imported — project decision (2026-08-03), not just an API gap. Members keep account/profile/contact linkage; they set a new password via reset. Never propose hash import." },
+    { "code": "activation-via-forgot-password", "severity": "warning", "summary": "Activation (decided 2026-08-03): passwordless members complete the standard forgot-password flow (confirmed). Delivery = post-import automation (label-added trigger, owner-branded email, label applied in API waves). Never mass-send Send Set Password Email — its link dies in 3h." },
+    { "code": "serial-create-only", "severity": "warning", "summary": "No bulk member create; documented >=1s spacing per Create Member call (10k members ~ 3h serial floor). Plan throughput and resume via loginEmail crosswalk." },
+    { "code": "chronology-server-controlled", "severity": "warning", "summary": "Original createdDate and lastLoginDate are not writable as native member chronology." }
+  ],
+  "mappingGuidance": [
+    "Split author, customer, contact, and login-member roles before selecting targets.",
+    "Create Member sends no email and does not fire the signup automations trigger (source-confirmed) — silent import is the default; the only member-facing email is the explicit Send Set Password Email call, which is per-member, interactive-mode, owner-approved only."
+  ],
+  "setupRequirements": ["Activation is decided end-to-end: no credential import; post-import the owner creates ONE dashboard automation (label-added trigger → branded email directing members to Log in → Forgot password), then the importer applies the label in API waves for rate control and re-targeting. Enable the automation only after the import window (AUTO-02 pause choreography)."],
+  "evidence": [
+    { "type": "repo-research", "path": "research/import-api-suitability/orders-contacts-members.md" }
+  ]
+}

package/skills/wix-replatform/resources/rp-target-wix/domains/schema.json

@@ -0,0 +1,84 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://wix.com/replatform/domain-knowledge.schema.json",
+  "title": "RePlatform Wix Domain Knowledge Entity",
+  "type": "object",
+  "additionalProperties": true,
+  "required": [
+    "schemaVersion",
+    "domain",
+    "entity",
+    "displayName",
+    "target",
+    "sourceAliases",
+    "preferredWrite",
+    "reliability",
+    "pitfalls",
+    "mappingGuidance",
+    "evidence"
+  ],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "domain": { "type": "string", "minLength": 1 },
+    "entity": { "type": "string", "minLength": 1 },
+    "displayName": { "type": "string", "minLength": 1 },
+    "target": {
+      "type": "object",
+      "required": ["classification", "idPolicy", "crosswalkRequired"],
+      "properties": {
+        "classification": {
+          "enum": [
+            "native",
+            "cms",
+            "native-plus-cms",
+            "setup-config",
+            "skip-by-default",
+            "unsupported-native-gap"
+          ]
+        },
+        "nativeEntity": { "type": ["string", "null"] },
+        "verifiedFqdn": { "type": ["string", "null"] },
+        "idPolicy": {
+          "enum": ["client-assigned", "server-assigned", "natural-key", "not-applicable"]
+        },
+        "crosswalkRequired": { "type": "boolean" }
+      }
+    },
+    "preferredWrite": {
+      "type": "object",
+      "required": ["surface", "endpoint", "writerId", "verification", "importSafe", "bulk"],
+      "properties": {
+        "surface": { "type": "string" },
+        "endpoint": { "type": ["string", "null"] },
+        "writerId": { "type": ["string", "null"] },
+        "verification": {
+          "enum": ["verified-live", "docs", "source-review", "internal-only", "unverified", "none"]
+        },
+        "importSafe": { "type": "boolean" },
+        "bulk": { "type": "boolean" }
+      }
+    },
+    "reliability": {
+      "type": "object",
+      "required": ["status", "flags"],
+      "properties": {
+        "status": { "enum": ["reliable", "partially-reliable", "unreliable", "unknown"] },
+        "flags": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "safeModeContactFields": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["kind", "targetPath", "source"],
+        "properties": {
+          "kind": { "enum": ["email", "phone"] },
+          "targetPath": { "type": "string", "minLength": 1 },
+          "source": { "type": "string", "minLength": 1 },
+          "notes": { "type": "string" }
+        },
+        "additionalProperties": true
+      }
+    }
+  }
+}

package/skills/wix-replatform/resources/rp-target-wix/domains/stores/domain.json

@@ -0,0 +1,25 @@
+{
+  "schemaVersion": 1,
+  "domain": "stores",
+  "displayName": "Wix Stores",
+  "ownerHint": "Stores Catalog, Inventory, Coupons, Tags, and merchandising domain owners",
+  "wixAppsRequired": ["Wix Stores"],
+  "defaultImportOrder": ["category", "product-tag", "product", "inventory-item", "coupon"],
+  "sharedPitfalls": [
+    {
+      "code": "catalog-version-required",
+      "severity": "blocker",
+      "summary": "Catalog V3 only — Catalog V1 is unsupported. Confirm catalogVersion is V3_CATALOG (GET /stores/v3/provision/version) before any Stores write; V1_CATALOG halts the run, it is never mapped or coded around."
+    }
+  ],
+  "evidence": [
+    {
+      "type": "repo-research",
+      "path": "research/import-api-suitability/stores-catalog-inventory.md"
+    },
+    {
+      "type": "repo-research",
+      "path": "research/source-entity-import-suitability-wordpress-woocommerce-wix.md"
+    }
+  ]
+}

package/skills/wix-replatform/resources/rp-target-wix/domains/stores/entities/category.json

@@ -0,0 +1,37 @@
+{
+  "schemaVersion": 1,
+  "domain": "stores",
+  "entity": "category",
+  "displayName": "Stores Category",
+  "target": {
+    "classification": "native",
+    "nativeEntity": "Stores Category",
+    "verifiedFqdn": null,
+    "idPolicy": "server-assigned",
+    "crosswalkRequired": true
+  },
+  "sourceAliases": [
+    { "sourceSystem": "woocommerce", "sourceEntity": "product_category", "routes": ["/wc/v3/products/categories"], "confidence": "high" },
+    { "sourceSystem": "wix", "sourceEntity": "storesCategory", "routes": ["Catalog V3 Categories", "V1 collections"], "confidence": "high" }
+  ],
+  "preferredWrite": {
+    "surface": "Categories",
+    "endpoint": "POST /categories/v1/categories",
+    "writerId": "createStoresCategory",
+    "verification": "verified-live",
+    "importSafe": true,
+    "bulk": false
+  },
+  "fallbacks": [
+    { "classification": "cms", "when": "Use only for source taxonomy metadata or hierarchy details not represented by Stores categories." }
+  ],
+  "reliability": { "status": "reliable", "flags": [] },
+  "pitfalls": [
+    { "code": "tree-reference-top-level", "severity": "blocker", "summary": "Pass Stores treeReference as a top-level sibling of category." }
+  ],
+  "mappingGuidance": ["Preserve hierarchy where the target category tree supports it; create before products."],
+  "setupRequirements": ["Wix Stores app"],
+  "evidence": [
+    { "type": "repo-research", "path": "research/import-api-suitability/stores-catalog-inventory.md" }
+  ]
+}

package/skills/wix-replatform/resources/rp-target-wix/domains/stores/entities/coupon.json

@@ -0,0 +1,37 @@
+{
+  "schemaVersion": 1,
+  "domain": "stores",
+  "entity": "coupon",
+  "displayName": "Stores Coupon",
+  "target": {
+    "classification": "native-plus-cms",
+    "nativeEntity": "Stores Coupon",
+    "verifiedFqdn": null,
+    "idPolicy": "server-assigned",
+    "crosswalkRequired": true
+  },
+  "sourceAliases": [
+    { "sourceSystem": "woocommerce", "sourceEntity": "coupon", "routes": ["/wc/v3/coupons"], "confidence": "high" },
+    { "sourceSystem": "wix", "sourceEntity": "coupon", "routes": ["Coupons API"], "confidence": "high" }
+  ],
+  "preferredWrite": {
+    "surface": "Coupons",
+    "endpoint": "POST /stores/v2/coupons",
+    "writerId": "createCoupon",
+    "verification": "unverified",
+    "importSafe": true,
+    "bulk": false
+  },
+  "fallbacks": [
+    { "classification": "cms", "when": "Use for unsupported source constraints, audit detail, or manual setup notes." }
+  ],
+  "reliability": { "status": "partially-reliable", "flags": [] },
+  "pitfalls": [
+    { "code": "constraint-coverage", "severity": "warning", "summary": "Source coupon constraints may be narrower or differently modeled in Wix." }
+  ],
+  "mappingGuidance": ["Prefer native coupons and record unsupported conditions as CMS shadow fields or setup gaps."],
+  "setupRequirements": ["Wix Stores app"],
+  "evidence": [
+    { "type": "repo-research", "path": "research/import-api-suitability/stores-catalog-inventory.md" }
+  ]
+}

package/skills/wix-replatform/resources/rp-target-wix/domains/stores/entities/inventory-item.json

@@ -0,0 +1,38 @@
+{
+  "schemaVersion": 1,
+  "domain": "stores",
+  "entity": "inventory-item",
+  "displayName": "Stores Inventory Item",
+  "target": {
+    "classification": "native",
+    "nativeEntity": "Stores Inventory Item",
+    "verifiedFqdn": null,
+    "idPolicy": "server-assigned",
+    "crosswalkRequired": true
+  },
+  "sourceAliases": [
+    { "sourceSystem": "woocommerce", "sourceEntity": "product_variation_inventory", "routes": ["/wc/v3/products", "/wc/v3/products/{productId}/variations"], "confidence": "medium" },
+    { "sourceSystem": "wix", "sourceEntity": "inventoryItem", "routes": ["Stores Inventory APIs"], "confidence": "high" }
+  ],
+  "preferredWrite": {
+    "surface": "Stores Inventory V3",
+    "endpoint": "POST /stores/v3/inventory-items",
+    "writerId": "createInventoryItem",
+    "verification": "unverified",
+    "importSafe": true,
+    "bulk": false
+  },
+  "fallbacks": [
+    { "classification": "cms", "when": "Use for source stock history or multi-location detail not represented by the selected target inventory plan." }
+  ],
+  "reliability": { "status": "partially-reliable", "flags": [] },
+  "pitfalls": [
+    { "code": "product-first", "severity": "blocker", "summary": "Inventory requires target product and variant IDs." },
+    { "code": "bis-side-effects", "severity": "warning", "summary": "Avoid stock transitions that trigger Back in Stock notifications on live stores." }
+  ],
+  "mappingGuidance": ["Create products first, then create or update inventory per variant."],
+  "setupRequirements": ["SCOPE.STORES.INVENTORY_ITEM_WRITE"],
+  "evidence": [
+    { "type": "repo-research", "path": "research/import-api-suitability/stores-catalog-inventory.md" }
+  ]
+}

package/skills/wix-replatform/resources/rp-target-wix/domains/stores/entities/product-tag.json

@@ -0,0 +1,37 @@
+{
+  "schemaVersion": 1,
+  "domain": "stores",
+  "entity": "product-tag",
+  "displayName": "Stores Product Tag",
+  "target": {
+    "classification": "native",
+    "nativeEntity": "Wix Tag",
+    "verifiedFqdn": "wix.stores.catalog.v3.product",
+    "idPolicy": "server-assigned",
+    "crosswalkRequired": true
+  },
+  "sourceAliases": [
+    { "sourceSystem": "woocommerce", "sourceEntity": "product_tag", "routes": ["/wc/v3/products/tags"], "confidence": "high" },
+    { "sourceSystem": "wix", "sourceEntity": "productTag", "routes": ["Tags API scoped to product FQDN"], "confidence": "high" }
+  ],
+  "preferredWrite": {
+    "surface": "Tags",
+    "endpoint": "POST /tags/v1/tags",
+    "writerId": null,
+    "verification": "unverified",
+    "importSafe": true,
+    "bulk": false
+  },
+  "fallbacks": [
+    { "classification": "cms", "when": "Use only for source tag metadata not represented by Wix Tags." }
+  ],
+  "reliability": { "status": "partially-reliable", "flags": [] },
+  "pitfalls": [
+    { "code": "fqdn-required", "severity": "blocker", "summary": "Use the verified product FQDN and resolve tag IDs before attaching them to products." }
+  ],
+  "mappingGuidance": ["Create tags before products; attach tag IDs through product publicTags when supported."],
+  "setupRequirements": ["Wix Stores app"],
+  "evidence": [
+    { "type": "repo-research", "path": "research/import-api-suitability/stores-catalog-inventory.md" }
+  ]
+}

package/skills/wix-replatform/resources/rp-target-wix/domains/stores/entities/product.json

@@ -0,0 +1,90 @@
+{
+  "schemaVersion": 1,
+  "domain": "stores",
+  "entity": "product",
+  "displayName": "Stores Product",
+  "target": {
+    "classification": "native-plus-cms",
+    "nativeEntity": "Stores Product",
+    "verifiedFqdn": "wix.stores.catalog.v3.product",
+    "idPolicy": "server-assigned",
+    "crosswalkRequired": true
+  },
+  "sourceAliases": [
+    { "sourceSystem": "woocommerce", "sourceEntity": "product", "routes": ["/wc/v3/products"], "confidence": "high" },
+    { "sourceSystem": "wix", "sourceEntity": "storesProduct", "routes": ["Stores Catalog V1 Products", "Stores Catalog V3 Products"], "confidence": "high" }
+  ],
+  "preferredWrite": {
+    "surface": "Stores Catalog V3 Products",
+    "endpoint": "POST /stores/v3/products",
+    "writerId": "createStoresProduct",
+    "verification": "verified-live",
+    "importSafe": true,
+    "bulk": false
+  },
+  "fieldContracts": [
+    {
+      "domain": "stores",
+      "entity": "product",
+      "surface": "catalog-v3",
+      "operation": "createProduct",
+      "path": "product.subscriptionDetails",
+      "verificationLevel": "live-create-and-readback",
+      "lastVerified": "2026-07-26",
+      "verifiedBy": "migration-20260726-01",
+      "requiredPaths": [
+        "product.subscriptionDetails.allowOneTimePurchases",
+        "product.subscriptionDetails.subscriptions[]",
+        "product.subscriptionDetails.subscriptions[].title",
+        "product.subscriptionDetails.subscriptions[].description",
+        "product.subscriptionDetails.subscriptions[].frequency",
+        "product.subscriptionDetails.subscriptions[].interval",
+        "product.subscriptionDetails.subscriptions[].autoRenewal"
+      ],
+      "constraints": [
+        {
+          "path": "product.subscriptionDetails.subscriptions[].description",
+          "maxLength": 60,
+          "source": "live-validation"
+        },
+        {
+          "path": "product.subscriptionDetails.subscriptions[].frequency",
+          "enum": ["DAY", "WEEK", "MONTH", "YEAR"],
+          "source": "live-create"
+        },
+        {
+          "path": "product.subscriptionDetails.subscriptions[].interval",
+          "minimum": 1,
+          "integer": true,
+          "source": "live-create"
+        }
+      ],
+      "readback": {
+        "product.subscriptionDetails": "returned-after-create",
+        "product.subscriptionDetails.subscriptions[].id": "server-assigned",
+        "product.subscriptionDetails.subscriptions[].title": "preserved",
+        "product.subscriptionDetails.subscriptions[].description": "preserved",
+        "product.subscriptionDetails.subscriptions[].frequency": "preserved",
+        "product.subscriptionDetails.subscriptions[].interval": "preserved",
+        "product.subscriptionDetails.subscriptions[].autoRenewal": "preserved"
+      }
+    }
+  ],
+  "fallbacks": [
+    { "classification": "cms", "when": "Use for plugin rules, source-only metadata, or catalog semantics that do not fit product extended fields." }
+  ],
+  "reliability": { "status": "partially-reliable", "flags": [] },
+  "pitfalls": [
+    { "code": "catalog-v3-normalization", "severity": "blocker", "summary": "Normalize V1/simple product fields into Catalog V3 product and variant shapes before create." },
+    { "code": "variant-matrix-two-pass", "severity": "warning", "summary": "Full variable product matrices require a post-create option-choice and variant pass." }
+  ],
+  "mappingGuidance": [
+    "Create categories, tags, and media references before products when the source uses them.",
+    "Preserve recurring offers natively via product.subscriptionDetails.subscriptions[] when the source exposes clear cadence data; live create coverage was verified on July 26, 2026, while patch/update coverage remains unverified."
+  ],
+  "setupRequirements": ["Wix Stores app", "Product data extension schema when source-only product fields are preserved natively."],
+  "evidence": [
+    { "type": "repo-research", "path": "research/import-api-suitability/stores-catalog-inventory.md" },
+    { "type": "repo-research", "path": "research/source-entity-import-suitability-wordpress-woocommerce-wix.md" }
+  ]
+}

package/skills/wix-replatform/resources/rp-target-wix/lib/audit-summary.js

@@ -0,0 +1,64 @@
+'use strict';
+
+const fs = require('fs');
+
+function createBucket() {
+  return {
+    total: 0,
+    ok: 0,
+    created: 0,
+    updated: 0,
+    skipped: 0,
+    failed: 0,
+    retried: 0,
+    throttled: 0,
+  };
+}
+
+function statusOf(event) {
+  return event.status || event.resultStatus || event.result || 'unknown';
+}
+
+function entityOf(event) {
+  return event.entity || event.entityKey || event.sourceEntity || 'unknown';
+}
+
+function summarizeAuditEvents(events, { runId } = {}) {
+  if (!runId) {
+    throw new Error('summarizeAuditEvents requires runId; append-only audit logs may contain multiple attempts.');
+  }
+  const summary = {};
+  for (const event of events) {
+    if (!event || event.runId !== runId) continue;
+    const entity = entityOf(event);
+    const status = statusOf(event);
+    if (!summary[entity]) summary[entity] = createBucket();
+    summary[entity].total += 1;
+    if (Object.prototype.hasOwnProperty.call(summary[entity], status)) {
+      summary[entity][status] += 1;
+    }
+  }
+  return summary;
+}
+
+function readAuditNdjson(filePath) {
+  const text = fs.readFileSync(filePath, 'utf8').trim();
+  if (!text) return [];
+  return text.split('\n').filter(Boolean).map((line, index) => {
+    try {
+      return JSON.parse(line);
+    } catch (error) {
+      throw new Error(`Invalid audit JSON at line ${index + 1}: ${error.message}`);
+    }
+  });
+}
+
+function summarizeAuditFile(filePath, options) {
+  return summarizeAuditEvents(readAuditNdjson(filePath), options);
+}
+
+module.exports = {
+  summarizeAuditEvents,
+  summarizeAuditFile,
+  readAuditNdjson,
+};

package/skills/wix-replatform/resources/rp-target-wix/lib/contract-ledger.js

@@ -0,0 +1,141 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { readEntityByRef } = require('./domain-knowledge.js');
+
+const SCHEMA_VERSION = 1;
+
+function normalizePathPresence(verifiedPaths = []) {
+  return verifiedPaths
+    .filter((entry) => entry && entry.path && entry.present !== false)
+    .map((entry) => entry.path);
+}
+
+function createContractLedgerProposalFromStoresVerification(artifact) {
+  if (!artifact || typeof artifact !== 'object') {
+    throw new Error('verification artifact is required');
+  }
+  if (artifact.command !== 'stores subscription-create') {
+    throw new Error(`unsupported verification command: ${artifact.command || '<missing>'}`);
+  }
+  const verifiedPaths = normalizePathPresence(artifact.verifiedPaths);
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    proposalId: `stores-product-subscription-create-${(artifact.timestamp || new Date().toISOString()).slice(0, 10)}`,
+    status: artifact.status === 'passed' ? 'proposed' : 'blocked',
+    sourceVerification: {
+      command: artifact.command,
+      artifactPath: artifact.artifactPath || null,
+      targetSiteIdentifier: artifact.targetSiteIdentifier || null,
+      timestamp: artifact.timestamp || null,
+      probeRecordId: artifact.probeRecordId || null,
+    },
+    targetRef: 'stores/product',
+    fieldContract: {
+      domain: 'stores',
+      entity: 'product',
+      surface: 'catalog-v3',
+      operation: 'createProduct',
+      path: 'product.subscriptionDetails',
+      verificationLevel: 'live-create-and-readback',
+      lastVerified: artifact.timestamp ? artifact.timestamp.slice(0, 10) : null,
+      verifiedBy: artifact.targetSiteIdentifier || artifact.sourceRunId || 'live-verification',
+      requiredPaths: verifiedPaths.filter((entry) => entry !== 'product.subscriptionDetails.subscriptions[].id'),
+      constraints: Array.isArray(artifact.constraintsDiscovered)
+        ? artifact.constraintsDiscovered.map((constraint) => ({ ...constraint }))
+        : [],
+      readback: {
+        'product.subscriptionDetails': verifiedPaths.includes('product.subscriptionDetails') ? 'returned-after-create' : 'unverified',
+        'product.subscriptionDetails.subscriptions[].id': verifiedPaths.includes('product.subscriptionDetails.subscriptions[].id') ? 'server-assigned' : 'unverified',
+      },
+    },
+  };
+}
+
+function proposalKey(proposal) {
+  const contract = proposal && proposal.fieldContract;
+  return [
+    proposal && proposal.targetRef,
+    contract && contract.surface,
+    contract && contract.operation,
+    contract && contract.path,
+  ].join('|');
+}
+
+function contractKey(contract, entity) {
+  return [
+    `${contract.domain || (entity && entity.domain)}/${contract.entity || (entity && entity.entity)}`,
+    contract.surface,
+    contract.operation,
+    contract.path,
+  ].join('|');
+}
+
+function promotedContractForProposal(domainsDir, proposal) {
+  if (!proposal || !proposal.targetRef || !proposal.fieldContract) return null;
+  const entity = readEntityByRef(domainsDir, proposal.targetRef);
+  return (entity.fieldContracts || []).find((contract) => contractKey(contract, entity) === proposalKey(proposal)) || null;
+}
+
+function isProposalPromoted(domainsDir, proposal) {
+  let promoted;
+  try {
+    promoted = promotedContractForProposal(domainsDir, proposal);
+  } catch (error) {
+    return false;
+  }
+  if (!promoted) return false;
+  const expected = proposal.fieldContract || {};
+  return promoted.verificationLevel === expected.verificationLevel;
+}
+
+function readJsonIfExists(filePath) {
+  if (!filePath || !fs.existsSync(filePath)) return null;
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+function writeProposal(filePath, proposal) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(proposal, null, 2)}\n`);
+  return proposal;
+}
+
+function validateContractPromotion({ domainsDir, verificationArtifacts = [], proposalArtifacts = [] } = {}) {
+  const errors = [];
+  const proposals = proposalArtifacts
+    .map((artifactPath) => ({ artifactPath, proposal: readJsonIfExists(artifactPath) }))
+    .filter((entry) => entry.proposal);
+  const proposalsByVerification = new Map();
+  for (const { proposal, artifactPath } of proposals) {
+    const sourcePath = proposal.sourceVerification && proposal.sourceVerification.artifactPath;
+    if (sourcePath) proposalsByVerification.set(path.resolve(sourcePath), { proposal, artifactPath });
+  }
+
+  for (const artifactPath of verificationArtifacts) {
+    const artifact = readJsonIfExists(artifactPath);
+    if (!artifact || artifact.status !== 'passed') continue;
+    if (artifact.command !== 'stores subscription-create') continue;
+    const proposalEntry = proposalsByVerification.get(path.resolve(artifactPath));
+    if (!proposalEntry) {
+      errors.push(`${artifactPath}: passed verification is missing contract-ledger proposal`);
+      continue;
+    }
+    const { proposal } = proposalEntry;
+    if (proposal.status === 'deferred' || proposal.deferralReason) continue;
+    if (!isProposalPromoted(domainsDir, proposal)) {
+      errors.push(`${proposalEntry.artifactPath}: proposal is not promoted into shared target ledger`);
+    }
+  }
+
+  return { ok: errors.length === 0, errors };
+}
+
+module.exports = {
+  SCHEMA_VERSION,
+  createContractLedgerProposalFromStoresVerification,
+  promotedContractForProposal,
+  isProposalPromoted,
+  validateContractPromotion,
+  writeProposal,
+};