@wix/agent-skills 1.33.1 → 1.34.0

package/skills/wix-replatform/resources/rp-target-wix/domains/tax/entities/tax-settings.json

@@ -0,0 +1,65 @@
+{
+  "schemaVersion": 1,
+  "domain": "tax",
+  "entity": "tax-settings",
+  "displayName": "Wix Tax Settings",
+  "capability": "commerce.tax-settings",
+  "target": {
+    "classification": "setup-config",
+    "nativeEntity": "TaxSettings",
+    "verifiedFqdn": "wix.billing.tax.v1.tax_settings",
+    "idPolicy": "not-applicable",
+    "crosswalkRequired": false
+  },
+  "sourceAliases": [
+    {
+      "sourceSystem": "woocommerce",
+      "sourceEntity": "settings.woocommerce_prices_include_tax",
+      "routes": ["/wc/v3/settings/tax"],
+      "confidence": "high",
+      "note": "A direct boolean 1:1: WooCommerce 'yes'/'no' -> Wix taxIncludedInItemPrices true/false. This is a single site-level flag, not a per-record entity -- there is exactly one TaxSettings resource per site (upsert, not create)."
+    }
+  ],
+  "dependsOn": [],
+  "preferredWrite": {
+    "surface": "Tax Settings",
+    "endpoint": "POST /billing/v1/tax-settings",
+    "writerId": "upsertTaxSettings",
+    "verification": "verified-live",
+    "importSafe": true,
+    "bulk": false
+  },
+  "fallbacks": [],
+  "reliability": { "status": "reliable", "flags": [] },
+  "pitfalls": [
+    {
+      "code": "single-site-level-resource-not-a-crosswalked-record",
+      "severity": "info",
+      "summary": "There is exactly one TaxSettings object per site (Get returns defaults if never set; Upsert creates-or-updates the same singleton). Treat this as ordinary setup/config work, never a per-record write with a crosswalk."
+    },
+    {
+      "code": "display-flag-only-does-not-reprice-the-catalog",
+      "severity": "info",
+      "summary": "`taxIncludedInItemPrices` only changes how checkout DISPLAYS/treats existing catalog prices (tax-inclusive vs. added-on-top); it does not rewrite product prices. Setting it does not require touching already-imported product prices."
+    },
+    {
+      "code": "shared-across-all-wix-products-on-the-site",
+      "severity": "warning",
+      "summary": "Per Wix's own docs, this setting is 'shared across all Wix products on the site' -- if the destination site later gets a second sales channel/app relying on a different price-inclusion convention, changing this affects it too. Not a concern for a single-purpose migration, but don't set it speculatively on a site with pre-existing unrelated commerce config."
+    }
+  ],
+  "mappingGuidance": [
+    "Dependencies: no other modeled record must exist first; Tax Settings is a single site-level configuration resource.",
+    "Read the source's woocommerce_prices_include_tax setting and the destination's Get Tax Settings response; call Upsert Tax Settings only when they differ. Live verification confirmed that a source value of 'no' can already match Wix's false default, requiring no write."
+  ],
+  "setupRequirements": [],
+  "evidence": [
+    { "type": "wix-docs", "url": "https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/extensions/tax/tax-settings/tax-settings-object" },
+    { "type": "wix-docs", "url": "https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/extensions/tax/tax-settings/get-tax-settings" },
+    { "type": "wix-docs", "url": "https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/extensions/tax/tax-settings/upsert-tax-settings" },
+    {
+      "type": "live-verification",
+      "path": "anonymized-live-verification"
+    }
+  ]
+}

package/skills/wix-replatform/resources/rp-target-wix/lib/blog-author-attribution.js

