Rp Target Wix

Wix target adapter. Owns the Wix-side write surface and shared execution runtime that every migration shares — verified once here so the platform-agnostic stages and per-project codegen never re-derive (and re-break) it. This is the symmetric counterpart to rp-source-wordpress: that adapter owns reading a source platform; this one owns writing to Wix.

Verified variant inventory import

lib/stores-inventory.js exports inventoryForVariant, resolveInventoryLocation, and reconcileInventory(wix, rows, {expectedCount, gaps, locationId?}). Rows carry resolved productId, variantId, and inventory: {inStock:boolean} OR {quantity:integer}. expectedCount must equal rows plus named source gaps. Bulk writes follow complete location- scoped reads; existing items reconcile or update by revision, then values and availability are read back. Failure remains partial and the next invocation re-reads before writing. The existing single-create inventory helpers remain available for narrow probes; imports use the bulk reconciliation path. trackQuantity is derived and must never be sent. Read domains/stores/entities/inventory-item.json and the setup inventory-probe contract.

When this skill is used

Not a stage in the flow — a reference + shared library consulted by:

• rp-import-codegen vendors lib/wix-writers.js into the project (like the wp-http transport) plus the shared write/setup runtime modules, and generates thin project-specific write specs/transforms that call these primitives/runtime APIs. Codegen does not re-emit Wix API plumbing.
• rp-setup-discovery / rp-execute-setup consult the “Verified endpoints” and “Provisioning” notes for app-install / Wix-Data / collection mechanics.

Because the Wix surface is identical across source platforms, adding a new source (rp-source-shopify, …) requires no change here.

Shared runtime boundary

App page routing

app-page-routing-capabilities.json is the per-family gate for lib/app-page-routing.js and scripts/internal-link-audit.js route. The shared lib/url-mapper-transport.js builds writer-side create/update/read requests over an injected authenticated sender and requires destination inspection. Only the Stores product URL Mapper payload currently has a recorded request and saved-state read-back shape. Its writer-side pattern may be configured after Stores installation and before frontend creation, but it is not evidence that the frontend serves that route. The generated transport supplies the migration credential and writer-side read/write methods; the public reader’s empty mapping is not a valid read-back. Use the recorded request and read-back fixture in app-page-routing-capabilities.json.

Every other discovered app family remains unverified until its exact key, page identifier, variables, supported method, request and read-back fixture are committed to the capability file and tested. Portfolio and Builder Blog remain unverified. Never infer one family’s adapter from another or use full-site registration. A missing or conflicting route produces a local route result and an Import Operator item; it does not become a served route through the URL ledger.

This adapter owns the shared Wix layer written once for all migrations.

It should own:

• verified request builders and endpoint primitives
• shared Wix client/auth handling
• shared retry and throttling policy
• generic write execution runtime
• generic setup execution/runtime behavior
• checkpoint helpers
• local crosswalk helpers (state/crosswalk/crosswalk.ndjson authority, append-only attempt journal, optional CMS mirror seed/upload adapters)
• URL preservation helpers (state/url-preservation/ base paths, ledger, planned redirects, and unresolved route rows) and the SEO Redirects writer (lib/seo-redirects.js: Bulk Create only, declared APP/WIX_USER identity with Manage SEO Settings, no forceReplace, durable write intents and List Redirects reconciliation; user-token API create/read-back verified, frontend serving and full live acceptance still unverified)
• NDJSON record-stream I/O (lib/ndjson.js): streaming read/write, batching by count and by cost, cursoring, and append-only producers. Migration data files are record streams, so the scan/batch/cursor primitives live here once instead of being re-derived by codegen.
• audit log emission
• compact execution report generation
• contract tests for stable request/runtime behavior

Per-migration code generation should own only:

• field maps
• transforms
• write specs
• setup-plan renderings
• entity ordering
• dependency wiring — populate WriteSpec.dependencyRefs from each in-scope entity’s domain-knowledge dependsOn field, not re-derived per project

Write contract (the verified Wix surface)

Capability and dependency boundary

createWixClient accepts only object-identity capabilities issued by the shared runtime. An unprivileged client admits registered read builders only; a raw request is not a trusted read. Import clients require a bound task plus the gate’s current per-batch readinessGrant and sourceStableKey on every write, including auxiliary writes and dry-run captures. Every import write must retain the closed writer builder’s object identity and sealed method, URL, body and headers. A raw, copied or modified request is refused even with a valid grant; use the shared marked builders and grant wrappers. Use writers.bindRecordClient(taskClient, { readinessGrant, sourceStableKey }) for library composites, or writers.withReadinessGrant(request, { readinessGrant, sourceStableKey }) for individual builders; these preserve trusted builder marks. Before standard product inventory reconciliation, read the current product through that record client and call registerImportInventoryScope(recordClient, canonicalProduct, targetProduct). It requires a same-record successful product write or current site-bound crosswalk, correlates variants by choices, and binds stock to that record, product, variants and read location/item revisions. Standard reviewed quantity/location behavior remains available; quick Shopify retains its separate boolean/default-location scope. A serialized/copied capability, caller phase or stale/foreign-site grant is refused before transport. Setup and quick mode use their own bounded issuers, never an import bypass. Disposable probes require the explicit ownership confirmation and are restricted to the shipped verification callers.

Use lib/dependency-readiness.js for producer binding, task evaluation and record-level reference resolution. Its closed states distinguish complete, empty, partial, setup-passed, approved/unapproved exclusion and unknown evidence. Setup remains task-complete. The diagnostic projection is not an input. Keep latest journal outcomes, site-bound pass evidence and existing contact/product verification as the authority; task ordering alone cannot grant write permission.

Quick mode loads only its shipped adapter contract and keeps declared dependencies in contract order. Shopify product capability additionally admits exactly product tags and bounded inventory work for products created/read through that same client. Inventory still correlates real product, variant, item and location evidence, preserves partial stock outcomes, and never receives a raw-transport or probe exception.

lib/wix-writers.js exposes pure request builders (build*Request) + executors. Shapes marked VERIFIED were validated by a real call against a live site, not just read from docs. Shapes marked UNVERIFIED are docs-schema/MCP-derived bootstrap primitives that must be surfaced in execution plans until a live contract call promotes them. It also exports sendDirectRest for dev-probe capabilities only: its requests carry no request mark, so an import, setup or quick client refuses them as writes. A native entity this adapter has no reviewed writer for is written by guarded raw requests (sendGuardedRawRequest, below), never by sendDirectRest.

