@wix/agent-skills 1.35.1 → 1.36.1

package/skills/wix-replatform/resources/rp-target-wix/lib/contact-extended-fields.js

@@ -1,194 +0,0 @@
-'use strict';
-
-const crypto = require('node:crypto');
-
-// The LEGACY Contacts V4 custom-field path, and only that path. A migration reaches it
-// only by routing a mapping explicitly to `contactWriteSurface: "contacts-v4"`; the default V5
-// contact goes through the Data Extension Schema helper (FQDN wix.contacts.*.contact) instead.
-// The two are never both attempted for one field, and a failure on one never falls back to the
-// other: their values live in different places (`info.extendedFields` vs
-// `extendedFields.namespaces`) and pair with different contact writers.
-//
-// API facts this relies on (docs re-read 2026-09-29):
-//   * Find Or Create Extended Field is POST /contacts/v4/extended-fields {displayName, dataType}.
-//     It matches an existing field BY DISPLAY NAME and returns `{ field, newField }`; the key is
-//     generated by Wix, so setup must persist the returned key rather than derive one.
-//   * Get Extended Field is GET /contacts/v4/extended-fields/{key} -- the read-back.
-//   * Keys cannot be changed once created; deleting a field removes its values from every contact.
-//   * Created fields land in the `custom` namespace. Documented types: Text, Number, Date, URL.
-//
-// This phase admits TEXT only, for the same reason the DES helper admits `string` only: the other
-// types have not been verified end to end, and a guessed type is how an unsupported one reaches a
-// live setup call.
-
-const WIXAPIS = 'https://www.wixapis.com';
-const EXTENDED_FIELDS_URL = `${WIXAPIS}/contacts/v4/extended-fields`;
-const SCHEMA_KIND = 'crm-contact-extended-field';
-const CONTACT_WRITE_SURFACE = 'contacts-v4';
-const EXPECTED_NAMESPACE = 'custom';
-const VERIFIED_CONTACT_DATA_TYPES = new Set(['TEXT']);
-const DOCUMENTED_CONTACT_DATA_TYPES = new Set(['TEXT', 'NUMBER', 'DATE', 'URL']);
-
-function fail(errors, code, detail) {
-  errors.push({ code, detail });
-  return errors;
-}
-
-function validateContactExtendedFieldRequirement(requirement) {
-  const errors = [];
-  if (!requirement || requirement.kind !== 'extendedFieldSchema') {
-    return { valid: false, errors: fail([], 'not-an-extended-field-requirement', 'requirement.kind must be "extendedFieldSchema"') };
-  }
-  if (requirement.schemaKind !== SCHEMA_KIND) {
-    fail(errors, 'unsupported-schema-kind', `this helper implements ${SCHEMA_KIND} only, not "${requirement.schemaKind}"`);
-  }
-  if (requirement.contactWriteSurface !== CONTACT_WRITE_SURFACE) {
-    // V4 is opt-in. Without the explicit surface this is a V5 requirement in the wrong shape.
-    fail(errors, 'contact-surface-mismatch', `${SCHEMA_KIND} requires contactWriteSurface "${CONTACT_WRITE_SURFACE}", not "${requirement.contactWriteSurface}"`);
-  }
-  if (requirement.targetRef !== undefined && requirement.targetRef !== 'crm/contact') {
-    fail(errors, 'target-ref-mismatch', `a ${SCHEMA_KIND} requirement targets crm/contact, not "${requirement.targetRef}"`);
-  }
-  if (requirement.fqdn || requirement.namespace) {
-    // The DES fields on a V4 requirement mean someone mixed the two surfaces.
-    fail(errors, 'contact-surface-mismatch', `${SCHEMA_KIND} does not take fqdn/namespace; those belong to the contacts-v5 Data Extension Schema path`);
-  }
-  if (!Array.isArray(requirement.fields) || requirement.fields.length === 0) {
-    fail(errors, 'no-fields-declared', 'a requirement with no fields provisions nothing');
-    return { valid: false, errors };
-  }
-  const seen = new Set();
-  for (const field of requirement.fields) {
-    if (!field || typeof field !== 'object') {
-      fail(errors, 'field-not-an-object', 'a field intent must be an object');
-      continue;
-    }
-    if (!field.displayName || typeof field.displayName !== 'string' || !field.displayName.trim()) {
-      fail(errors, 'missing-display-name', 'a contacts-v4 field needs a displayName; Find Or Create matches by it');
-    } else {
-      // Find Or Create matches by display name, so two fields with one name would collapse into
-      // one key and one field's values would overwrite the other's.
-      const normalized = field.displayName.trim().toLowerCase();
-      if (seen.has(normalized)) fail(errors, 'duplicate-display-name', `displayName "${field.displayName}" is declared twice`);
-      seen.add(normalized);
-    }
-    if (!field.dataType) {
-      fail(errors, 'missing-data-type', `field "${field.displayName}" has no dataType`);
-    } else if (!DOCUMENTED_CONTACT_DATA_TYPES.has(field.dataType)) {
-      fail(errors, 'unsupported-contact-data-type', `dataType "${field.dataType}" is not a Wix contact field type`);
-    } else if (!VERIFIED_CONTACT_DATA_TYPES.has(field.dataType)) {
-      fail(errors, 'unverified-contact-data-type', `dataType "${field.dataType}" is not verified for this phase; only ${[...VERIFIED_CONTACT_DATA_TYPES].join(', ')} is`);
-    }
-    if (field.expectedNamespace !== undefined && field.expectedNamespace !== EXPECTED_NAMESPACE) {
-      fail(errors, 'unexpected-contact-namespace', `created contact fields land in "${EXPECTED_NAMESPACE}", not "${field.expectedNamespace}"`);
-    }
-    if (field.writePath && !/^info\.extendedFields\./.test(field.writePath)) {
-      fail(errors, 'write-path-mismatch', `a contacts-v4 value lands under info.extendedFields, not "${field.writePath}"`);
-    }
-    if (field.writePathTemplate !== undefined && field.writePathTemplate !== 'info.extendedFields.<verifiedKey>') {
-      fail(errors, 'write-path-mismatch', `writePathTemplate must be "info.extendedFields.<verifiedKey>", not "${field.writePathTemplate}"`);
-    }
-  }
-  return { valid: errors.length === 0, errors };
-}
-
-function buildFindOrCreateContactExtendedFieldRequest({ displayName, dataType = 'TEXT' } = {}) {
-  if (!displayName) throw new Error('buildFindOrCreateContactExtendedFieldRequest: displayName is required');
-  return { method: 'POST', url: EXTENDED_FIELDS_URL, body: { displayName, dataType } };
-}
-
-function buildGetContactExtendedFieldRequest({ key } = {}) {
-  if (!key) throw new Error('buildGetContactExtendedFieldRequest: key is required');
-  return { method: 'GET', url: `${EXTENDED_FIELDS_URL}/${encodeURIComponent(key)}` };
-}
-
-// Find Or Create and Get both answer `{ field: {...} }`. Accept a bare field too.
-function normalizeContactExtendedFieldResult(response) {
-  const field = response && (response.field || (response.key ? response : null));
-  if (!field) return null;
-  return {
-    key: field.key || null,
-    namespace: field.namespace || null,
-    dataType: field.dataType || null,
-    displayName: field.displayName || null,
-    newField: response && typeof response.newField === 'boolean' ? response.newField : null,
-  };
-}
-
-// The identity a later run must see again. A receipt records it so a key that changed between
-// runs is caught instead of silently splitting a field's values across two keys.
-function contactFieldIdentity(field) {
-  return String(field.displayName || '').trim().toLowerCase();
-}
-
-// Checks one Find Or Create answer (or its read-back) against the intent and any key recorded by
-// an earlier run. Returns null when it matches.
-function describeContactFieldMismatch(intent, normalized, { priorKey = null } = {}) {
-  if (!normalized || !normalized.key) return 'the field was not returned';
-  const differences = [];
-  // Required, not merely "not wrong": a response that omits the namespace has not shown the key
-  // lives where the writer will put values, so it cannot pass verification.
-  if (normalized.namespace !== EXPECTED_NAMESPACE) {
-    differences.push(`namespace: expected "${EXPECTED_NAMESPACE}", got ${normalized.namespace ? `"${normalized.namespace}"` : 'none'}`);
-  }
-  if (normalized.dataType !== intent.dataType) {
-    // Find Or Create matched an existing field by name; it will not retype it for us.
-    differences.push(`dataType: expected ${intent.dataType}, got ${normalized.dataType}`);
-  }
-  if (normalized.displayName && contactFieldIdentity(normalized) !== contactFieldIdentity(intent)) {
-    differences.push(`displayName: expected "${intent.displayName}", got "${normalized.displayName}"`);
-  }
-  if (priorKey && normalized.key !== priorKey) {
-    differences.push(`key: an earlier setup verified "${priorKey}" but Wix now returns "${normalized.key}"; keys cannot change`);
-  }
-  return differences.length > 0 ? differences.join('; ') : null;
-}
-
-function contactFieldWritePath(key) {
-  return `info.extendedFields.${key}`;
-}
-
-// Same stamp idea as the DES helper, hashed over what a V4 consumer depends on.
-function contactExtendedFieldContractVersion(requirement) {
-  if (!requirement || !Array.isArray(requirement.fields)) return null;
-  const material = [
-    SCHEMA_KIND,
-    requirement.contactWriteSurface || '',
-    ...requirement.fields.map((field) => [contactFieldIdentity(field), field.dataType || ''].join(':')).sort(),
-  ].join('|');
-  return crypto.createHash('sha256').update(material).digest('hex').slice(0, 16);
-}
-
-// Keys an earlier receipt verified, by display-name identity, so a re-run can enforce that they
-// did not change.
-function priorContactFieldKeys(setupVerification) {
-  const entries = !setupVerification ? []
-    : Array.isArray(setupVerification.verifications) ? setupVerification.verifications
-      : Array.isArray(setupVerification) ? setupVerification : [setupVerification];
-  const keys = new Map();
-  for (const entry of entries) {
-    if (!entry || entry.schemaKind !== SCHEMA_KIND) continue;
-    for (const verified of entry.verified || []) {
-      if (verified && verified.displayName && verified.key) keys.set(contactFieldIdentity(verified), verified.key);
-    }
-  }
-  return keys;
-}
-
-module.exports = {
-  EXTENDED_FIELDS_URL,
-  SCHEMA_KIND,
-  CONTACT_WRITE_SURFACE,
-  EXPECTED_NAMESPACE,
-  VERIFIED_CONTACT_DATA_TYPES,
-  DOCUMENTED_CONTACT_DATA_TYPES,
-  validateContactExtendedFieldRequirement,
-  buildFindOrCreateContactExtendedFieldRequest,
-  buildGetContactExtendedFieldRequest,
-  normalizeContactExtendedFieldResult,
-  describeContactFieldMismatch,
-  contactFieldIdentity,
-  contactFieldWritePath,
-  contactExtendedFieldContractVersion,
-  priorContactFieldKeys,
-};