@@ -0,0 +1,165 @@
+'use strict';
+
+// Blog post author attribution: resolve a real Wix member for each distinct source blog author,
+// instead of attributing every imported post to the site owner.
+//
+// THE PITFALL: every imported blog post could carry the SAME memberId -- the site owner's own
+// auto-created user-member -- regardless of which WordPress author actually wrote the post. The
+// source data (data/source-extract/post.ndjson, via `_embedded.author`) names each post's
+// distinct author, and all of them were discarded on import in favor of one hardcoded
+// `WIX_BLOG_AUTHOR_MEMBER_ID`. Root cause: a stale
+// assumption in wix-writers.js's members section ("attribute-to-owner blog imports need no
+// member provisioning") -- a deliberate but wrong simplification, because Wix Blog's `memberId`
+// is required and has no "unauthored" option.
+//
+// The sanctioned fix, verified directly against Wix's own documentation -- the internal skill
+// doc "How to Create Blog Posts" (dev.wix.com/docs/api-reference/business-solutions/blog/skills/
+// how-to-create-blog-posts, "Part 0: Get an Author/Member ID") -- is to CREATE a member when
+// there is no existing member to reuse for an author: its `profile.nickname` (derived from
+// `contact.firstName`) is the name the blog displays as the author, and "If the user named an
+// author, use their name." The same doc, and wix-writers.js's own VERIFIED notes near
+// `createMember`, confirm Create Member sends no email and fires no signup-automation trigger --
+// member creation here is silent, not a notification risk.
+//
+// This creates ONE member per distinct SOURCE AUTHOR, never one per post: callers must resolve
+// through a crosswalk keyed by `sourceAuthorId` (see the `crosswalk` param below) so two posts by
+// the same WordPress author resolve to the same Wix member, and a resumed/re-run import never
+// creates a second member for an author it already provisioned. Recording that crosswalk row
+// after a successful create is the CALLER's responsibility (mirrors `customer-member.js` /
+// `member-crosswalk.js`'s own ensure-then-persist split for the order-buyer member pass) --
+// this module only resolves and creates; see rp-import-codegen/SKILL.md's "Blog post author
+// attribution" section for the generated call site that does both.
+//
+// Not every migration source populates author info on every post (`_embedded.author` is a
+// WordPress `_embed` convenience, not a guarantee across every source platform this toolkit
+// supports) -- resolution falls back to the existing site-owner attribution when a post simply
+// has no source author data, rather than making author resolution a hard requirement that blocks
+// import.
+
+const w = require('./wix-writers.js');
+
+const OUTCOMES = Object.freeze([
+  'blog-author-reconciled-existing', // crosswalk already had a member for this source author
+  'blog-author-created', // no crosswalk row for this source author; a new member was created
+  'blog-author-owner-fallback', // post carries no source author info at all; owner attribution
+]);
+
+// RFC 2606 reserves `.invalid` for addresses guaranteed never to resolve or be deliverable --
+// unlike `example.com`/`example.org`, which some mail systems do attempt to resolve, `.invalid`
+// is the correct TLD for a placeholder address that must never receive mail. The local part
+// carries ONLY the opaque source author id (never the author's real name or any other PII) --
+// the whole point of this fix is that the human's NAME is what is supposed to show up as
+// "posted by X" on the blog, deliberately, via `profile.nickname`/`contact.firstName`; the
+// placeholder address that makes the member creatable carries none of it. The domain is scoped
+// per `siteId` so the SAME source author id across two different projects' migrations can never
+// collide into the same placeholder address -- loginEmail uniqueness is per-site in Wix Members,
+// so this costs nothing and removes any cross-project ambiguity from the scheme.
+//
+// Pattern: `blog-author-{hash(sourceAuthorId)}@{hash(siteId)}.invalid` (see the collision fix
+// below for why each component is a hash of the raw value rather than the raw value itself).
+//
+// COLLISION FIX: an earlier version of this function
+// derived the token via a lossy, human-readable sanitization (lowercase, then collapse every run
+// of non-alphanumeric characters to a single `-`). That is not injective: two different raw
+// values that differ only in WHICH separator character they use collapse to the identical token
+// -- e.g. sourceAuthorId `'1-2'` and `'1@2'` both sanitized to `'1-2'`, so two genuinely distinct
+// WordPress authors would have collided onto the SAME placeholder `loginEmail` and therefore the
+// SAME Wix member, silently misattributing one author's posts to the other. The fix derives the
+// token from a hash of the RAW, un-sanitized value instead: distinct inputs can never collide
+// (short of a SHA-1 collision). This token is never exposed as user-facing content -- it only
+// ever appears inside the `.invalid` placeholder email's local part; the real, human-readable
+// author name goes solely into `profile.nickname`/`contact.firstName` (see
+// `resolveBlogAuthorMemberId` below) -- so there is no readability requirement to trade off here.
+function sanitizeForEmailToken(value) {
+  const raw = value === undefined || value === null ? '' : String(value);
+  return require('node:crypto').createHash('sha1').update(raw).digest('hex').slice(0, 16);
+}
+
+function buildPlaceholderAuthorEmail({ sourceAuthorId, siteId }) {
+  if (sourceAuthorId === undefined || sourceAuthorId === null || sourceAuthorId === '') {
+    throw new Error('buildPlaceholderAuthorEmail requires sourceAuthorId');
+  }
+  const authorToken = sanitizeForEmailToken(sourceAuthorId);
+  const siteToken = sanitizeForEmailToken(siteId || 'site');
+  return `blog-author-${authorToken}@${siteToken}.invalid`;
+}
+
+// CORRECTED: this module previously paced its own Create
+// Member write against a module-private `lastAuthorMemberWriteAt` clock, entirely disjoint from
+// `ensureMember`'s own `lastMemberWriteAt` in wix-writers.js -- the two never saw each other's
+// writes despite sharing the same `MEMBER_WRITE_MIN_INTERVAL_MS` constant. wix-writers.js's own
+// comment documents the >=1s Create Member floor as a constraint on the Wix API endpoint
+// itself, not on whichever function happens to call it, and rp-import-codegen/SKILL.md's
+// generated importers run passes sequentially in ONE process -- so a migration's member
+// pass (`ensureMember`) and blog-author pass (`resolveBlogAuthorMemberId`) could issue two
+// Create Member calls under 1s apart. Fixed by going through wix-writers.js's exported
+// `pacedCreateMember`, which reads and stamps the SAME clock `ensureMember` uses, so every
+// Create Member call in the process -- regardless of which pass issues it -- is correctly
+// spaced against every other one.
+if (typeof w.pacedCreateMember !== 'function') {
+  throw new Error('blog-author-attribution.js requires wix-writers.js to export pacedCreateMember');
+}
+
+// wix: the Wix API client (wix-writers.js's createWixClient()).
+// sourceAuthorId / sourceAuthorName: pulled straight from the source post's author reference
+//   (e.g. WordPress `_embedded.author[0].id`/`.name`) -- null/undefined/'' means the source gave
+//   no author for this post at all.
+// crosswalk: an object exposing async get(sourceAuthorId) -> { memberId, loginEmail } | null,
+//   such as `member-crosswalk.js`'s createProjectMemberCrosswalk({ projectDir, sourceSystem,
+//   sourceEntityType: 'blog-author' }). Required whenever sourceAuthorId is present -- this is
+//   what makes repeat resolution of the same author idempotent across resumed runs.
+// siteId: folded into the placeholder email's domain (see buildPlaceholderAuthorEmail).
+// ownerMemberId: the existing single-owner attribution fallback, used only when the source gives
+//   no author info for this post.
+async function resolveBlogAuthorMemberId(wix, {
+  sourceAuthorId = null,
+  sourceAuthorName = null,
+  crosswalk = null,
+  siteId = null,
+  ownerMemberId = null,
+  safeModeOptions,
+  sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+} = {}) {
+  if (sourceAuthorId === null || sourceAuthorId === undefined || sourceAuthorId === '') {
+    if (!ownerMemberId) {
+      throw new Error('resolveBlogAuthorMemberId: post has no source author and no ownerMemberId fallback was supplied');
+    }
+    return { outcome: 'blog-author-owner-fallback', memberId: String(ownerMemberId), created: false };
+  }
+  if (!crosswalk || typeof crosswalk.get !== 'function') {
+    throw new Error('resolveBlogAuthorMemberId: a post with a source author requires a crosswalk with an async get(sourceAuthorId) lookup');
+  }
+
+  const existing = await crosswalk.get(sourceAuthorId);
+  if (existing && existing.memberId) {
+    return { outcome: 'blog-author-reconciled-existing', memberId: String(existing.memberId), created: false };
+  }
+
+  const displayName = (sourceAuthorName && String(sourceAuthorName).trim()) || `Author ${sourceAuthorId}`;
+  const loginEmail = buildPlaceholderAuthorEmail({ sourceAuthorId, siteId });
+
+  const member = await w.pacedCreateMember(wix, { email: loginEmail, name: displayName }, safeModeOptions, sleep);
+  // createMember only ever skips on an empty email (buildCreateMemberRequest's own guard);
+  // buildPlaceholderAuthorEmail never produces one, so reaching `skipped` means a caller bypassed
+  // it -- surfaced as an error rather than silently falling through to the owner.
+  if (member && member.skipped) {
+    throw new Error(`resolveBlogAuthorMemberId: member creation was skipped unexpectedly: ${member.reason}`);
+  }
+  if (!member || !member.id) {
+    throw new Error('resolveBlogAuthorMemberId: Create Member returned no id');
+  }
+  return {
+    outcome: 'blog-author-created',
+    memberId: String(member.id),
+    created: true,
+    loginEmail,
+    displayName,
+  };
+}
+
+module.exports = {
+  OUTCOMES,
+  sanitizeForEmailToken,
+  buildPlaceholderAuthorEmail,
+  resolveBlogAuthorMemberId,
+};

