@wix/agent-skills 1.33.0 → 1.34.0

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

@@ -0,0 +1,306 @@
+'use strict';
+
+// Durable state for the ordered blog importer. The ledger is the authority; reports and
+// in-memory maps are projections and can be discarded after any operation.
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+const LEDGER = 'blog-post-build.ndjson';
+const LOCK = 'blog-post-build.lock';
+const SNAPSHOT_DIR = 'blog-containment';
+const PHASES = new Set([
+  'media-pending', 'creating', 'drafted', 'slug-set', 'links-final', 'held',
+  'snapshot-saved', 'publishing', 'published', 'adopted-published', 'verified',
+  'verify-failed', 'containing', 'contain-deleted', 'contain-recreating',
+  'contain-drafted', 'contain-linked', 'contained', 'contain-failed',
+]);
+const CONTAINMENT = new Set([
+  'containing', 'contain-deleted', 'contain-recreating', 'contain-drafted',
+  'contain-linked', 'contained', 'contain-failed',
+]);
+const DUPLICATE_EVENTS = new Set([
+  'detected', 'provenance', 'ownership-confirmed', 'delete-chosen',
+  'removed', 'kept', 'not-importer', 'unresolved',
+]);
+const SNAPSHOT_KINDS = new Set(['link-set', 'leftover-set', 'dates', 'verify']);
+const DESIRED_EVENTS = new Set(['captured', 'update-intent', 'update-applied']);
+const CLOSED_DUPLICATES = new Set(['removed', 'kept', 'not-importer']);
+const ROW_CACHE = new Map();
+const SNAPSHOT_METRICS = new Map();
+const RUN_IDS = new Map();
+
+function stateDir(projectDir) {
+  if (!projectDir) throw new Error('blog build needs projectDir');
+  return path.join(projectDir, 'state', 'crosswalk');
+}
+function ledgerPath(projectDir) { return path.join(stateDir(projectDir), LEDGER); }
+function sha(value) { return crypto.createHash('sha256').update(typeof value === 'string' ? value : canonical(value)).digest('hex'); }
+function canonical(value) {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
+  if (value && typeof value === 'object') return `{${Object.keys(value).filter(k => value[k] !== undefined).sort().map(k => `${JSON.stringify(k)}:${canonical(value[k])}`).join(',')}}`;
+  return JSON.stringify(value);
+}
+function normalizeRich(value, isNode = false) {
+  if (Array.isArray(value)) return value.map(item => normalizeRich(item, false));
+  if (!value || typeof value !== 'object') return value;
+  return Object.fromEntries(Object.entries(value)
+    .filter(([key]) => !(isNode && key === 'id') &&
+      !['createdDate', 'updatedDate', 'editedDate', 'metadata', 'documentStyle'].includes(key))
+    .map(([key, item]) => [key, key === 'nodes' && Array.isArray(item)
+      ? item.map(node => normalizeRich(node, true)) : normalizeRich(item, false)]));
+}
+function normalizeSeoData(value) {
+  if (!value || typeof value !== 'object') return value;
+  const copy = { ...value };
+  if (Array.isArray(copy.tags) && copy.tags.length === 0) delete copy.tags;
+  return Object.keys(copy).length ? copy : undefined;
+}
+function normalizeMedia(value) {
+  if (!value || typeof value !== 'object') return value;
+  const copy = structuredClone(value);
+  for (const image of [copy.wixMedia?.image, copy.heroImage]) {
+    if (!image || typeof image !== 'object') continue;
+    for (const field of ['url', 'width', 'height', 'filename']) delete image[field];
+  }
+  return copy;
+}
+function bodyProjection(post) {
+  const src = post && (post.draftPost || post.post || post);
+  if (!src || typeof src !== 'object') throw new Error('blog body must be an object');
+  return {
+    title: src.title,
+    richContent: normalizeRich(src.richContent),
+    media: normalizeMedia(src.media),
+    heroImage: normalizeMedia({ heroImage: src.heroImage }).heroImage,
+    memberId: src.memberId,
+    firstPublishedDate: src.firstPublishedDate,
+    excerpt: src.excerpt,
+    categoryIds: [...(src.categoryIds || [])].sort(),
+    tagIds: [...(src.tagIds || [])].sort(),
+    seoData: normalizeSeoData(src.seoData),
+  };
+}
+function bodySha(post) { return sha(bodyProjection(post)); }
+function fingerprint(post) {
+  const src = post && (post.draftPost || post.post || post);
+  return sha({ title: src.title, firstPublishedDate: src.firstPublishedDate,
+    memberId: src.memberId, excerpt: src.excerpt,
+    coverId: src.media?.wixMedia?.image?.id || src.heroImage?.id || '' });
+}
+function validateDesiredPost(post) {
+  const missing = [];
+  for (const field of ['title', 'memberId', 'richContent']) {
+    if (post?.[field] === undefined || post?.[field] === null || post[field] === '') missing.push(field);
+  }
+  if (!post?.richContent || !Array.isArray(post.richContent.nodes)) missing.push('richContent.nodes');
+  if (missing.length) throw new Error(`desired-post-invalid: missing ${missing.join(', ')}`);
+  return post;
+}
+function fromDraftResponse(response) {
+  const draft = response?.draftPost || response;
+  if (!draft || typeof draft !== 'object') throw new Error('draft response is missing');
+  const fields = ['title', 'richContent', 'media', 'memberId', 'firstPublishedDate',
+    'excerpt', 'categoryIds', 'tagIds', 'seoData', 'heroImage'];
+  const post = Object.fromEntries(fields.filter(key => Object.hasOwn(draft, key)).map(key => [key, draft[key]]));
+  if (draft.slug) post.seoSlug = draft.slug;
+  return validateDesiredPost(post);
+}
+function readRows(projectDir) {
+  const file = ledgerPath(projectDir);
+  if (!fs.existsSync(file)) return [];
+  const stat = fs.statSync(file, { bigint: true });
+  const cached = ROW_CACHE.get(file);
+  if (cached && cached.size === stat.size && cached.mtimeNs === stat.mtimeNs) return cached.rows;
+  const content = fs.readFileSync(file, 'utf8');
+  const lines = content.split('\n');
+  const rows = [];
+  const complete = content.endsWith('\n') ? lines.length - 1 : lines.length;
+  for (let i = 0; i < complete; i += 1) {
+    if (!lines[i]) throw new Error(`blog ledger line ${i + 1}: empty line`);
+    let row;
+    try { row = JSON.parse(lines[i]); }
+    catch (error) {
+      if (i === complete - 1 && !content.endsWith('\n')) break;
+      throw new Error(`blog ledger line ${i + 1}: invalid JSON: ${error.message}`);
+    }
+    if (row.seq !== rows.length + 1) throw new Error(`blog ledger line ${i + 1}: expected seq ${rows.length + 1}, got ${row.seq}`);
+    validateRow(row);
+    rows.push(row);
+  }
+  ROW_CACHE.set(file, { size: stat.size, mtimeNs: stat.mtimeNs, rows });
+  return rows;
+}
+function validateRow(row) {
+  if (!row.sourceStableKey && row.kind !== 'spot-check') throw new Error(`blog ledger seq ${row.seq}: sourceStableKey missing`);
+  if (row.kind === 'phase') {
+    if (!PHASES.has(row.phase)) throw new Error(`blog ledger seq ${row.seq}: unknown phase`);
+    if (['held', 'contain-failed'].includes(row.phase) && !row.reason) throw new Error(`blog ledger seq ${row.seq}: reason missing`);
+    if (row.phase === 'verified' && !['read', 'reverify', 'accepted'].includes(row.via)) throw new Error(`blog ledger seq ${row.seq}: verified via missing`);
+  } else if (row.kind === 'desired-state') {
+    if (!DESIRED_EVENTS.has(row.event) || !row.snapshotSha || !row.generation) throw new Error(`blog ledger seq ${row.seq}: invalid desired state`);
+  } else if (row.kind === 'duplicate') {
+    if (!DUPLICATE_EVENTS.has(row.event) || !row.extraDraftId || !row.recordedDraftId) throw new Error(`blog ledger seq ${row.seq}: invalid duplicate`);
+  } else if (SNAPSHOT_KINDS.has(row.kind)) {
+    if (!Array.isArray(row.findings) || row.findings.some(f => !f.findingKey)) throw new Error(`blog ledger seq ${row.seq}: invalid findings`);
+  } else if (row.kind === 'accepted') {
+    if (!row.snapshotKind || !row.findingKey || !row.snapshotSeq || !row.acceptedBy) throw new Error(`blog ledger seq ${row.seq}: invalid acceptance`);
+  } else if (row.kind === 'spot-check') {
+    if (!row.coverageVersion || !Array.isArray(row.posts) || !row.checkedBy || !row.recordedBy) throw new Error(`blog ledger seq ${row.seq}: invalid spot-check`);
+  } else throw new Error(`blog ledger seq ${row.seq}: unknown kind ${row.kind}`);
+}
+function appendRow(projectDir, row) {
+  const dir = stateDir(projectDir);
+  fs.mkdirSync(dir, { recursive: true });
+  const rows = readRows(projectDir);
+  const content = fs.existsSync(ledgerPath(projectDir)) ? fs.readFileSync(ledgerPath(projectDir), 'utf8') : '';
+  if (content && !content.endsWith('\n')) {
+    const tail = content.slice(content.lastIndexOf('\n') + 1);
+    let valid = false;
+    try { JSON.parse(tail); valid = true; } catch { /* torn tail already ignored by readRows */ }
+    if (valid) fs.appendFileSync(ledgerPath(projectDir), '\n');
+    else fs.truncateSync(ledgerPath(projectDir), Buffer.byteLength(content.slice(0, content.lastIndexOf('\n') + 1)));
+  }
+  const runId = row.runId || RUN_IDS.get(projectDir);
+  const next = { ...row, ...(runId ? { runId } : {}), seq: rows.length + 1,
+    ts: row.ts || new Date().toISOString() };
+  validateRow(next);
+  const fd = fs.openSync(ledgerPath(projectDir), 'a');
+  try { fs.writeSync(fd, `${JSON.stringify(next)}\n`); fs.fsyncSync(fd); }
+  finally { fs.closeSync(fd); }
+  const stat = fs.statSync(ledgerPath(projectDir), { bigint: true });
+  ROW_CACHE.set(ledgerPath(projectDir), { size: stat.size, mtimeNs: stat.mtimeNs,
+    rows: [...rows, next] });
+  return next;
+}
+function withLock(projectDir, run) {
+  const dir = stateDir(projectDir);
+  fs.mkdirSync(dir, { recursive: true });
+  const lock = path.join(dir, LOCK);
+  let fd;
+  try { fd = fs.openSync(lock, 'wx'); }
+  catch (error) {
+    if (error.code === 'EEXIST') throw new Error(`blog build lock exists at ${lock}; Import Operator must inspect it`);
+    throw error;
+  }
+  fs.writeSync(fd, `${process.pid}\n`); fs.fsyncSync(fd);
+  const release = () => { fs.closeSync(fd); fs.unlinkSync(lock); };
+  try {
+    const result = run();
+    if (result && typeof result.then === 'function') return result.finally(release);
+    release();
+    return result;
+  } catch (error) { release(); throw error; }
+}
+function setRunId(projectDir, runId) {
+  if (runId) RUN_IDS.set(projectDir, runId);
+  else RUN_IDS.delete(projectDir);
+}
+function saveGeneration(projectDir, sourceStableKey, desiredPost, origin, extra = {}) {
+  const started = process.hrtime.bigint();
+  validateDesiredPost(desiredPost);
+  if (!['run', 'held-draft', 'source'].includes(origin)) throw new Error('invalid blog snapshot origin');
+  const payload = { schema: 3, sourceStableKey, draftId: extra.draftId || null,
+    fingerprint: fingerprint(desiredPost), desiredPost, ownerState: extra.ownerState || null,
+    finalSlug: extra.finalSlug || null, snapshotOrigin: origin,
+    savedAt: new Date().toISOString() };
+  const bytes = canonical(payload);
+  const digest = sha(bytes);
+  const dir = path.join(stateDir(projectDir), SNAPSHOT_DIR);
+  fs.mkdirSync(dir, { recursive: true });
+  const safeKey = encodeURIComponent(sourceStableKey).replace(/%/g, '_');
+  const file = path.join(dir, `${safeKey}.${digest}.snapshot.json`);
+  if (!fs.existsSync(file)) {
+    const temp = path.join(dir, `.${digest}.${process.pid}.tmp`);
+    const fd = fs.openSync(temp, 'wx');
+    try { fs.writeSync(fd, bytes); fs.fsyncSync(fd); }
+    finally { fs.closeSync(fd); }
+    fs.renameSync(temp, file);
+    const dirFd = fs.openSync(dir, 'r');
+    try { fs.fsyncSync(dirFd); } finally { fs.closeSync(dirFd); }
+  }
+  const elapsedMs = Number(process.hrtime.bigint() - started) / 1e6;
+  const metricsKey = `${projectDir}\u0000${sourceStableKey}`;
+  const previous = SNAPSHOT_METRICS.get(metricsKey) || { bytes: 0, ms: 0, generations: 0 };
+  SNAPSHOT_METRICS.set(metricsKey, { bytes: previous.bytes + Buffer.byteLength(bytes),
+    ms: previous.ms + elapsedMs, generations: previous.generations + 1 });
+  return { generation: digest, snapshotSha: digest, sourceStableKey };
+}
+function snapshotMetrics(projectDir, sourceStableKey) {
+  return SNAPSHOT_METRICS.get(`${projectDir}\u0000${sourceStableKey}`) ||
+    { bytes: 0, ms: 0, generations: 0 };
+}
+function resetSnapshotMetrics(projectDir) {
+  for (const key of SNAPSHOT_METRICS.keys()) if (key.startsWith(`${projectDir}\u0000`)) SNAPSHOT_METRICS.delete(key);
+}
+function loadGeneration(projectDir, digest, sourceStableKey) {
+  const dir = path.join(stateDir(projectDir), SNAPSHOT_DIR);
+  const suffix = `.${digest}.snapshot.json`;
+  const names = fs.readdirSync(dir).filter(name => name.endsWith(suffix));
+  if (names.length !== 1) throw new Error(`blog snapshot ${digest}: expected one referenced generation, found ${names.length}`);
+  const file = path.join(dir, names[0]);
+  const data = fs.readFileSync(file, 'utf8');
+  if (sha(data) !== digest) throw new Error(`blog snapshot hash mismatch: ${digest}`);
+  const result = JSON.parse(data);
+  if (sourceStableKey && result.sourceStableKey !== sourceStableKey) throw new Error(`blog snapshot source mismatch: ${digest}`);
+  return result;
+}
+function savePublishedEvidence(projectDir, sourceStableKey, published) {
+  const dir = path.join(stateDir(projectDir), SNAPSHOT_DIR);
+  fs.mkdirSync(dir, { recursive: true });
+  const safeKey = encodeURIComponent(sourceStableKey).replace(/%/g, '_');
+  const file = path.join(dir, `${safeKey}.published.json`);
+  const temp = `${file}.${process.pid}.tmp`;
+  const fd = fs.openSync(temp, 'w');
+  try { fs.writeSync(fd, `${JSON.stringify(published, null, 2)}\n`); fs.fsyncSync(fd); }
+  finally { fs.closeSync(fd); }
+  fs.renameSync(temp, file);
+  const dirFd = fs.openSync(dir, 'r');
+  try { fs.fsyncSync(dirFd); } finally { fs.closeSync(dirFd); }
+  return path.relative(projectDir, file);
+}
+function fold(rows) {
+  const posts = new Map();
+  const duplicates = new Map();
+  let spotCheck = null;
+  for (const row of rows) {
+    if (row.kind === 'spot-check') { spotCheck = row; continue; }
+    const key = row.sourceStableKey;
+    if (!posts.has(key)) posts.set(key, { sourceStableKey: key, phase: null, containmentOpen: false,
+      desired: null, pendingIntent: null, snapshots: {}, accepted: new Map(), rows: [] });
+    const post = posts.get(key);
+    post.rows.push(row);
+    if (row.kind === 'phase') {
+      post.phase = row;
+      if (row.phase === 'containing') post.containmentOpen = true;
+      else if (row.phase === 'contained') post.containmentOpen = false;
+    } else if (row.kind === 'desired-state') {
+      if (row.event === 'captured' || row.event === 'update-applied') { post.desired = row; post.pendingIntent = null; }
+      else post.pendingIntent = row;
+    } else if (row.kind === 'duplicate') {
+      const pair = `${key}\u0000${row.extraDraftId}`;
+      if (!duplicates.has(pair)) duplicates.set(pair, { sourceStableKey: key, extraDraftId: row.extraDraftId,
+        recordedDraftId: row.recordedDraftId, evidence: null, confirmation: null, choice: null });
+      const item = duplicates.get(pair);
+      item.last = row;
+      if (['provenance', 'unresolved'].includes(row.event)) { item.evidence = row.evidence; item.confirmation = null; item.choice = null; }
+      if (row.event === 'ownership-confirmed') item.confirmation = row;
+      if (row.event === 'delete-chosen') item.choice = row;
+      item.closed = CLOSED_DUPLICATES.has(row.event);
+    } else if (SNAPSHOT_KINDS.has(row.kind)) post.snapshots[row.kind] = row;
+    else if (row.kind === 'accepted') post.accepted.set(`${row.snapshotKind}\u0000${row.findingKey}`, row);
+  }
+  for (const post of posts.values()) {
+    post.openFindings = Object.fromEntries(Object.entries(post.snapshots).map(([kind, snap]) =>
+      [kind, snap.findings.filter(f => !post.accepted.has(`${kind}\u0000${f.findingKey}`))]));
+  }
+  return { posts, duplicates, spotCheck };
+}
+
+module.exports = {
+  LEDGER, PHASES, CONTAINMENT, SNAPSHOT_KINDS, stateDir, ledgerPath, sha, canonical,
+  bodyProjection, bodySha, fingerprint, validateDesiredPost, fromDraftResponse,
+  readRows, appendRow, withLock, saveGeneration, loadGeneration, savePublishedEvidence, fold,
+  snapshotMetrics, resetSnapshotMetrics,
+  setRunId,
+};

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