This resource should also expose shared execution-runtime modules above those primitives, so generated migrations use one common path for retries, throttling, checkpointing, reporting, and audit logging.

Read/return contract for query* executors. Every query* executor (queryStoresProducts, queryStoresCategories, queryContacts, queryCoupons, queryOrders) unwraps the response to the entity array and returns one page, discarding pagingMetadata. Two failure modes follow, both of which have shipped:

• The return value IS the array. Reading .products / .categories off it a second time gives undefined → []. A dedupe index or existing-entity safety net then comes back empty without erroring, which is indistinguishable from a fresh site — so the import duplicates what is already there, and a setup verification reports 0 categories on a site with 25.
• These executors cannot be cursor-paged, because the cursor is in the metadata they discarded. Use a queryAll* primitive where one exists — queryAllStoresCategories, queryAllStoresProducts, queryAllDataItems — otherwise send wix.send(build<X>Request(body)) and read pagingMetadata.cursors.next off the raw response.

Every sweep used for dedupe must throw on a partial result rather than return it. “Empty net” and “empty store” look identical to the caller, and the caller assumes the second.

Domain entity suitability knowledge

Target entity suitability lives in domains/, not in a large prose table in this skill. Use the deterministic reader as the normal access path:

node scripts/domain-knowledge.js list-domains
node scripts/domain-knowledge.js list-entities --domain stores
node scripts/domain-knowledge.js read-entity --ref stores/product
node scripts/domain-knowledge.js resolve-source --source-system woocommerce --source-entity product
node scripts/domain-knowledge.js resolve-source --route /wc/v3/products
node scripts/domain-knowledge.js list-flagged --flag IMPORT_UNRELIABLE
node scripts/domain-knowledge.js summarize-entities --refs stores/product,ecom/order

domains/index.json is generated from domain/entity files and checked in. After editing domain knowledge, run:

node scripts/domain-knowledge-validate.js --write-index

Authoring or editing any entity file also requires the dependency check, both directions: (1) what does this entity need to already exist and be crosswalked — record it in dependsOn: string[] (a domain/entity ref array; empty is a real, reviewed answer, not the same as the field being absent); (2) does this entity change what an already-written entity’s dependsOn should say (e.g. authoring gift-cards/gift-card should have prompted revisiting ecom/order.json — it hadn’t, until it was caught by hand). domain-knowledge-validate.js checks dependsOn refs resolve and the whole graph stays acyclic whenever the field is present, but it is not yet required on every entity — node scripts/domain-knowledge-validate.js --list-missing-deps prints the live backlog of entities that have never had it authored at all; that command is the source of truth, not a hand-maintained list.

domains/SERVICE-PLUGINS.md covers the escalation ladder for a source capability with no native Wix primitive: native primitive first, always, then a Wix service plugin (Wix calls an endpoint we host and we answer per request), and only then a recorded gap. It carries the cost list, a worked example — bounded quantity discount bands, implemented live 2026-08-31 — and a catalog of all 25 service plugins with per-plugin migration relevance. Read it before writing “Wix cannot express this” into a gap report.

Operation contracts. operationContracts.<operation> records, per reviewed write operation, what each dependsOn ref means for that operation: conditional, guardedPaths (payload paths that would carry a reference needing a separate producer; a { path, equals } guard matches one value, such as the Gift Cards catalog appId), creatingPaths plus withinWrite { completion, outcome, identityOutput, verification } when the write itself creates or resolves the dependency, inapplicable { reason } when the entity-level edge does not apply to that operation, secondaryOutputs (identities the write returns that another dependent may use after read-back), childOutputs (many child identities the write creates, each keyed by its own source key and proven by the parent’s verified write receipt: a product’s variants; the child entity file names its parent in childOf), auxiliaryOperations, and recovery.reconciliationKeys for identity recovery after an uncertain write. evidence is prose and excluded from the operationContractDigest that mapping proofs bind; every other field is semantic, so changing it invalidates those proofs. Add an entry only from verified API evidence; a missing entry or empty guardedPaths means “unknown” and keeps the separate producer requirement. setupProducible: true marks an entity setup may produce when no import task writes it; when an import task writes it, the import owns it and no setup step may claim it. The flag must match setup: an entity a named setup executor writes (SETUP_EXECUTOR_ENTITY_REFS in lib/setup-verification.js) carries it, and a flagged entity has that executor or a build* writer in WRITE_BUILDERS_BY_ENTITY. The selected targets’ support rules and reliability flags bind reconciliation freshness. Member create helpers/builders are aliases of createMember.

writerId values in entity files must match exported functions from lib/wix-writers.js; use null for setup/manual work or native entities with no writer yet. An entity with a builder in WRITE_BUILDERS_BY_ENTITY names it as writerId (for example stores/product-tag uses buildCreateStoresProductTagRequest). A native entity with writerId: null and no such builder is written by guarded raw requests; its write operation is sendGuardedRawRequest. A task’s write operation on a native or native-plus-cms entity must be a writer for that entity (its writerId, an operation contract name, alias or auxiliary operation, or a function listed for it in WRITE_BUILDERS_BY_ENTITY or WRITE_HELPERS_BY_ENTITY, such as ensureCoupon and bulkCreateCoupons), or the raw path when it has none; another entity’s writer does not count, and an entity with a reviewed writer cannot use the raw path (scripts/import-contract-verify.js refuses either with MISSING_WRITER). A writer listed in the entity’s own alternateWrites counts only when it is exported, importSafe: true and verification: verified-live, and the entity is not import-unsafe; otherwise the gate names the reason and the default writer (MISSING_WRITER:<task>:<ref>:alternate-unverified:use bulkUpsertContacts). List every new marked builder there; the contract test re-derives the map from the markRequest calls. A reviewed wrapper that writes only through its entity’s writer or builders goes in WRITE_HELPERS_BY_ENTITY.

Entity files may also expose fieldContracts[] for verified nested write paths. These are machine-readable contracts for codegen and dry-run validators, not replacements for the human notes below. For Stores products, domains/stores/entities/product.json records the verified Catalog V3 create contract for product.subscriptionDetails, including required nested paths, allowed recurrence values, read-back behavior, and the live-validated subscriptions[].description <= 60 constraint. Generated transforms should consume that metadata through the vendored wix-writers.js exports instead of copying limits into project-local code.

Live verification helpers must not edit domains/ directly. When a probe changes a target write assumption, emit a proposal artifact and let the orchestrator promote it deliberately:

node skills/wix-replatform/resources/rp-target-wix/scripts/verify-stores.js stores subscription-create \
  --artifact migrations/<project>/setup/stores-subscription-verification.json \
  --proposal-artifact migrations/<project>/setup/contract-ledger-proposal.json

Use lib/contract-ledger.js to validate the handoff: a passed verification without a proposal is incomplete, and a proposal that is neither promoted into fieldContracts[] nor explicitly deferred is stale product knowledge. Codegen should consume fieldContracts[] through scripts/domain-knowledge.js summarize-entities, which includes promoted contracts.

Dual product descriptions

When a canonical product contains both shortDescription and description, lib/wix-build.js writes one Stores plainDescription: short body, <hr />, then long body. HTML-empty bodies and normalized, case-insensitive lorem ipsum… filler are treated as empty independently, so a real companion body remains. The horizontal-rule serialization is unverified in a live Wix storefront: canary it and capture a Hebrew/RTL screenshot before any bulk import or remediation backfill.

Contact fields

Writers send emails and phones exactly as given; nothing replaces them (safe mode was removed; notifications rely on the site mute). Target domain entity files may define contactFields[] with { kind, targetPath, source, notes } entries naming the request-body paths that carry an email or phone. The order contact-field rules (order-history.js) read their list from ecom/order‘s contactFields[].

Stores subscription validation

lib/wix-writers.js exports the Stores subscription contract and deterministic helpers:

• STORES_SUBSCRIPTION_CONTRACT
• normalizeStoresProductSubscriptions
• validateStoresProductSubscriptionDetails

Generated import code should call the normalizer from product transforms and the validator during dry-run and immediately before live create. Validation failures are record-level preflight failures/deferred outcomes; do not send known-invalid subscription payloads to Wix to discover field errors live.

Catalog V3 subscriptions are a native Stores target, not an automatic CMS fallback or semantic loss. Product create with subscriptionDetails.allowOneTimePurchases and subscriptions[] entries containing title, description, frequency, interval, and autoRenewal was verified live on 2026-07-26; Wix returned server-assigned subscription option ids. Mapping/codegen should emit native recurring product creates when the source cadence is known. General subscription patching remains unverified.

Stores live verification helpers

Use the shared Stores verification CLI for live target checks that would otherwise become migration-local snippets:

node skills/wix-replatform/resources/rp-target-wix/scripts/verify-stores.js stores subscription-create \
  --artifact migrations/<project>/setup/stores-subscription-verification.json \
  --proposal-artifact migrations/<project>/setup/contract-ledger-proposal.json
node skills/wix-replatform/resources/rp-target-wix/scripts/verify-stores.js stores product-count \
  --project migrations/<project> \
  --artifact migrations/<project>/execution/stores-product-count-verification.json
node skills/wix-replatform/resources/rp-target-wix/scripts/verify-stores.js stores product-by-source-marker \
  --marker-path customFields.sourceId --marker-value <source-id> \
  --artifact migrations/<project>/execution/stores-product-marker-verification.json
node skills/wix-replatform/resources/rp-target-wix/scripts/verify-stores.js stores delete-probe \
  --product-id <probe-product-id> \
  --artifact migrations/<project>/setup/stores-probe-cleanup.json

The CLI reads WIX_AUTH_TOKEN and WIX_SITE_ID from the environment or config/wix.env under the current project root, creates the shared Wix client, and sends requests through wix.send(...). It writes machine-readable artifacts with the target site id, endpoint, method, verified nested paths, discovered constraints, probe id, cleanup status, warnings, recovery instructions, and timestamp. Failed probe cleanup is not hidden: the artifact must remain with an explicit warning and a delete-probe recovery command.

Routed URL preservation behavior

URL preservation is a mapping and execution-state concern. This adapter owns only the Wix-side facts that generated code may rely on when deciding whether a final target URL is known.

Current import-only phase rules:

• Do not configure Wix redirects or site routing.
• Do not guess a destination relative URL from a slug when Wix route behavior has not been verified for that entity and delivery mode.
• When the destination base path or final URL is unknown, write URL ledger rows with urlStatus: "pending_target_route" or target_url_missing and record unresolved rows for the future website-builder phase.
• When a Wix create/update response or a safe declared lookup returns a final slug or relative path, generated code may record it as actualTargetSlug or actualTargetRelativeUrl and write a redirect plan if it differs from the source URL.

Known routed entity status:

Shared execution runtime contract

In addition to endpoint primitives, this adapter should define the reusable runtime API that generated migrations call.

Conceptual contracts:

executeWriteSpec({
  spec,
  items,
  client,
  dryRun,
  runContext,
}): Promise<WriteExecutionReport>

executeSetupPlan({
  plan,
  client,
  dryRun,
  runContext,
}): Promise<SetupExecutionReport>

The exact filenames are implementation details, but the shared runtime should be the single place that owns generic Wix execution mechanics.

WriteSpec contract

Generated migrations should pass a declarative WriteSpec into the shared runtime.

Each spec should define, as applicable:

• entity
• mode: create | update | upsert | bulk_create | bulk_upsert
• create
• update
• lookup
• bulk
• batchSize
• concurrency
• retryPolicy
• throttlePolicy
• auditKeys
• crosswalkAuthority: "local"
• cmsMirror
• crosswalkStrategy
• reconciliationStrategy
• dependencyRefs
• verificationLevel: verified | unverified

This resource should document how each field is interpreted by the runtime.

WriteExecutionReport contract

The shared runtime should return a compact, token-aware report suitable for the agent.

It should include:

• run ID
• entity
• counts: input, attempted, created, updated, skipped, failed, retried, throttled
• grouped error buckets
• references to fuller on-disk logs

The runtime should prefer grouped summaries over raw per-record detail.

These per-entity or per-phase reports are intermediate runtime outputs. They are inputs to the final completion artifact, not replacements for it.

Completion artifact contract

The shared runtime should support deterministic emission of a final machine-readable completion artifact for the whole run.

Preferred output:

• execution/completion-report.json

This artifact should be the authoritative source for:

• final run status
• final imported/updated/skipped/failed counts
• separate dry-run counts when dryRun: true: requests built, Wix calls skipped, would-create/update/delete, would require live lookup, and local validation failures
• grouped skipped/deferred outcomes
• grouped failure outcomes
• dashboard/editor/preview destinations
• artifact references for audit/error/execution logs

The shared runtime should also support deterministic rendering inputs for:

• execution/review/completion-summary.md

The rendered summary should be derived from completion-report.json, not independently invented by the agent.

Audit log contract

The shared runtime should emit append-only machine-readable audit events.

Preferred format: NDJSON.