package/skills/wix-replatform/resources/rp-target-wix/lib/blog-post-build-client.js

@@ -0,0 +1,60 @@
+'use strict';
+
+const WIXAPIS = 'https://www.wixapis.com';
+const writers = require('./wix-writers');
+
+function unwrap(response, field) {
+  const value = response?.[field];
+  if (!value) throw new Error(`Wix Blog response lacks ${field}`);
+  return value;
+}
+function readUrl(surface, id) {
+  const encoded = encodeURIComponent(id);
+  return `${WIXAPIS}/blog/v3/${surface}/${encoded}?fieldsets=RICH_CONTENT&fieldsets=URL`;
+}
+function createBlogBuildClient(wix, { fetchPage, fetchImage } = {}) {
+  if (!wix || typeof wix.send !== 'function') throw new Error('blog build client needs wix.send');
+  return {
+    async createDraft(post) {
+      const response = await wix.send({ method: 'POST', url: `${WIXAPIS}/blog/v3/draft-posts`,
+        body: { draftPost: post, fieldsets: ['RICH_CONTENT', 'URL'] } });
+      return unwrap(response, 'draftPost');
+    },
+    async updateDraft(id, projection) {
+      const response = await wix.send({ method: 'PATCH', url: `${WIXAPIS}/blog/v3/draft-posts/${encodeURIComponent(id)}`,
+        body: { action: 'UPDATE', draftPost: { id, ...projection }, fieldsets: ['RICH_CONTENT', 'URL'] } });
+      return unwrap(response, 'draftPost');
+    },
+    async publishDraft(id) { return writers.publishDraftPost(wix, id); },
+    async getDraft(id) { return unwrap(await wix.send({ method: 'GET', url: readUrl('draft-posts', id) }), 'draftPost'); },
+    async getPost(id) { return unwrap(await wix.send({ method: 'GET', url: readUrl('posts', id) }), 'post'); },
+    async listDrafts({ cursor } = {}) {
+      const params = new URLSearchParams({ 'paging.limit': '100', status: 'UNPUBLISHED' });
+      if (cursor?.startsWith('offset:')) params.set('paging.offset', cursor.slice('offset:'.length));
+      else if (cursor) params.set('paging.cursor', cursor);
+      const response = await wix.send({ method: 'GET', url: `${WIXAPIS}/blog/v3/draft-posts?${params}` });
+      const drafts = response?.draftPosts;
+      if (!Array.isArray(drafts)) throw new Error('Wix Blog list response lacks draftPosts');
+      // Blog List Draft Posts exposes metaData; other Wix list APIs use pagingMetadata.
+      // Accept either documented envelope, but never silently truncate an uncertain page.
+      const metadata = response?.metaData || response?.pagingMetadata;
+      if (!metadata) throw new Error('Wix Blog list response lacks pagination metadata');
+      let nextCursor = metadata.cursors?.next || metadata.nextCursor || null;
+      if (!nextCursor && Number.isFinite(metadata.total) && Number.isFinite(metadata.offset) &&
+        metadata.offset + drafts.length < metadata.total) {
+        if (!drafts.length) throw new Error('Wix Blog list made no offset progress');
+        nextCursor = `offset:${metadata.offset + drafts.length}`;
+      }
+      if (!nextCursor && drafts.length === 100 && !Number.isFinite(metadata.total)) {
+        throw new Error('Wix Blog list ended on a full page without pagination evidence');
+      }
+      return { drafts, nextCursor };
+    },
+    async deletePost(id) { return writers.deletePost(wix, id); },
+    async deleteDraft(id) { return wix.send(writers.buildDeleteDraftPostRequest(id)); },
+    ...(fetchPage ? { fetchPage } : {}),
+    ...(fetchImage ? { fetchImage } : {}),
+  };
+}
+
+module.exports = { createBlogBuildClient };