@@ -0,0 +1,229 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const ledger = require('./blog-post-build-ledger');
+
+const REPORT = 'blog-import-report.json';
+const SPOT_CHECK_ACTION = Object.freeze({
+  code: 'blog-verification-spot-check', severity: 'medium', entity: 'blog-posts',
+  action: 'Cutover Operator: open these posts in preview and check them; Import Operator records the result (prompt 10)',
+  deadlineReason: 'before go-live: the run did not fetch these pages',
+});
+
+function atomicJson(file, data) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.tmp`;
+  const fd = fs.openSync(tmp, 'w');
+  try { fs.writeSync(fd, `${JSON.stringify(data, null, 2)}\n`); fs.fsyncSync(fd); }
+  finally { fs.closeSync(fd); }
+  fs.renameSync(tmp, file);
+}
+function address(post) { return post.phase?.publishedPath || post.phase?.expectedPath || null; }
+function pendingMediaDetails(projectDir) {
+  const file = path.join(ledger.stateDir(projectDir), 'pending-blog-media.ndjson');
+  if (!fs.existsSync(file)) return new Map();
+  const text = fs.readFileSync(file, 'utf8');
+  const lines = text.split('\n');
+  const details = new Map();
+  for (let i = 0; i < lines.length; i += 1) {
+    if (!lines[i]) continue;
+    let row;
+    try { row = JSON.parse(lines[i]); }
+    catch (error) {
+      if (i === lines.length - 1 && !text.endsWith('\n')) break;
+      throw new Error(`pending-blog-media line ${i + 1}: ${error.message}`);
+    }
+    if (!row.sourceStableKey) continue;
+    if (!details.has(row.sourceStableKey)) details.set(row.sourceStableKey, new Map());
+    const media = details.get(row.sourceStableKey);
+    if (row.outcome === 'resolved') { media.clear(); continue; }
+    if (row.mediaKey) media.set(row.mediaKey, row);
+  }
+  return new Map([...details].map(([key, rows]) => [key, [...rows.values()]
+    .filter(row => row.outcome !== 'ready').map(row => ({ mediaKey: row.mediaKey, kind: row.kind,
+      outcome: row.outcome, reason: row.reason || null, fileId: row.fileId || null }))]));
+}
+function blogSpotCheckOperatorAction(coverage) {
+  if (!coverage || ['not-required', 'recorded'].includes(coverage.spotCheck.status)) return null;
+  return { ...SPOT_CHECK_ACTION, affectedCount: coverage.requiredCount };
+}
+function verificationCoverage(state) {
+  const verified = [...state.posts.values()].filter(post => post.phase?.phase === 'verified' && address(post));
+  const sampled = verified.filter(post => post.snapshots.verify?.sampled === true);
+  const unsampled = verified.filter(post => post.snapshots.verify?.sampled !== true);
+  const pairs = unsampled.map(post => [post.sourceStableKey, address(post)]).sort((a, b) => a[0].localeCompare(b[0]));
+  const coverageVersion = ledger.sha(pairs);
+  const sampledAddresses = sampled.map(address).sort();
+  const unsampledAddresses = unsampled.map(address).sort();
+  const requiredCount = Math.min(3, unsampled.length);
+  const last = state.spotCheck;
+  let status = 'required';
+  if (!unsampled.length) status = 'not-required';
+  else if (last && last.coverageVersion !== coverageVersion) status = 'stale';
+  else if (last?.posts?.some(post => post.result === 'fail')) status = 'failed';
+  else if (last && last.posts.length >= requiredCount) status = 'recorded';
+  return { schema: 1, coverageVersion, sampled: sampled.length, total: verified.length,
+    sampledAddresses, unsampledAddresses, requiredCount,
+    spotCheck: { status, seq: last?.seq || null, checkedBy: last?.checkedBy || null,
+      checkedAt: last?.checkedAt || null, recordedBy: last?.recordedBy || null,
+      posts: last?.posts || [] } };
+}
+function action({ code, severity, entity, affectedCount, role, prompt, impact, closure, records }) {
+  return { code, severity, entity, affectedCount, role, prompt, impact, closure, records,
+    action: `${role}: use blog report prompt ${prompt}; closure: ${closure}`,
+    deadlineReason: severity === 'critical' ? `immediately: ${impact}` : `before go-live: ${impact}` };
+}
+function rebuildBlogReport(projectDir) {
+  const state = ledger.fold(ledger.readRows(projectDir));
+  const mediaDetails = pendingMediaDetails(projectDir);
+  const held = [], pending = [], verificationFailures = [], containmentUrgent = [], containmentRebuild = [], adoptionAmbiguous = [];
+  const addresses = [];
+  let publishedPostReads = 0;
+  let livePagesFetched = 0;
+  for (const post of state.posts.values()) {
+    const phase = post.phase;
+    if (!phase) continue;
+    const lastContainment = [...post.rows].reverse().find(row => row.phase === 'contained');
+    const base = { sourceStableKey: post.sourceStableKey, draftId: phase.draftId,
+      postId: phase.postId, reason: phase.reason, expectedPath: phase.expectedPath,
+      publishedPath: phase.publishedPath, phase: phase.phase,
+      ...(lastContainment ? { exposedFrom: lastContainment.exposedFrom,
+        containedAt: lastContainment.containedAt } : {}) };
+    if (address(post)) addresses.push({ sourceStableKey: post.sourceStableKey, address: address(post), phase: phase.phase });
+    if (phase.phase === 'media-pending') pending.push({ ...base, media: mediaDetails.get(post.sourceStableKey) || [] });
+    if (phase.phase === 'held' && ['adoption-ambiguous', 'legacy-mismatch', 'create-projection-mismatch'].includes(phase.reason)) {
+      adoptionAmbiguous.push({ ...base, candidates: phase.candidates || [] });
+    } else if (['held', 'contained'].includes(phase.phase)) held.push({ ...base,
+      openFindings: post.openFindings['leftover-set'] || [] });
+    if (phase.phase === 'verify-failed') verificationFailures.push({ ...base,
+      openFindings: post.openFindings.verify || [] });
+    if (post.containmentOpen && phase.phase === 'contain-failed') {
+      (phase.reason === 'delete-failed' ? containmentUrgent : containmentRebuild).push(base);
+    }
+    publishedPostReads += post.snapshots.verify ? 1 : 0;
+    livePagesFetched += post.snapshots.verify?.sampled ? 1 : 0;
+  }
+  const extras = [...state.duplicates.values()].filter(pair => !pair.closed).map(pair => ({
+    sourceStableKey: pair.sourceStableKey, recordedDraftId: pair.recordedDraftId,
+    extraDraftId: pair.extraDraftId, evidence: pair.evidence,
+    status: !pair.evidence ? 'evidence-pending'
+      : pair.evidence.status === 'consistent' && pair.confirmation ? 'ownership-confirmed'
+        : 'owner-confirmation-needed',
+    ownershipConfirmedBy: pair.confirmation?.chosenBy || null,
+  }));
+  const coverage = verificationCoverage(state);
+  const operatorActions = [];
+  if (held.length) operatorActions.push(action({ code: 'blog-held-posts', severity: 'high', entity: 'blog-posts',
+    affectedCount: held.length, role: 'Import Operator', prompt: 2, impact: 'Posts remain unpublished',
+    closure: 'empty leftover-set, then published and verified', records: held }));
+  if (adoptionAmbiguous.length) operatorActions.push({ code: 'blog-adoption-ambiguous',
+    severity: 'high', entity: 'blog-posts', affectedCount: adoptionAmbiguous.length,
+    role: 'Import Operator', prompt: null,
+    impact: 'A candidate draft could belong to another post or person; no write was made',
+    action: 'Requires Import Operator: stop the blog step and inspect the listed draft ids, source post, and ledger identity evidence. Resolve the identity conflict with a reviewed recovery plan before any adoption, create, or deletion.',
+    deadlineReason: 'before go-live: the post remains unpublished or unverified',
+    closure: 'documented identity resolution and a later verified ledger row', records: adoptionAmbiguous });
+  if (pending.length) operatorActions.push(action({ code: 'blog-pending-media', severity: 'high', entity: 'blog-posts',
+    affectedCount: pending.length, role: 'Import Operator', prompt: 3,
+    impact: 'Media is unresolved; new posts are held and existing crosswalk posts may already be live',
+    closure: 'media ready, then published and verified', records: pending }));
+  if (verificationFailures.length) operatorActions.push(action({ code: 'blog-verification-failed', severity: 'high', entity: 'blog-posts',
+    affectedCount: verificationFailures.length, role: 'Import Operator', prompt: 4,
+    impact: 'Published posts have failed checks', closure: 'reverified or accepted', records: verificationFailures }));
+  if (containmentUrgent.length) operatorActions.push(action({ code: 'blog-may-still-be-live', severity: 'critical', entity: 'blog-posts',
+    affectedCount: containmentUrgent.length, role: 'Cutover Operator; Requires Import Operator', prompt: 5,
+    impact: 'A post that failed a blocking check may still be live', closure: 'not-found read, then contained', records: containmentUrgent }));
+  if (containmentRebuild.length) operatorActions.push(action({ code: 'blog-rebuild-draft', severity: 'high', entity: 'blog-posts',
+    affectedCount: containmentRebuild.length, role: 'Import Operator', prompt: 6,
+    impact: 'Posts are off site and lack a draft', closure: 'contained with draft id, then verified', records: containmentRebuild }));
+  for (const status of ['evidence-pending', 'owner-confirmation-needed', 'ownership-confirmed']) {
+    const records = extras.filter(extra => extra.status === status);
+    if (records.length) operatorActions.push(action({ code: `blog-extra-draft-${status}`, severity: 'high', entity: 'blog-posts',
+      affectedCount: records.length, role: status === 'ownership-confirmed' ? 'Cutover Operator; Requires Import Operator' : 'Import Operator',
+      prompt: status === 'evidence-pending' ? 9 : status === 'ownership-confirmed' ? 7 : 8,
+      impact: 'An extra unpublished draft may belong to someone else',
+      closure: 'provenance, kept, not-importer, or confirmed choice with re-test', records }));
+  }
+  const spot = blogSpotCheckOperatorAction(coverage);
+  if (spot) operatorActions.push({ ...spot, role: 'Cutover Operator; Requires Import Operator', prompt: 10,
+    records: coverage.unsampledAddresses });
+  const report = { schema: 1, ledger: path.relative(projectDir, ledger.ledgerPath(projectDir)),
+    totals: { posts: state.posts.size, publishedPostReads, livePagesFetched },
+    addresses: addresses.sort((a, b) => a.sourceStableKey.localeCompare(b.sourceStableKey)),
+    held, adoptionAmbiguous, pending, verificationFailures, containmentUrgent, containmentRebuild, extraDrafts: extras,
+    verificationCoverage: coverage, operatorActions };
+  atomicJson(path.join(ledger.stateDir(projectDir), REPORT), report);
+  return report;
+}
+
+async function refreshBlogHandoff(projectDir) {
+  const report = rebuildBlogReport(projectDir);
+  const completion = require('../../../lib/completion-report');
+  const file = path.join(projectDir, completion.COMPLETION_REPORT_FILE);
+  if (!fs.existsSync(file)) return { report, status: 'completion-report-missing' };
+  const existing = JSON.parse(fs.readFileSync(file, 'utf8'));
+  const actions = (existing.operatorActions || []).filter(row => row.code !== SPOT_CHECK_ACTION.code);
+  const spot = blogSpotCheckOperatorAction(report.verificationCoverage);
+  if (spot) actions.push(spot);
+  const normalized = actions.map(completion.normalizeOperatorAction);
+  const updated = { ...existing, operatorActions: normalized };
+  atomicJson(file, updated);
+  const summaryFile = path.join(projectDir, completion.COMPLETION_SUMMARY_FILE);
+  fs.mkdirSync(path.dirname(summaryFile), { recursive: true });
+  fs.writeFileSync(summaryFile, completion.renderCompletionSummary(updated));
+  const { generatePostExecutionHandoff } = require('../../../lib/website-handoff');
+  const handoff = await generatePostExecutionHandoff(projectDir, { appendLog: false });
+  return { report, status: 'refreshed', handoff };
+}
+
+function recordBlogSpotCheck(projectDir, coverageVersion, posts, checkedBy, checkedAt, recordedBy, note) {
+  return ledger.withLock(projectDir, async () => {
+    const report = (await refreshBlogHandoff(projectDir)).report;
+    const coverage = report.verificationCoverage;
+    if (coverageVersion !== coverage.coverageVersion) throw new Error('spot-check coverageVersion is stale');
+    if (!String(checkedBy || '').trim() || !String(recordedBy || '').trim()) throw new Error('checkedBy and recordedBy are required');
+    if (!checkedAt || Number.isNaN(Date.parse(checkedAt))) throw new Error('checkedAt must be a date');
+    if (!Array.isArray(posts) || posts.length < coverage.requiredCount) throw new Error(`at least ${coverage.requiredCount} unsampled posts required`);
+    const allowed = new Set(coverage.unsampledAddresses);
+    const seen = new Set();
+    for (const post of posts) {
+      if (!allowed.has(post.address) || seen.has(post.address)) throw new Error(`sampled, unverified, or duplicate address: ${post.address}`);
+      if (!['pass', 'fail'].includes(post.result)) throw new Error('spot-check result must be pass or fail');
+      if (!String(post.note || '').trim()) throw new Error('spot-check observation note is required');
+      seen.add(post.address);
+    }
+    const byAddress = new Map(report.addresses.map(row => [row.address, row.sourceStableKey]));
+    const row = ledger.appendRow(projectDir, { kind: 'spot-check', coverageVersion,
+      posts: posts.map(post => ({ sourceStableKey: byAddress.get(post.address), ...post })),
+      checkedBy: checkedBy.trim(), checkedAt, recordedBy: recordedBy.trim(), note });
+    return { row, ...(await refreshBlogHandoff(projectDir)) };
+  });
+}
+
+function acceptBlogFinding(projectDir, sourceStableKey, snapshotKind, findingKey, note, acceptedBy) {
+  return ledger.withLock(projectDir, async () => {
+    if (!String(acceptedBy || '').trim() || !String(note || '').trim()) throw new Error('acceptance needs a person and note');
+    const state = ledger.fold(ledger.readRows(projectDir));
+    const post = state.posts.get(sourceStableKey);
+    const snapshot = post?.snapshots[snapshotKind];
+    const finding = snapshot?.findings.find(item => item.findingKey === findingKey);
+    if (!finding || !post.openFindings[snapshotKind].some(item => item.findingKey === findingKey)) {
+      throw new Error('findingKey is not open in the current snapshot');
+    }
+    if (finding.blocking) throw new Error('a blocking finding cannot be accepted');
+    const row = ledger.appendRow(projectDir, { kind: 'accepted', sourceStableKey,
+      snapshotKind, findingKey, snapshotSeq: snapshot.seq, note, acceptedBy: acceptedBy.trim() });
+    const after = ledger.fold(ledger.readRows(projectDir)).posts.get(sourceStableKey);
+    if (after.phase?.phase === 'verify-failed' && Object.values(after.openFindings).every(items => !items.length)) {
+      ledger.appendRow(projectDir, { kind: 'phase', sourceStableKey, phase: 'verified',
+        draftId: after.phase.draftId, postId: after.phase.postId,
+        publishedPath: after.phase.publishedPath, via: 'accepted' });
+    }
+    return { row, ...(await refreshBlogHandoff(projectDir)) };
+  });
+}
+
+module.exports = { REPORT, SPOT_CHECK_ACTION, verificationCoverage,
+  blogSpotCheckOperatorAction, rebuildBlogReport, refreshBlogHandoff,
+  recordBlogSpotCheck, acceptBlogFinding };

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

@@ -0,0 +1,55 @@
+'use strict';
+
+const ledger = require('./blog-post-build-ledger');
+const build = require('./blog-post-build');
+const media = require('./blog-post-media');
+
+// The generated importer owns source conversion and crosswalk storage. This bridge owns
+// the ordering between verified build state, the normal crosswalk, and media closure.
+async function runBlogBuildStage({ projectDir, sourcePosts, preparedPosts, client, crosswalk,
+  pendingMedia, runId, checks = [], transforms = {}, options = {} }) {
+  if (!Array.isArray(sourcePosts) || !Array.isArray(preparedPosts))
+    throw new Error('blog stage needs sourcePosts and preparedPosts arrays');
+  if (!crosswalk || typeof crosswalk.get !== 'function' ||
+    typeof crosswalk.idOwners !== 'function' || typeof crosswalk.set !== 'function' ||
+    typeof crosswalk.recordVerified !== 'function') throw new Error('blog stage needs bound crosswalk operations');
+  if (!pendingMedia) throw new Error('blog stage needs pending media state');
+  const byKey = new Map(sourcePosts.map(post => [media.postStableKey(post), post]));
+  const preparedByKey = new Map(preparedPosts.map(post => [post.sourceStableKey, post]));
+  if (byKey.size !== sourcePosts.length || preparedByKey.size !== preparedPosts.length ||
+    preparedPosts.some(post => !byKey.has(post.sourceStableKey))) throw new Error('blog stage source keys differ');
+  const report = await build.runBlogBuild({ projectDir, posts: preparedPosts, client,
+    crosswalk, checks, transforms, options: { ...options, runId } });
+  const state = ledger.fold(ledger.readRows(projectDir));
+  for (const row of report.addresses.filter(item => item.phase === 'verified')) {
+    if (!byKey.has(row.sourceStableKey)) continue; // a resumed batch may omit earlier verified posts
+    const phase = state.posts.get(row.sourceStableKey)?.phase;
+    if (!phase?.postId) throw new Error(`verified blog post ${row.sourceStableKey} lacks post id`);
+    await crosswalk.recordVerified(byKey.get(row.sourceStableKey), phase.postId);
+    const prepared = preparedByKey.get(row.sourceStableKey);
+    if (prepared.existingCrosswalk) {
+      await pendingMedia.closeIfCrosswalked(byKey.get(row.sourceStableKey).id,
+        { targetPostId: phase.postId, runId });
+    } else {
+      await pendingMedia.markResolved(byKey.get(row.sourceStableKey).id,
+        { targetPostId: phase.postId, runId, resumed: prepared.mediaResumed === true });
+    }
+  }
+  const pending = await media.summarizePendingBlogMedia({ state: pendingMedia,
+    crosswalk: key => state.posts.get(key)?.phase?.phase === 'verified' });
+  // A pre-ledger crosswalk hit can have unresolved local media evidence without an
+  // open pending-media row (including an already-resolved historical row). Its build
+  // phase is still a pending post and must count against import completion.
+  const present = new Set(pending.pending.map(row => row.sourceStableKey));
+  for (const row of report.pending) {
+    if (present.has(row.sourceStableKey)) continue;
+    pending.pending.push({ sourceStableKey: row.sourceStableKey,
+      title: byKey.get(row.sourceStableKey)?.title || null, awaitingWrite: false,
+      reason: row.reason, media: row.media, existingCrosswalk: Boolean(preparedByKey.get(row.sourceStableKey)?.existingCrosswalk) });
+    present.add(row.sourceStableKey);
+  }
+  pending.pendingMedia = pending.pending.length;
+  return { report, pending };
+}
+
+module.exports = { runBlogBuildStage };