Each event should capture, at minimum:

• timestamp
• run ID
• phase: setup | import
• entity
• operation
• source ID when applicable
• target ID when known
• endpoint or primitive used
• attempt number
• result status
• HTTP status or platform error code when applicable
• latency

The run ID is required because audit files are append-only across dry-runs, retries, and recovery passes. Completion reports should be generated from runtime counters for the current run and may use audit aggregation only when filtered by run ID. The shared lib/audit-summary.js helper enforces this filter for fallback/verification summaries.

Dry-run runtime contract

The shared Wix runtime exports createDryRunConfig, normalizeDryRunValue, createWixClient, and createWixSetupExecutor.

Dry-run is enabled by DRY_RUN=true or by the generated entrypoint’s --dry-run flag. It is disabled by default. true, 1, yes, and on enable it; false, 0, no, and off disable it.

When createWixClient({ dryRun: true }) is used:

• authToken and siteId may be blank unless the generated project requires the site ID for a local artifact namespace;
• send() must not call fetch, SDK, MCP, or CLI transports;
• send() must capture the would-send request under state/attempts/wix-request-captures.ndjson when projectDir or requestCapturePath is supplied;
• captured headers must omit Authorization and redact secret-like header/body keys;
• response payloads must preserve the live shape expected by writer helpers, for example { contact }, { product }, { dataItem }, { file }, or an expected collection field such as { contacts: [] } for skipped queries.
• writers that read back what they wrote (events, forms, gift cards, add-ons, bookings, plan orders, labels, member Abouts, SEO) get answers from this dry run’s own writes (lib/dry-run-target.js), and those placeholder responses count as the record’s evidence for its follow-up calls, the same as live responses; the shared target read pacer never waits in a dry run.

Dry-run placeholder target IDs are not live authority. If downstream local execution needs them, write them only to state/crosswalk/dry-run-crosswalk.ndjson or keep them in memory. Never append simulated target IDs to state/crosswalk/crosswalk.ndjson and never upload them to a CMS crosswalk mirror.

When createWixSetupExecutor({ dryRun: true }) is used, each setup step must first be reduced to a structured intent, then captured as planned_dry_run without invoking MCP, CLI, SDK, or REST transports that access or mutate Wix account/site state.

Artifact authority at run completion

The shared runtime contract should preserve explicit artifact authority:

1. execution-log.md for chronology and operator/debug context only
2. completion-report.json for final outcome
3. completion-summary.md for deterministic user-facing rendering

The runtime should not force downstream consumers to reconstruct final outcome by reading raw audit logs or chronological execution logs.

A rejected write and a write of unknown outcome are different results

createWixClient().send checks the response status before it tries to read the body, and every failure it throws says which of two things happened:

• Rejected. The response body parsed. The target made a decision and stands behind it. outcomeKnown: true, status set, body parsed, applicationErrorCode populated when the envelope carried one. Report it and classify it by status; only the duplicate-protected transient paths below may retry.
• Unknown. The body did not parse — a gateway or protection layer answered ahead of the service with an HTML error page — or the transport threw before any response arrived. outcomeKnown: false, with rawBody holding the first 400 characters of what actually came back and status set to what the target returned (null only when no response arrived at all). Nobody knows whether the write was applied, and the honest report says so.

A 2xx whose body does not parse is unknown, not a success: it usually means the request never reached the service, and returning null there is how an unwritten record becomes a written one in the report. An empty body on a 2xx is not unparseable and still returns null, as several Wix deletes answer exactly that way.

describeError carries outcomeKnown: false through to the results ledger, so the distinction survives being written down.

One exported test decides whether a failure is worth trying again: isTransientWixError (with TRANSIENT_WIX_STATUSES), from lib/wix-writers.js. It keys on the target’s numeric status (429, 500, 502, 503, 504) and on the no-response-at-all marker, and on nothing else — never on the error’s message text, which is truncated at 400 characters by design, and never on applicationErrorCode, in either direction. 403 is excluded: it is one endpoint’s observed throttle and a real permission failure everywhere else. No caller may define its own copy.

It answers “is this condition likely to clear”. It does not answer “is it safe to try again” — only the call site knows that. Exactly two write paths retry (3 attempts, with 500 / 1500 ms between attempts): the order import and the reconcile-plus-payment-write pair, both inside importOrderHistory, and both only because they reconcile against the target first. Nothing else does, because a write that is not reconciled first and fails after the target committed would be retried into a duplicate record.

A 429 is the one exception, and the client handles it, not the caller. Wix refuses a rate-limited request before processing it, so createWixClient‘s send sends the same request again, for a read or a write: it waits Retry-After (capped at 30 s, plus jitter), else jittered exponential backoff from 1 s, up to RATE_LIMIT_POLICY.maxRetries (5) more tries. The pacing it learns is per endpoint (site + method + path, ids folded) and shared by every client in the process: a 429 widens that endpoint’s spacing, a Retry-After holds it shut for every caller, and clean replies narrow it again (client.rateLimitStats counts waits per endpoint). Every Wix API, single or bulk, gets this because every request goes through send. A few writers keep an older retry of their own on top (Ricos conversion, plan-order create, product media rounds, the read pacer, quick Shopify); their waits now add to the client’s. Only a 429 that outlasts every retry reaches the caller. It carries requestApplied: false, so the raw-request journal records it as refused, not unknown, and importProducts leaves that record retryable for the next run.

Retry and throttling policy

This adapter should define one shared retry/throttling contract rather than letting each migration invent its own.

It should classify, at minimum:

• retryable transport/network failures
• retryable 429 responses
• retryable 5xx responses
• non-retryable 4xx validation failures unless explicitly listed otherwise

When the server provides backoff hints such as Retry-After, the shared runtime should honor them.

Bulk and fallback policy

The shared runtime should know:

• when a native bulk primitive exists and is preferred
• when to fall back from bulk to per-record writes
• when an upsert requires lookup + create/update orchestration
• when an unverified native path must be surfaced before execution rather than used silently

Media policy by target

Do not treat all media the same. The target domain decides whether media must exist in Wix first or can be ingested through the entity API itself.