package/skills/wix-replatform/resources/rp-target-wix/lib/blog-post-build-duplicates.js

@@ -0,0 +1,201 @@
+'use strict';
+
+const ledger = require('./blog-post-build-ledger');
+const reports = require('./blog-post-build-report');
+
+function pairKey(key, extraId) { return `${key}\u0000${extraId}`; }
+function currentPair(projectDir, key, extraId) {
+  return ledger.fold(ledger.readRows(projectDir)).duplicates.get(pairKey(key, extraId));
+}
+function append(projectDir, key, recordedDraftId, extraDraftId, event, rest = {}) {
+  return ledger.appendRow(projectDir, { kind: 'duplicate', sourceStableKey: key,
+    recordedDraftId, extraDraftId, event, ...rest });
+}
+function isNotFound(error) {
+  if (error?.status !== 404) return false;
+  const code = error.code || error.applicationErrorCode || error.details?.code ||
+    error.body?.details?.applicationError?.code;
+  const message = error.body?.message || error.message || '';
+  return ['NOT_FOUND', 'ENTITY_NOT_FOUND'].includes(code) ||
+    (!code && error.outcomeKnown === true && /^entity not found\b/i.test(String(message)));
+}
+async function readOrNull(fn, id) {
+  try { return await fn(id); } catch (error) { if (isNotFound(error)) return null; throw error; }
+}
+async function listAll(client) {
+  const drafts = [];
+  let cursor = null;
+  const cursors = new Set();
+  for (let n = 0; n < 1000; n += 1) {
+    const page = await client.listDrafts({ cursor });
+    if (!Array.isArray(page?.drafts)) throw new Error('draft listing lacks drafts array');
+    drafts.push(...page.drafts);
+    if (!page.nextCursor) return drafts;
+    if (cursors.has(page.nextCursor)) throw new Error('draft listing cursor repeated');
+    cursors.add(page.nextCursor);
+    cursor = page.nextCursor;
+  }
+  throw new Error('draft listing page cap reached');
+}
+function sourceRows(state, key) {
+  return state.posts.get(key)?.rows || [];
+}
+function intentAndCreate(state, key) {
+  const rows = sourceRows(state, key);
+  const create = [...rows].reverse().find(row => row.kind === 'phase' && ['drafted', 'contain-drafted'].includes(row.phase));
+  return {
+    intent: [...rows].reverse().find(row => row.seq < create?.seq && row.kind === 'phase' &&
+      ['creating', 'contain-recreating'].includes(row.phase)),
+    create,
+  };
+}
+function recordedElsewhere(state, id, key, crosswalk) {
+  if (typeof crosswalk?.idOwners !== 'function') return true;
+  for (const [otherKey, post] of state.posts) {
+    if (otherKey !== key && post.rows.some(row => row.draftId === id || row.postId === id)) return true;
+  }
+  return Boolean(crosswalk?.idOwners?.(id)?.some(owner => String(owner) !== key));
+}
+function assessProvenance(state, key, extraId, draft, crosswalk) {
+  const { intent, create } = intentAndCreate(state, key);
+  const sourceFp = intent?.fingerprint;
+  const creation = Date.parse(draft?.createdDate || draft?.createdAt);
+  const edited = Date.parse(draft?.editedDate || draft?.updatedDate);
+  const started = Date.parse(intent?.ts);
+  const finished = Date.parse(create?.ts);
+  const tests = {
+    fingerprint: Boolean(draft && sourceFp && ledger.fingerprint(draft) === sourceFp),
+    storedBody: Boolean(draft && create?.storedBodySha && ledger.bodySha(draft) === create.storedBodySha),
+    creationWindow: Number.isFinite(creation) && Number.isFinite(started) && Number.isFinite(finished) &&
+      creation >= started - 5 * 60_000 && creation <= finished,
+    unedited: Number.isFinite(edited) && Number.isFinite(creation) && Math.abs(edited - creation) <= 1000,
+    unowned: !recordedElsewhere(state, extraId, key, crosswalk),
+  };
+  return { status: Object.values(tests).every(Boolean) ? 'consistent' : 'inconsistent', tests,
+    title: draft?.title || null, createdDate: draft?.createdDate || draft?.createdAt || null };
+}
+async function recordProvenance(projectDir, key, extraId, client, crosswalk, alreadyRead) {
+  const pair = currentPair(projectDir, key, extraId);
+  if (!pair || pair.closed) throw new Error('no open duplicate pair');
+  let draft = alreadyRead;
+  let readError;
+  if (!draft) {
+    try { draft = await client.getDraft(extraId); }
+    catch (error) { readError = error.message; }
+  }
+  const state = ledger.fold(ledger.readRows(projectDir));
+  const evidence = draft ? assessProvenance(state, key, extraId, draft, crosswalk)
+    : { status: 'inconsistent', tests: {}, readError };
+  append(projectDir, key, pair.recordedDraftId, extraId, 'provenance', { evidence });
+  return evidence;
+}
+async function finishPendingEvidence(projectDir, client, crosswalk) {
+  const state = ledger.fold(ledger.readRows(projectDir));
+  for (const pair of state.duplicates.values()) {
+    if (!pair.closed && !pair.evidence) await recordProvenance(projectDir, pair.sourceStableKey, pair.extraDraftId, client, crosswalk);
+  }
+}
+async function detectExtraDrafts(projectDir, client, crosswalk, onlyKey) {
+  const state = ledger.fold(ledger.readRows(projectDir));
+  const targets = [...state.posts.entries()].filter(([key, post]) => (!onlyKey || key === onlyKey) &&
+    post.rows.some(row => ['drafted', 'contain-drafted'].includes(row.phase) && row.recreatedAfterIntent));
+  if (!targets.length) return [];
+  const drafts = await listAll(client);
+  const added = [];
+  for (const [key, post] of targets) {
+    const { intent, create } = intentAndCreate(state, key);
+    if (!intent || !create) continue;
+    const intentBody = [...post.rows].reverse().find(row => row.kind === 'desired-state' &&
+      row.seq < intent.seq);
+    if (!intentBody) throw new Error(`blog duplicate ${key}: create intent has no pinned body`);
+    const expectedTitle = ledger.loadGeneration(projectDir, intentBody.snapshotSha, key).desiredPost.title;
+    for (const draft of drafts) {
+      if (draft.id === create.draftId || draft.title !== expectedTitle) continue;
+      if (currentPair(projectDir, key, draft.id)) continue;
+      // List responses need not include every fingerprint field; use one full read
+      // for matching and provenance rather than missing a late-visible duplicate.
+      let full;
+      try { full = await client.getDraft(draft.id); }
+      catch (error) {
+        append(projectDir, key, create.draftId, draft.id, 'detected');
+        append(projectDir, key, create.draftId, draft.id, 'provenance',
+          { evidence: { status: 'inconsistent', tests: {}, readError: error.message } });
+        added.push({ sourceStableKey: key, extraDraftId: draft.id });
+        continue;
+      }
+      if (ledger.fingerprint(full) !== intent.fingerprint) continue;
+      append(projectDir, key, create.draftId, draft.id, 'detected');
+      added.push({ sourceStableKey: key, extraDraftId: draft.id });
+      await recordProvenance(projectDir, key, draft.id, client, crosswalk, full);
+    }
+  }
+  return added;
+}
+function ensureEvidence(pair, expected = 'consistent') {
+  if (!pair || pair.closed || pair.evidence?.status !== expected) throw new Error(`duplicate needs current ${expected} evidence`);
+}
+function confirmOwnership(projectDir, key, extraId, chosenBy, note) {
+  return ledger.withLock(projectDir, async () => {
+    const pair = currentPair(projectDir, key, extraId);
+    ensureEvidence(pair);
+    if (!String(chosenBy || '').trim() || !String(note || '').trim()) throw new Error('ownership needs named person and their explanation');
+    const row = append(projectDir, key, pair.recordedDraftId, extraId, 'ownership-confirmed', { chosenBy, note });
+    return { row, ...(await reports.refreshBlogHandoff(projectDir)) };
+  });
+}
+function keepOrNotImporter(projectDir, key, extraId, event, chosenBy, note) {
+  return ledger.withLock(projectDir, async () => {
+    const pair = currentPair(projectDir, key, extraId);
+    if (!pair || pair.closed) throw new Error('no open duplicate pair');
+    if (!['kept', 'not-importer'].includes(event)) throw new Error('invalid duplicate closure');
+    if (!String(note || '').trim()) throw new Error('the person’s note is required');
+    if (event === 'kept' && !String(chosenBy || '').trim()) throw new Error('chosenBy required');
+    const row = append(projectDir, key, pair.recordedDraftId, extraId, event, { chosenBy, note });
+    return { row, ...(await reports.refreshBlogHandoff(projectDir)) };
+  });
+}
+async function deleteConfirmedExtra(projectDir, key, extraId, chosenBy, note, client, crosswalk) {
+  return ledger.withLock(projectDir, async () => {
+    let pair = currentPair(projectDir, key, extraId);
+    ensureEvidence(pair);
+    if (!pair.confirmation || !String(chosenBy || '').trim() || !String(note || '').trim()) {
+      throw new Error('current ownership confirmation and a separate named delete choice required');
+    }
+    if (!pair.choice) append(projectDir, key, pair.recordedDraftId, extraId, 'delete-chosen', { chosenBy, note });
+    const draft = await readOrNull(value => client.getDraft(value), extraId);
+    if (!draft) {
+      const post = await readOrNull(value => client.getPost(value), extraId);
+      if (!post) {
+        append(projectDir, key, pair.recordedDraftId, extraId, 'removed');
+        return (await reports.refreshBlogHandoff(projectDir)).report;
+      }
+      append(projectDir, key, pair.recordedDraftId, extraId, 'unresolved',
+        { evidence: { status: 'inconsistent', tests: { unpublished: false } } });
+      return (await reports.refreshBlogHandoff(projectDir)).report;
+    }
+    const evidence = assessProvenance(ledger.fold(ledger.readRows(projectDir)), key, extraId, draft, crosswalk);
+    if (evidence.status !== 'consistent') {
+      append(projectDir, key, pair.recordedDraftId, extraId, 'unresolved', { evidence });
+      return (await reports.refreshBlogHandoff(projectDir)).report;
+    }
+    if (typeof client.deleteDraft !== 'function') throw new Error('client needs deleteDraft for chosen duplicate deletion');
+    await client.deleteDraft(extraId);
+    const draftAfter = await readOrNull(value => client.getDraft(value), extraId);
+    const postAfter = await readOrNull(value => client.getPost(value), extraId);
+    if (draftAfter || postAfter) throw new Error('extra draft deletion not confirmed on both surfaces');
+    pair = currentPair(projectDir, key, extraId);
+    append(projectDir, key, pair.recordedDraftId, extraId, 'removed');
+    return (await reports.refreshBlogHandoff(projectDir)).report;
+  });
+}
+
+function recheckProvenance(projectDir, key, extraId, client, crosswalk) {
+  return ledger.withLock(projectDir, async () => {
+    const evidence = await recordProvenance(projectDir, key, extraId, client, crosswalk);
+    return { evidence, ...(await reports.refreshBlogHandoff(projectDir)) };
+  });
+}
+
+module.exports = { pairKey, currentPair, assessProvenance,
+  finishPendingEvidence, detectExtraDrafts, confirmOwnership, keepOrNotImporter,
+  deleteConfirmedExtra, recheckProvenance };