package/skills/wix-replatform/resources/rp-target-wix/lib/contact-import.js

@@ -1,133 +0,0 @@
-'use strict';
-const w = require('./wix-writers');
-const v = require('./write-verification');
-const { contactId } = require('./bulk-results');
-const stateIO = require('../../../lib/write-verification-state');
-const local = require('../../../lib/local-state');
-const sleepDefault = ms => new Promise(resolve => setTimeout(resolve, ms));
-
-// Schema: Contacts V5 Find Matching Contacts (GET); keep every primary identifier.
-async function findMatching(wix, expected) {
-  const params = new URLSearchParams();
-  if (expected.externalId) params.set('externalId', expected.externalId);
-  if (expected.email?.email) params.set('email', expected.email.email);
-  if (expected.phone?.phone) params.set('phone', expected.phone.phone);
-  const result = await wix.send({ method: 'GET', url: `https://www.wixapis.com/contacts/v5/contacts/find-matching?${params}` });
-  if (!Array.isArray(result?.contacts) || result.contacts.length >= 100) throw new Error('Contact lookup is malformed or may be truncated');
-  return result.contacts;
-}
-async function importContacts(wix, { projectDir, siteId, rows, verifyAttempts = 3, sleep = sleepDefault, dryRun = false } = {}) {
-  if (!projectDir || !siteId || !Array.isArray(rows) || !Number.isInteger(verifyAttempts) || verifyAttempts < 1 || verifyAttempts > 5) throw new Error('Invalid contact import arguments');
-  if (rows.some(r => typeof r.sourceKey !== 'string' || !r.sourceKey) || new Set(rows.map(r => r.sourceKey)).size !== rows.length) throw new Error('Unique source keys required');
-  return local.withStateLock(projectDir, async () => {
-    const state = await stateIO.load(projectDir, siteId);
-    const crosswalk = await local.loadCrosswalk(projectDir);
-    const work = rows.map(row => {
-      try {
-        v.assertProjection(row.contact, 'contact');
-        const expected = w.buildCreateContactRequest({ contact: row.contact }, row.safeModeOptions).body.contact;
-        v.assertProjection(expected);
-        const limits = [[expected.externalId, 100], [expected.name?.first, 1000], [expected.name?.last, 1000], [expected.email?.email, 320], [expected.phone?.phone, 50]];
-        if (limits.some(([value, max]) => value != null && (typeof value !== 'string' || value.length > max))) throw new Error('Contact field exceeds its declared type or limit');
-        for (const [key, max] of [['additionalEmails', 10], ['additionalPhones', 10], ['addresses', 50]]) if (expected[key] != null && (!Array.isArray(expected[key]) || expected[key].length > max)) throw new Error(`Contact ${key} exceeds its declared array limit`);
-        return { ...row, baseline: crosswalk.bySource[row.sourceKey] || state.rows[row.sourceKey]?.baseline || null, expected, uncertain: Boolean(state.rows[row.sourceKey]?.uncertain), targetId: state.rows[row.sourceKey]?.targetId || crosswalk.bySource[row.sourceKey]?.targetId || state.rows[row.sourceKey]?.baseline?.targetId || null };
-      } catch (e) { return { ...row, baseline: crosswalk.bySource[row.sourceKey] || state.rows[row.sourceKey]?.baseline || null, targetId: state.rows[row.sourceKey]?.targetId || crosswalk.bySource[row.sourceKey]?.targetId || state.rows[row.sourceKey]?.baseline?.targetId, uncertain: state.rows[row.sourceKey]?.uncertain, error: e.message }; }
-    });
-    // Resolve the entire input set before writes: even a later row can conflict with an earlier one.
-    const shared = new Map();
-    for (const r of work) for (const [key, value] of Object.entries({ externalId: r.expected?.externalId, email: v.email(r.expected?.email?.email), phone: r.expected?.phone?.phone })) {
-      if (!value) continue;
-      const k = `${key}:${value}`;
-      if (!shared.has(k)) shared.set(k, []);
-      shared.get(k).push(r);
-    }
-    for (const group of shared.values()) if (group.length > 1) for (const r of group) r.error = 'Conflicting source contact identifiers';
-    if (dryRun) return { siteId, intended: rows.length, status: 'simulated', verified: 0, rows: work.map(r => ({ sourceKey: r.sourceKey, verified: false, outcome: 'simulated' })) };
-    for (const r of work) {
-      if (r.error) continue;
-      try {
-        if (!r.expected.externalId && !v.email(r.expected.email?.email)) throw new Error('Phone-only or name-only identity is unsupported');
-        const candidates = await findMatching(wix, r.expected);
-        if (candidates.length > 1 || candidates.some(c => !v.contactIdentity(r.expected, c, c.id).verified)) throw Object.assign(new Error('Conflicting target contact identity'), { identityConflict: true });
-        if (r.targetId) {
-          if (!contactId(r.targetId)) throw Object.assign(new Error('Invalid candidate contact ID'), { identityConflict: true });
-          const known = await w.getContact(wix, r.targetId);
-          if (!v.contactIdentity(r.expected, known, r.targetId).verified) throw Object.assign(new Error('Crosswalk contact identity does not agree'), { identityConflict: true });
-          if (candidates.length && candidates[0].id !== r.targetId) throw Object.assign(new Error('Crosswalk and matching lookup disagree'), { identityConflict: true });
-          r.actual = known;
-        } else if (candidates.length) { r.targetId = candidates[0].id; r.actual = await w.getContact(wix, r.targetId); }
-        else if (state.rows[r.sourceKey]?.uncertain) throw new Error('Previous write outcome is uncertain; reconcile before retry');
-        if (r.actual && !v.verifyContact(r.expected, r.actual, r.targetId).verified) throw new Error('Existing contact values differ; use the revision-protected update and conflict-review flow');
-        if (r.targetId && crosswalk.rows.some(c => c.sourceStableKey !== r.sourceKey && c.targetSystem === 'wix' && c.targetId === r.targetId)) throw Object.assign(new Error('Target contact belongs to another source key'), { identityConflict: true });
-      } catch (e) { r.error = e.message; r.identityConflict = Boolean(e.identityConflict); }
-    }
-    for (const r of work) if (r.targetId && work.some(other => other !== r && other.targetId === r.targetId)) { r.error = 'Distinct source keys share a target contact'; r.identityConflict = true; }
-    const save = r => {
-      const previous = state.rows[r.sourceKey];
-      const lastVerifiedReceipt = v.validReceipt(previous?.receipt) ? previous.receipt : previous?.lastVerifiedReceipt || null;
-      state.rows[r.sourceKey] = { sourceKey: r.sourceKey, targetId: r.targetId, baseline: r.baseline, identityConflict: Boolean(r.identityConflict),
-        outcome: r.outcome || 'needs_verification', uncertain: Boolean(r.uncertain), error: r.error || null, receipt: r.receipt || null, lastVerifiedReceipt };
-    };
-    for (const r of work) save(r);
-    await stateIO.checkpoint(projectDir, state, work);
-    const pending = work.filter(r => !r.error && !(r.actual && v.verifyContact(r.expected, r.actual, r.targetId).verified));
-    const batches = [];
-    for (const memberMode of [false, true]) {
-      const selected = pending.filter(r => (r.updateMember === true) === memberMode);
-      for (let start = 0; start < selected.length; start += 100) batches.push(selected.slice(start, start + 100));
-    }
-    for (const group of batches) {
-      for (const r of group) { r.uncertain = true; save(r); }
-      await stateIO.checkpoint(projectDir, state, group);
-      try {
-        // Sanitize once per source record, never with one shared batch identity.
-        const result = await w.bulkUpsertContacts(wix, group.map(r => r.expected), { updateMember: group[0].updateMember === true }, { safeMode: false });
-        for (const outcome of result.results) {
-          if (!outcome.correlated) continue;
-          const r = group[outcome.index];
-          if (outcome.success) {
-            if (r.targetId && r.targetId !== outcome.contactId) { r.error = 'Upsert returned a different contact identity'; continue; }
-            r.targetId = outcome.contactId; r.uncertain = false; r.confirmedCreate = true;
-          } else { r.error = outcome.errorCode || 'Contact write failed'; r.uncertain = false; }
-          save(r);
-        }
-        for (const index of result.unresolvedIndexes) { group[index].error = 'Unresolved bulk contact result'; save(group[index]); }
-      } catch (e) {
-        for (const r of group) {
-          r.error = e.message;
-          if ([401, 403].includes(e.status || e.statusCode)) r.uncertain = false;
-          save(r);
-        }
-      }
-      await stateIO.checkpoint(projectDir, state, group);
-    }
-    for (const r of work) if (r.targetId && work.some(other => other !== r && other.targetId === r.targetId)) { r.error = 'Distinct source keys share a target contact'; r.identityConflict = true; }
-    const publications = [];
-    let verifiedBatch = [];
-    for (const r of work) {
-      if (!r.error && r.targetId) for (let attempt = 1; attempt <= verifyAttempts; attempt++) {
-        try {
-          const actual = await w.getContact(wix, r.targetId);
-          if (!v.contactIdentity(r.expected, actual, r.targetId).verified) r.identityConflict = true;
-          r.receipt = v.receipt({ siteId, sourceKey: r.sourceKey, kind: 'contact', expected: r.expected, actual, targetId: r.targetId, operation: 'bulkUpsertContacts', attempts: attempt });
-          if (r.identityConflict) break;
-          if (r.receipt.verified) { r.outcome = 'verified'; r.uncertain = false; break; }
-        } catch (e) { r.readError = e.message; }
-        if (attempt < verifyAttempts) await sleep(100 * attempt);
-      }
-      if (!r.receipt?.verified) { r.error ||= r.readError || 'Contact values could not be verified'; r.outcome = 'needs_verification'; }
-      save(r);
-      if (r.outcome === 'verified') publications.push({ row: {
-        schemaVersion: 1, sourceSystem: r.sourceSystem || 'source', sourceEntityType: 'contact', sourceId: r.sourceId || r.sourceKey,
-        sourceStableKey: r.sourceKey, targetSystem: 'wix', targetEntityType: 'contact', targetId: r.targetId, status: 'imported',
-      }, receipt: r.receipt, options: r });
-      verifiedBatch.push(r);
-      if (verifiedBatch.length === 100) { await stateIO.checkpoint(projectDir, state, verifiedBatch); verifiedBatch = []; }
-    }
-    await stateIO.checkpoint(projectDir, state, verifiedBatch);
-    await stateIO.persist(projectDir, state);
-    await stateIO.publishMany(projectDir, publications, work.filter(r => r.identityConflict).map(r => r.sourceKey));
-    return stateIO.report(work.map(r => state.rows[r.sourceKey]), siteId);
-  });
-}
-module.exports = { findMatching, importContacts };

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

@@ -1,150 +0,0 @@
-'use strict';
-
-const fs = require('node:fs');
-const path = require('node:path');
-const { readEntityByRef } = require('./domain-knowledge.js');
-
-const { verifySubscriptionEvidence } = require('./write-verification');
-const SCHEMA_VERSION = 1;
-const validEvidence = artifact => artifact && artifact.status === 'passed' && artifact.probeRecordId === artifact.valueEvidence?.targetId && verifySubscriptionEvidence(artifact.valueEvidence).verified;
-
-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: validEvidence(artifact) ? '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: validEvidence(artifact) ? 'live-create-and-readback' : 'unverified',
-      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.command !== 'stores subscription-create') continue;
-    if (!validEvidence(artifact)) {
-      errors.push(`${artifactPath}: missing or invalid identity/value verification`);
-      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 (proposal.status !== 'proposed' || proposal.fieldContract?.verificationLevel !== 'live-create-and-readback') {
-      errors.push(`${proposalEntry.artifactPath}: invalid verification proposal`);
-      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,
-};