• Wix Stores products: prefer external URLs on media.itemsInfo.items[] and let the product API ingest them in the background. This is the default path when the URLs are publicly reachable.

  What one item accepts, from the machine-readable Catalog V3 spec (component ProductMedia) — not from the prose article, which disagrees on the cap:

  Field	Direction	Constraint
  setBy.id or setBy.url	in	a oneOf — exactly one per item
  altText	in	1–1000 characters
  displayName	in	max 80, and only accepted when the item is set by url
  mediaType, uploadId	out	read-only
  media.image, media.video	out	read-only; populated when the item is set by id
  thumbnail	out	Wix-generated; needs THUMBNAIL in the request’s fields array
  media.main (on the parent)	out	read-only; always the first entry of itemsInfo.items — reorder the array to change it

  ⚠️ thumbnail is not an input. It looks like a second image URL you could supply and it is not — fields is defined as “Fields to include in the response”, so THUMBNAIL only asks Wix to return a derivative it generated from the one file you uploaded. There is no input that influences it, and none that raises an already-ingested item’s quality: the URL you send is that image’s permanent ceiling. Send the source’s original, maximum- resolution file — the source adapter owns that choice (WordPress sources: wp-image-url.js).

  ⚠️ The cap is disputed by Wix’s own docs. The schema says maxItems: 50 on itemsInfo.items; the About Product Media article says 15. Follow the schema and do not design near either bound.

  ⚠️ The article also says width/height are not populated for URL-set media. Observed behaviour contradicts it — a URL-set item read back live returned both — so reading dimensions back is a usable post-ingest check. Confirm at first live run before reporting it as a guarantee.

  ⚠️ The 200 is a queue acknowledgement, not a delivery — and a failed ingest empties the gallery. This is the most expensive trap on this endpoint, so it gets its own paragraph. The write returns 200 with the item echoed back as mediaType: "UNKNOWN_MEDIA_TYPE" and an uploadId; Wix fetches the URL afterwards, on its own side, with no callback and no status endpoint. media.itemsInfo.items is a full replace, so the product’s existing image is discarded the moment the PATCH is accepted. When the later fetch fails, Wix drops the item and the product is left with no images at all — 200 on the write, no error anywhere, and the old picture already gone.

  It is transient and unattributable: observed live on a valid, publicly reachable 2048×2048 JPEG that ingested fine on the very next identical attempt. Nothing about the file or the request predicts it, so there is nothing to validate up front.

  Observed live	Frequency
  Items not ingested 60 s after an accepted write	a sizable minority
  Of those, fixed by one identical retry	nearly all
  Writes refused by an edge-level 429 whose body is an HTML page, not JSON	occasional

  So: never treat a 200 as done. Read the product back with ?fields=MEDIA_ITEMS_INFO (a plain GET returns only media.main and looks empty even when healthy), and re-send anything whose items lack an image.id. A miss is not yet known, never failed — only re-sending distinguishes “still in flight” from “dropped and gone”. Use patchStoresProductMediaVerified, which does this, rather than patchStoresProductMedia, which returns on the 200. Re-read the revision each round: the accepted-but-not-ingested write already incremented it.

  ⚠️ Two different failures, one retry list. A write refused with 429 leaves the OLD image in place; a write accepted but never ingested leaves NOTHING. Anything that did not reach the verified state goes into the next round, whatever went wrong — recording one of them as an error and dropping it out of the loop is how a run reports success over products it never fixed. Keep the write pool small (3 concurrent, not 6) so the edge limiter is not the thing the retry loop spends its rounds on.

  WordPress-family URL provenance is enforced here. A generated importer uses the exact confirmedPictures instance exported by wix-writers.js for declaration, source reads and confirmation; a separately required toolkit or vendored copy does not activate this writer. After declaring orchestration/decisions.json → sourcePlatform.value, guarded importers call assertProductMediaGuardActive() at startup and stop if this writer’s own guard is inactive. Under exact woocommerce or wordpress declarations, buildStoresProductMedia accepts URL items only when the complete ordered list came from confirmPictures (or an exact normalization registered by deriveConfirmed). Create, bulk create, general patch, media patch and verified media patch all cross this boundary; the verified path checks before its first read. Hand-built strings, objects, clones, subsets, extensions and reorders throw before any Wix request. Wix media ids, other source identities and undeclared legacy callers retain their current behavior.

  ⚠️ A round that failed must back off before the next one, and it is a different wait from the settle wait. The settle wait comes after an accepted write, so a round that throws never reaches it — retry immediately and the loop burns all its rounds in milliseconds against a rate limit that lasts tens of seconds, which is a retry loop that only looks like one. Two waits, two purposes: settleMs waits for an accepted write to finish ingesting, retryDelayMs waits for a refusal to lift. Skip the delay after the final round — there is nothing left to wait for and the caller should not pay for it.

• Wix Blog cover images and other surfaces that require a Wix media id at create/update time: import media first, then pass the Wix media id into the entity payload.

• Generic Media Manager import is a fallback/shared primitive, not the default for every entity carrying media.

Media import source URL reachability

The media primitive imports by URL: Wix servers fetch the provided sourceUrl. Public HTTPS URLs are expected; localhost, 127.0.0.1, Docker-only hosts, and other private-only URLs are not reachable by Wix during a live import. This is optional source preparation and, as far as we know today, affects media import only.

If the source system is local, the migration should either:

• expose the source through a public HTTPS tunnel, then pass/rewire media URLs to that public base URL; or
• skip/defer media import and clearly state which media-dependent references will be missing until media is imported.

Ngrok quick setup for macOS:

brew install ngrok
ngrok config add-authtoken "<YOUR_AUTHTOKEN>"
ngrok http 8090
export WP_BASE_URL=https://<id>.ngrok-free.app

Validate by real call — do not trust doc examples

Codegen-time MCP doc checks confirm an endpoint exists; they do not confirm the request shape works. The live wporg-news import proved doc examples can be wrong (lowercase Ricos plugins → 400) or incomplete (featured image field, tag body). The rule for this adapter:

• Treat a shape as verified only after a real call succeeds — encode the working shape here with a // VERIFIED: (or // VERIFIED-TRAP:) note and a date.

• A // UNVERIFIED: primitive is allowed as a bootstrap point for generated code, but it is not a silent live-write permission. The execution plan must call it out, and setup verification must either promote it with a sandbox/live validation or route to fallback.

• Keep tests/target-wix/contract-test.js current: it issues one real call per primitive against a sandbox site and is the single place schema drift surfaces. Tests live in the repo’s tests/ tree rather than in this bundle, so the published product carries no test harnesses. Run from the repo root:

  bashCopy

  bash tests/run-all.sh target-wix
  WIX_AUTH_TOKEN=... WIX_SITE_ID=... bash tests/run-all.sh target-wix

  Without credentials the shape checks still run and the live calls are skipped. tests/target-wix/ndjson-contract-test.js covers lib/ndjson.js and never needs credentials.

  For live verification runs, pass --progress-log <path> and poll it per CONVENTIONS.md#progress-log-polling.

  Run on a cadence and after any Wix API change. A failing contract test — not a stranger’s broken import — is how we learn the surface moved.

Stores catalog is Catalog V3 only — Catalog V1 is not supported

A migration only ever writes to a V3_CATALOG site. Catalog V1 is not a supported destination: there is no V1 write primitive here, no V1 fallback, and none should be added (a former V1 fallback was removed — it only masked real V3 errors as spurious 428s). A V1 site is a blocker the run halts on, not a variant the adapter, the mapper, or codegen accommodates. The V3 create traps are handled in lib/wix-writers.js (normalizeStoresProductV3 + the top-level treeReference builder), so callers never re-hit them.

On a site this run created, a Stores install is guaranteed Catalog V3. This section used to require verifying that live, because a site scaffolded from the blank headless template, with Stores installed afterwards through the App Installation API, could come up V1_CATALOG — Catalog version is fixed at provisioning, so every V3 write on such a site failed and the site had to be abandoned. The Wix platform has since changed: Catalog V3 is now guaranteed at provisioning regardless of scaffold template, so that failure mode can no longer occur for a newly-created site, and neither the --site-template commerce requirement nor the pre-write version gate apply anymore.

This does not extend to an existing site this run did not create — rp-execute-setup (“A V1_CATALOG verdict is terminal here”) still treats that case as a live risk and halts on it, since a pre-existing site’s catalog version predates this guarantee.

Order history: payment records, refunds and preserved invoice documents

Import Order creates no payment record — a freshly imported order reads back with payments: [] — so payment history is a separate write, and refunds have nothing to reference until it exists. And the order write itself has no idempotency unless it is given an id.

The contract is one call: importOrderHistory in lib/order-history.js. It owns the per-order sequence — derive the order id, read or write the crosswalk, import, gate, one reconciliation read, payment, refunds, invoice document — and returns every stage’s outcome:

const { importOrderHistory, createProjectOrderCrosswalk } = require('./lib/order-history.js');
const result = await importOrderHistory(wix, {
  order,              // mapped Import Order body, no `id`
  sourceId, sourceSiteHost,
  evidence,           // { amount, paidDate, altPaidDate, currency, status, methodName, providerTransactionId,
                      //   offlinePayment, cardDisplay, refunds: [{ sourceId, amount, reason }],
                      //   invoice: { approval, sourceUrl, invoiceNumber, pendingMediaFileId },
                      //   utcOffsetMinutes,                        // a fact about the SHOP
                      //   paidDateZone, altPaidDateZone }          // 'utc' | 'site-local', a fact about
                      //   each source KEY. The offset is applied only to a stamp declared 'site-local'.
                      //   Supplying utcOffsetMinutes beside a present stamp with no clock is REFUSED.
  crosswalk,          // createProjectOrderCrosswalk({ projectDir }) — required, persisted
  setupVerification,  // setup/extended-field-verification.json, read once per run
});
// result.outcomes = { order, payment, refunds: [{ sourceId, sourceOccurrence, outcome, refundId, paymentId }], invoice }
// result.findings, result.errors (partial failures carry a cause), result.orderId, result.paymentId

Its guarantees, each the answer to a failure mode seen in end-to-end testing:

• The order id is derived from sourceSiteHost and sourceId and the crosswalk row is written before any further write. Hit or miss, the target is asked by id once — a read, not a duplicated store, and not a phantom order either. A crosswalk row from before derived ids (a Wix-minted id) wins and is counted as order-id-from-crosswalk. An existing order is never re-sent: Import Order’s replace is silent and would overwrite a merchant’s edits.
• Evidence keys are a contract. An unknown key throws and names the right one; it does not report an ineligible order. The target currency is order.currency.
• One reconciliation read per order, shared by the payment and every refund. Refund occurrences are assigned inside from source ids; pass all of an order’s refunds together.
• Every stage returns an outcome, and a stage that failed after the order existed returns payment-failed / refund-failed / invoice-failed with errors.<stage>.cause, so a resume reconciles the order and retries only what failed. An order-stage failure fails the rest for the cause order-not-imported; a target that cannot be read is order-target-read-failed and writes nothing.
• The buyer’s member id comes through buyer, never on the body, and the body’s buyerInfo.email must be the billing email the member was corroborated against. lib/order-buyer.js resolveOrderBuyer({ sourceCustomerId, billingEmail, memberCrosswalk, contactCrosswalk }) links buyerInfo.memberId only when the member crosswalk row’s loginEmail equals the order’s billing email; a guest, a missing row or a mismatch links nothing and reports (buyer-* outcomes). The result is stamped; the composite sets buyerInfo from it and refuses a body that carries memberId itself. Import Order stores ANY GUID there unvalidated (verified live), so this is the only guard.
• The invoice approval goes to the writer unchanged. The merchant opt-in is applied when the plan is built, nowhere else — and resolvePreservationPlan() stamps what it approves (lib/preservation-approval-stamp.js), so the writer refuses an opt-in that did not come from the plan. A READY Media file whose order patch failed comes back as invoice-fields-write-failed with pendingMediaFileId; the composite remembers it in the crosswalk (getInvoiceFile/setInvoiceFile) and the resume records that file instead of importing another. The crosswalk contract is four methods, all required.
• Every crosswalk hit is verified with one paced order read. A hit is not proof: a row pointing at an order the target no longer has (a cleared migration) is re-imported under the derived id and counted as order-reimported-after-deletion. One read per order per run, hit or miss.

Live: tests/target-wix/order-history-live-sentinel.js (credential-gated) — three runs against a disposable site, one order and one payment afterwards, cleaned up through Bulk Delete Imported Orders. Passed 2026-09-05.

Per-writer reference — what the composite calls, in this order

The writers keep their contracts and remain callable; the composite is a new caller of them. This is what each one guarantees, kept here because the guarantees are the reason the sequence is safe:

1. Gate on the source, first. evaluatePaymentEligibility() in lib/order-payment-mapping.js requires a positive amount AND a source paid date. An order total is not evidence of payment; neither is an order status, and neither is a transaction reference. Ineligible orders are reported under a named reason and never reach the target — which is also what keeps target reads proportional to evidenced payments rather than to the whole order population.
2. Build the record, with buildPaymentRecord(). status sits at payment level, not inside regularPaymentDetails. savedPaymentMethod is never set: the field is writable but no reusable credential can accompany it, so setting it asserts a charging agreement that does not exist. An unknown offline/online class is OMITTED, never guessed — that is how a card payment ends up labelled as cash.
3. Reconcile before creating, with writeOrderPayment(). It reads the order’s existing payments every run and matches by provider reference, else by an exact fingerprint of the payment facts. The migration’s own crosswalk is a hint, not proof of target state: it does not survive “Wix write succeeded, crosswalk write failed”, and it is blind to payments the merchant created by hand. Exactly one match reconciles, more than one is ambiguous and prohibits creation, and a failed target read is its own outcome — never permission to create. Add Payments fails the ENTIRE call if a duplicate external transaction id is present, so writing blind breaks the run and can double recorded revenue.
4. Refund only what the source evidences, with ensureOrderPaymentAndRefund(). Assign occurrence numbers first and pass sourceOccurrence (the composite does this from the refunds’ source ids; a direct caller uses assignRefundOccurrences()): two distinct source refunds can share a payment and an amount, and without it the second one reconciles against the first and is silently dropped. It no longer fabricates a payment to give a refund something to point at; a qualified refund whose order evidences no payment is reported as refund-without-payment. externalRefund is a hardcoded literal true — it defaults to false, which calls the payment provider for real. Omit sideEffects entirely: that is what suppresses restock and the customer email. The refund date cannot be preserved (read-only and immutable), so every written refund discloses that loss, and the true date must not be smuggled into the customer-visible customerReason.
5. Preserve invoice documents by reference, with preserveOrderInvoiceDocument(). Pass the approval straight from resolvePreservationPlan(), and pass sourceSiteHost with it. The writer refuses anything that is not an approval naming that exact URL, and it re-derives the DECISION from its own classification rather than trusting the approval’s action: a document that is not on the source site needs merchantOptedIn however the approval is labelled — and the opt-in is believed only under the planner’s provenance stamp. action is caller-supplied, and trusting it meant a caller could relabel a third-party document preserve and have it imported on nobody’s authority. With no sourceSiteHost the guard answers third-party, so omitting it fails closed. Pass the persisted setup/extended-field-verification.json as setupVerification. When a previous run left an import in flight, pass its pendingMediaFileId back so the import RESUMES instead of creating another private orphan. It reads the order itself — pass an orderId, not an order object — so an existing file id suppresses the import and a re-run cannot import a second copy of a tax document. Pass the setup verification receipt (setup/extended-field-verification.json): without it the write is refused as invoice-fields-not-provisioned. The file is imported private: true; only the returned id is kept, because the Import File response echoes sourceUrl and that URL is a bearer link. Update Order MERGES the extendedFields object it is given — verified live: a foreign key survived a patch that never mentioned it. The write still sends the complete object, which is precautionary rather than load-bearing. Do not describe it as preventing data loss; the API does that itself. The Data Extension SCHEMA PUT is the opposite — there the merge is the only thing preserving a merchant’s fields. Update Order also silently DROPS a value over the field’s maxLength and still answers 200 (verified live 2026-10-27). The writer therefore leaves an over-length invoice number unset, without truncating it, and reports invoice-number-over-length. It reports any key the PATCH response does not carry back as invoice-field-dropped, and treats a dropped file id as invoice-fields-write-failed, with pendingMediaFileId for the resume. These findings arrive in the composite’s findings; count them like every other finding.

Never call the invoicing service. Re-issuing a historical tax document mints a second legal document under a different number, and whether publishing one emails the customer is undocumented in either direction. The contract is non-use, and it is provable: tests/target-wix/no-invoices-api-contract-test.js scans the published tree.

Extended fields must be provisioned and verified before any value is written — see lib/data-extension-schema.js (orders, products, Contacts V5), lib/contact-extended-fields.js (legacy Contacts V4, explicit opt-in only) and the provisioning section in rp-execute-setup. A value write is blocked until setup verified that exact field. Contact values go under extendedFields.namespaces._user_fields with V5 writers, or info.extendedFields.<verifiedKey> with V4 writers — never both.

Coupons, coupon usage and plan definitions

Four small target-side pieces, all pure except the writers named in the table above:

• lib/coupon-redemption-drift.js — a bearer voucher is money, and its redeemability must be decided at write time, not from the discovery snapshot. isBearerVoucher(coupon) narrows to the money-instrument shape (a fixed amount, no scope, no minimum, usage_limit: 1); classifySnapshot({ capturedAt, now, maxAgeMs }) refuses an undated or stale snapshot; classifyPreWriteDrift refuses to write a voucher spent since capture (coupons-spent-after-capture) and refuses to write one it cannot decide; classifyPostImportDrift + buildVoucherDriftPlan produce the cutover remedy plan, with face value and affected orders per code; verifyRemedyApplied insists on a post-settle read-back. One measured fact drives all of it. Update Coupon WRITES when the specification carries ONLY the changed fields plus a field mask — so a spent voucher is deactivated in place, keeping its id, code, dates and amount. Send the FULL specification alongside a narrow mask and it returns 200 with an empty body and writes nothing: the shape everyone reaches for first, and a pass that counts 2xx responses reports a false pass on money. buildRemedyRequest can only emit the minimal form; verifyRemedyApplied refuses to call any 2xx applied without a post-settle read-back. specification.tags is the one usable marker field (every alternative is silently dropped) and the vocabulary is frozen: Imported on everything a migration writes, plus Already_Used or Disabled_At_Source on a disabled one. All recorded as pitfalls on domains/stores/entities/coupon.json.
• lib/order-applied-discount-build.js — buildCouponAppliedDiscounts({ couponLines, resolveCoupon }) turns a source order’s coupon lines into appliedDiscounts[] entries of the coupon variant ({ id, code, name, amount: { amount } }, discountType: GLOBAL) for the Import Order body. There is no standalone write: the entity ecom/order-applied-discount is written through importOrder. A code the coupon crosswalk cannot resolve produces NO entry and an unresolved line — never a dangling coupon id. Import Order stores money as-is, so priceSummary.discount must already agree with the entries.
• lib/pricing-plan-definition.js — evaluatePlanSources({ B1, B2, B3 }) (the row-count gate and the “none found” wording), buildPlanDefinition(offer) (PRIVATE, unbuyable, ACTIVE; name and description truncated WITH a finding; 7-day minimum cycle and 10-year maximum), and assertInertPlan, which the request builder and writer both call.
• Live: tests/target-wix/coupon-plan-live-sentinel.js (credential-gated, cleans up) — one coupon of each mapped type including an expired and an exhausted one, one inert plan, one imported order carrying a coupon usage. Its verdicts are recorded as pitfalls on the entity files.

What stays in codegen (not here)

Per-project field maps and ordering (which source field → which data key, the media/author/taxonomy ref maps, upsert-by-key) live in the generated transforms/write specs. This adapter holds the invariant Wix request shapes, transport, and shared execution mechanics. Collection names and schemas (PodcastEpisodes, …) are project-specific and come from the mapping plan.

Provisioning pointers (see rp-execute-setup)

• Apps (Blog, Members) install via the App Installation API; ground appDefId from the official “Apps Created by Wix” table.
• Wix Data enablement (WDE0110): install the Wix Data app appDefId e593b0bd-b783-45b8-97c2-873d42aacaf4 via the App Installation API; afterward POST /wix-data/v2/collections creates NATIVE collections with no WDE0110 (verified live). Fallback: a custom app with a data-collections extension (declares collections at install time, but can’t express REFERENCE fields).

Scope & coverage

Wix has many apps/entities (Stores, Bookings, Events, Restaurants, Pricing Plans, CRM, …). This adapter does not pre-build all of them. Coverage is demand-driven and grows through reviewed releases. A migration that targets a native Wix entity before a dedicated primitive exists writes it through guarded raw requests: the records are written, the plan shows “raw request, no reviewed writer” before consent, and the retro proposes a reviewed writer from the journaled calls. Generated code never writes it through sendDirectRest.

Native target ladder when no dedicated writer exists:

1. Use the dedicated rp-target-wix primitive when one exists.
2. If Wix has a native entity but no dedicated primitive, use guarded raw requests. Map it natively with write operation sendGuardedRawRequest; the client enforces the URL rules, the journal and the first-record check. A reviewed writer, when one ships, replaces the raw path automatically.
3. Use CMS only when there is no suitable native Wix entity, or when the native entity is explicitly rejected for fidelity/side-effect reasons. CMS is not a fallback for a missing adapter writer.
4. Halt if neither a native path nor an acceptable CMS/custom target exists.

The invariant: anything not backed by a verified primitive is surfaced to the user for consent before execution — never written silently.

Setup runtime expectations

This adapter should also define the shared setup-side runtime used by setup execution.

It should cover reusable mechanics for:

• app installation and verification
• Wix Data enablement verification
• CMS collection and field provisioning when supported
• setup step ordering/checkpointing
• setup audit logging
• setup execution reporting

rp-execute-setup should consume setup artifacts through this runtime rather than re-implementing setup mechanics in skill-local prose or one-off scripts.

Contract-test expectations

Contract tests should validate not only request builders, but also the most important shared runtime invariants.

Examples:

• verified request shapes still serialize correctly
• retry policy classifies common Wix failures correctly
• throttle/backoff handling honors server hints
• compact reports preserve stable top-level fields
• completion reports preserve stable top-level fields
• audit events preserve the agreed machine-readable shape

Default-location reconcileInventory outcomes include catalogVerification: exact Catalog variant availability must agree even when no stock write is needed. Catalog reads are grouped per product with at most four concurrent reads and bounded retries. Non-default locations mark this check not-applicable; Inventory-only success is not a default-location Catalog completion verdict.

Verified contact and product import callers

Use lib/contact-import.js importContacts and lib/product-import.js importProducts for standard imports. Inside an import task, pass importContacts the task’s current evaluation (from evaluateTask) with the task’s own client: it gates its rows and sends each bulk upsert with withBulkReadinessGrant, one source key per contact. A bulk body sent with a single record’s grant is refused. They reconcile source identities before writes, persist candidate IDs in project-local state, and publish crosswalks only after identity/value read-back. The request primitives do not themselves certify a mapping. lib/bulk-results.js selects rules through explicit Contacts V5 / products-with-inventory / Inventory adapters; missing indexes are unresolved, never positional fallbacks. Blog bulk remains outside those adapters.

Product SEO runs inside importProducts for rows carrying seo (a lib/product-seo.js planProductSeo plan). It writes only proven or owner-materialized title/description tags through product.seoData, verifies each field on the product and in Item SEO resolvedTags, and reports report.seo.stageResiduals. Item SEO bulk set is refused for STORES_PRODUCT. Verification is bounded: at most 3 products in flight, every read through the shared sharedTargetReadPacer() (start slots reserved atomically and re-checked after a late timer wake, so actual starts stay >=60 ms apart), an immediate first resolvedTags read, and batch retry rounds whose settle wait stays within 31 s per stage. report.seo.timing reports settleWaitMs, pacingWaitMs and backoffWaitMs separately; the last two are summed per-call waits, never added to wall-clock.

lib/write-verification.js forwards to the shared runtime comparators in skills/wix-replatform/lib/write-verification.js. Contacts normalize only the main email (trim/lowercase) and compare other mapped values exactly after the existing per-source sanitizer. Phone-only identity and distinct source keys sharing a target block and report. Product variant matching uses source-fixed projections and exact target IDs; stock and default-location Catalog verification remain in reconcileInventory.

The existing subscription probe now records valueEvidence. Contract-ledger proposal creation and promotion recheck those inputs; toggling status or supplying only present paths cannot establish verified values. Existing published contracts remain in place. These changes add no automatic probe or global canary gate. Schema fingerprints retained as development evidence must be computed from saved docs-tool output, not authored claims.

Public multilingual target contract

Use scripts/multilingual-inventory.js to exhaust locale, schema, and translation-content pagination; it normalizes Wix’s per-record schemaId/entityId/locale plus typed fields map into deterministic per-field inventory rows. After the normal writer’s verified read-back, scripts/multilingual-object-pairing.js records every source-object to Wix-object binding and scripts/multilingual-member-pairing.js adds nested/repeated member bindings. Both accept only API-supported stable IDs and emit no receipt when there are no additional locales. A top-level field without a verified object receipt is unresolved; the source ID is never assumed to be the Wix ID. scripts/multilingual-execute.js applies the approved field-level sequences through a generated adapter and versioned disposable-site proof file. It refuses unproved mutations, secures typed prior values in ReplatformTranslationRecovery, verifies every value/publication state, and writes per-route cost evidence. scripts/multilingual-decision.js is the sole writer of the scoped local decision ledger, including durable owner restore requests. scripts/multilingual-restore.js restores a verified journal row only while the live replacement digest still matches. The recovery collection is administrator-only, stays on the destination, and is never exported. scripts/multilingual-journal-removal.js opens the post-window action and deletes only after a matching owner authorization; its absence read-back, not the authorization alone, closes the action.