@wix/agent-skills 1.33.1 → 1.34.0

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

@@ -0,0 +1,715 @@
+'use strict';
+
+const ledger = require('./blog-post-build-ledger');
+const reports = require('./blog-post-build-report');
+const duplicates = require('./blog-post-build-duplicates');
+
+const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
+const NOT_FOUND_CODE = 'NOT_FOUND';
+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_CODE, '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; }
+}
+function stableKey(post) { return String(post.sourceStableKey ?? post.id); }
+function sourceDate(post) { return Date.parse(post.firstPublishedDate || post.date || 0) || 0; }
+function sortPosts(posts) { return [...posts].sort((a, b) => sourceDate(a) - sourceDate(b) || stableKey(a).localeCompare(stableKey(b))); }
+function sampleKeys(posts) {
+  if (!posts.length) return new Set();
+  const ordered = sortPosts(posts);
+  const chosen = [ordered[0]];
+  const longest = [...ordered].sort((a, b) =>
+    encodeURIComponent(b.desiredPost?.seoSlug || b.slug || '').length - encodeURIComponent(a.desiredPost?.seoSlug || a.slug || '').length)[0];
+  if (longest && stableKey(longest) !== stableKey(chosen[0])) chosen.push(longest);
+  const rest = ordered.filter(post => !chosen.includes(post)).sort((a, b) =>
+    ledger.sha(stableKey(a)).localeCompare(ledger.sha(stableKey(b))));
+  return new Set([...chosen, ...rest].slice(0, Math.min(10, posts.length)).map(stableKey));
+}
+function budgetPlan(posts, transforms = {}) {
+  const ready = posts.filter(post => post.mediaReady !== false);
+  if (transforms.rewriteLinks && ready.some(post => typeof post.hasPostLinks !== 'boolean')) {
+    throw new Error('blog preflight needs hasPostLinks for every ready post when link rewriting is registered');
+  }
+  const N = ready.length;
+  const S0 = ready.filter(post => post.slug && encodeURIComponent(post.slug).length > 100).length;
+  const L = ready.filter(post => post.hasPostLinks === true).length;
+  return { N, S0, L, ceiling: N + N + L + 40, expected: N + S0 + L + 40 };
+}
+function makeFinding(name, blocking, identity, details = {}) {
+  return { check: name, blocking, findingKey: ledger.sha({ name, identity }), ...details };
+}
+function defaultChecks() {
+  return [{ name: 'path', blocking: false, kind: 'verify', run(published, ctx) {
+    const actual = publishedPath(published);
+    const expected = ctx.expectedPath;
+    return actual === expected ? [] : [makeFinding('path', false,
+      { sourceStableKey: ctx.sourceStableKey, expected }, { expected, actual })];
+  } }];
+}
+function checkRegistry(checks = []) {
+  const out = [...defaultChecks(), ...checks];
+  const names = new Set();
+  for (const check of out) {
+    if (!check.name || !ledger.SNAPSHOT_KINDS.has(check.kind) ||
+      typeof check.run !== 'function' || typeof check.blocking !== 'boolean') throw new Error('invalid blog check');
+    if (names.has(check.name)) throw new Error(`duplicate blog check ${check.name}`);
+    names.add(check.name);
+  }
+  return out;
+}
+function phase(projectDir, post, value, extra = {}) {
+  return ledger.appendRow(projectDir, { kind: 'phase', sourceStableKey: stableKey(post), phase: value, ...extra });
+}
+function current(projectDir, key) { return ledger.fold(ledger.readRows(projectDir)).posts.get(key); }
+function bodyFrom(post) {
+  const body = post.desiredPost;
+  if (!body) throw new Error(`blog post ${stableKey(post)} has no desiredPost`);
+  return ledger.validateDesiredPost(structuredClone(body));
+}
+function commitGeneration(projectDir, post, draftId, desiredPost, origin, event, projection, extra = {}) {
+  const saved = ledger.saveGeneration(projectDir, stableKey(post), desiredPost, origin,
+    { draftId, ...extra });
+  return ledger.appendRow(projectDir, { kind: 'desired-state', sourceStableKey: stableKey(post),
+    draftId, ...saved, event, projection });
+}
+function desiredFor(projectDir, key) {
+  const state = current(projectDir, key);
+  if (!state?.desired) throw new Error(`blog post ${key}: no committed desired state`);
+  return ledger.loadGeneration(projectDir, state.desired.snapshotSha);
+}
+function validateClient(client) {
+  for (const name of ['createDraft', 'updateDraft', 'publishDraft', 'getDraft', 'getPost',
+    'listDrafts', 'deletePost']) {
+    if (typeof client?.[name] !== 'function') throw new Error(`blog client needs ${name}`);
+  }
+}
+async function allDrafts(client) {
+  const drafts = [];
+  let cursor = null;
+  const seen = new Set();
+  for (let page = 0; page < 1000; page += 1) {
+    const result = await client.listDrafts({ cursor });
+    if (!Array.isArray(result?.drafts)) throw new Error('draft listing lacked drafts array');
+    drafts.push(...result.drafts);
+    if (!result.nextCursor) return drafts;
+    if (seen.has(result.nextCursor)) throw new Error('draft listing cursor repeated');
+    seen.add(result.nextCursor);
+    cursor = result.nextCursor;
+  }
+  throw new Error('draft listing page cap reached');
+}
+function candidateCreatedAfter(candidate, intent) {
+  const created = Date.parse(candidate.createdDate || candidate.createdAt);
+  const started = Date.parse(intent.ts);
+  return Number.isFinite(created) && created >= started - 5 * 60_000;
+}
+function ownedElsewhere(id, key, state, crosswalk) {
+  if (typeof crosswalk?.idOwners !== 'function') throw new Error('blog adoption requires crosswalk.idOwners');
+  for (const [otherKey, other] of state.posts) {
+    if (otherKey !== key && other.rows.some(row => row.draftId === id || row.postId === id)) return true;
+  }
+  return crosswalk.idOwners(id).some(owner => String(owner) !== key);
+}
+async function candidateDrafts(client, intent, post, state, crosswalk, expectedHashes, expectedTitle) {
+  const list = await allDrafts(client);
+  const pref = list.filter(candidate => {
+    if (candidate.title !== expectedTitle) return false;
+    // A list page can omit fields that a full draft read includes. Do not interpret
+    // a sparse listing as proof that a draft does not match an uncertain create.
+    return !candidate.createdDate && !candidate.createdAt || candidateCreatedAfter(candidate, intent);
+  });
+  const matches = [];
+  const problems = [];
+  for (const candidate of pref) {
+    const full = await client.getDraft(candidate.id);
+    if (ledger.fingerprint(full) !== intent.fingerprint) continue;
+    if (!candidateCreatedAfter(full, intent)) {
+      problems.push({ id: candidate.id, creationTime: 'missing-or-outside-window' });
+      continue;
+    }
+    const bodyMatches = ledger.bodySha(full) === intent.createBodySha;
+    const owned = ownedElsewhere(candidate.id, stableKey(post), state, crosswalk);
+    const collision = expectedHashes.filter(value => value === intent.createBodySha).length > 1;
+    if (bodyMatches && !owned && !collision) matches.push(full);
+    else problems.push({ id: candidate.id, bodyMatches, ownedElsewhere: owned, sourceCollision: collision });
+  }
+  return { matches, problems };
+}
+async function recoverCreating(projectDir, post, client, crosswalk, expectedHashes, options) {
+  const key = stableKey(post);
+  const state = ledger.fold(ledger.readRows(projectDir));
+  const intent = state.posts.get(key).phase;
+  const title = desiredFor(projectDir, key).desiredPost.title;
+  let found = await candidateDrafts(client, intent, post, state, crosswalk, expectedHashes, title);
+  if (!found.matches.length && !found.problems.length) {
+    await sleep(options.settleMs ?? 10_000);
+    found = await candidateDrafts(client, intent, post, state, crosswalk, expectedHashes, title);
+  }
+  if (found.problems.length || found.matches.length > 1) {
+    phase(projectDir, post, 'held', { reason: 'adoption-ambiguous', candidates: [...found.matches.map(x => x.id), ...found.problems.map(x => x.id)] });
+    throw new Error(`blog post ${key}: adoption-ambiguous`);
+  }
+  if (found.matches.length === 1) return { draft: found.matches[0], recreated: false, adopted: true };
+  // The intent pins the complete body. Source input may have changed since the crash.
+  const pinned = desiredFor(projectDir, key).desiredPost;
+  if (ledger.bodySha(pinned) !== intent.createBodySha) throw new Error(`blog post ${key}: create intent body changed`);
+  const draft = await client.createDraft(pinned);
+  return { draft, recreated: true };
+}
+async function captureCreate(projectDir, post, client, crosswalk, expectedHashes, options) {
+  const key = stableKey(post);
+  let state = current(projectDir, key);
+  let newIntent = false;
+  if (!state?.phase || state.phase.phase === 'media-pending' ||
+    state.phase.phase === 'held' && state.phase.reason === 'desired-post-invalid' && !latestId(state)) {
+    const body = bodyFrom(post);
+    const oldId = crosswalk?.get ? await crosswalk.get(key) : null;
+    if (oldId) {
+      const id = typeof oldId === 'string' ? oldId : oldId.targetId || oldId.postId || oldId.draftId;
+      if (!id) throw new Error(`blog post ${key}: crosswalk row has no target id`);
+      const owners = typeof crosswalk.idOwners === 'function' ? crosswalk.idOwners(id).map(String) : [];
+      if (owners.length !== 1 || owners[0] !== key) {
+        phase(projectDir, post, 'held', { draftId: id, reason: 'legacy-mismatch' });
+        throw new Error(`blog post ${key}: legacy crosswalk id has ambiguous owners`);
+      }
+      const draft = await readOrNull(value => client.getDraft(value), id);
+      if (draft) {
+        const full = draft.draftPost || draft;
+        if (ledger.bodySha(full) !== ledger.bodySha(body) || ledger.fingerprint(full) !== ledger.fingerprint(body) ||
+          ownedElsewhere(id, key, ledger.fold(ledger.readRows(projectDir)), crosswalk) ||
+          expectedHashes.filter(hash => hash === ledger.bodySha(body)).length > 1) {
+          phase(projectDir, post, 'held', { draftId: id, reason: 'legacy-mismatch' });
+          throw new Error(`blog post ${key}: legacy-mismatch`);
+        }
+        commitGeneration(projectDir, post, id, body, 'source', 'captured', undefined,
+          { ownerState: post.ownerState });
+        phase(projectDir, post, 'drafted', { draftId: id, slug: full.slug || null,
+          fingerprint: ledger.fingerprint(body), createBodySha: ledger.bodySha(body),
+          storedBodySha: ledger.bodySha(full), legacy: true });
+        return;
+      }
+      const published = await readOrNull(value => client.getPost(value), id);
+      if (!published) throw new Error(`blog post ${key}: crosswalk target missing on both surfaces`);
+      options.publishedCache?.set(key, published);
+      const saved = commitGeneration(projectDir, post, id, body, 'source', 'captured', undefined,
+        { ownerState: post.ownerState });
+      const path = expectedPath(published.slug || body.seoSlug, post);
+      phase(projectDir, post, 'snapshot-saved', { draftId: id,
+        expectedPath: path, snapshotSha: saved.snapshotSha, snapshotOrigin: 'source' });
+      phase(projectDir, post, 'adopted-published', { draftId: id, postId: id,
+        expectedPath: path, publishedPath: publishedPath(published) });
+      return;
+    }
+    commitGeneration(projectDir, post, null, body, 'run', 'captured', undefined,
+      { ownerState: post.ownerState });
+    phase(projectDir, post, 'creating', { fingerprint: ledger.fingerprint(body), createBodySha: ledger.bodySha(body) });
+    state = current(projectDir, key);
+    newIntent = true;
+  }
+  if (state.phase.phase !== 'creating') return;
+  const result = newIntent
+    ? { draft: await client.createDraft(desiredFor(projectDir, key).desiredPost), recreated: false }
+    : await recoverCreating(projectDir, post, client, crosswalk, expectedHashes, options);
+  const draft = result.draft?.draftPost || result.draft;
+  if (!draft?.id) throw new Error(`blog post ${key}: create response lacks draft id`);
+  if (result.adopted && ledger.bodySha(draft) !== state.phase.createBodySha) {
+    phase(projectDir, post, 'held', { draftId: draft.id, reason: 'create-projection-mismatch' });
+    throw new Error(`blog post ${key}: create response body projection differs`);
+  }
+  phase(projectDir, post, 'drafted', { draftId: draft.id, slug: draft.slug || null,
+    fingerprint: state.phase.fingerprint, createBodySha: state.phase.createBodySha,
+    storedBodySha: ledger.bodySha(draft), recreatedAfterIntent: result.recreated });
+}
+function latestId(postState) {
+  return [...postState.rows].reverse().find(row => row.draftId)?.draftId;
+}
+function latestSlug(postState) {
+  return [...postState.rows].reverse().find(row => Object.hasOwn(row, 'slug'))?.slug || null;
+}
+function expectedPath(slug, post) {
+  if (!slug) return null;
+  const prefix = String(post?.blogPathPrefix || '/post').replace(/\/$/, '');
+  return `${prefix}/${encodeURIComponent(slug)}`;
+}
+function publishedPath(post) {
+  const raw = post?.url?.path || post?.url?.relativePath || post?.path || post?.url;
+  if (typeof raw === 'string') {
+    try { return new URL(raw).pathname; } catch { return raw; }
+  }
+  return null;
+}
+async function updateWithIntent(projectDir, post, client, draftId, desiredPost, projection, origin, ownerState) {
+  commitGeneration(projectDir, post, draftId, desiredPost, origin, 'update-intent', Object.keys(projection),
+    { ownerState });
+  const response = await client.updateDraft(draftId, projection);
+  const partial = response?.draftPost || response || {};
+  const committed = { ...desiredPost };
+  if (Object.hasOwn(partial, 'slug') && partial.slug) committed.seoSlug = partial.slug;
+  commitGeneration(projectDir, post, draftId, committed, origin, 'update-applied', Object.keys(projection),
+    { ownerState, finalSlug: partial.slug || null });
+  return { response: partial, desiredPost: committed };
+}
+async function finalizePost(projectDir, post, client, transforms = {}, options = {}) {
+  const key = stableKey(post);
+  let state = current(projectDir, key);
+  if (!state || ['media-pending', 'snapshot-saved', 'publishing', 'published',
+    'adopted-published', 'verified', 'verify-failed'].includes(state.phase?.phase)) return;
+  if (state.phase?.phase === 'links-final' && !state.pendingIntent) return;
+  if (state.phase?.phase === 'held' && ['adoption-ambiguous', 'legacy-mismatch',
+    'create-projection-mismatch'].includes(state.phase.reason)) return;
+  if (state.containmentOpen) return;
+  const draftId = latestId(state);
+  if (!draftId) return;
+  if ((state.phase.phase === 'contained' || state.phase.reason === 'leftover-after-publish') &&
+    typeof transforms.detectLeftovers !== 'function') {
+    if (state.phase.phase !== 'held') phase(projectDir, post, 'held', { draftId,
+      reason: 'leftover-after-publish' });
+    return;
+  }
+  let generation = desiredFor(projectDir, key);
+  let desired = generation.desiredPost;
+  let origin = generation.snapshotOrigin;
+  let ownerState = generation.ownerState;
+  let slug = latestSlug(state);
+  const heldResume = state.phase.phase === 'held' || state.phase.phase === 'contained' ||
+    state.pendingIntent && origin === 'held-draft';
+  if (heldResume) {
+    const liveDraft = await client.getDraft(draftId);
+    try { desired = ledger.fromDraftResponse(liveDraft); }
+    catch (error) { phase(projectDir, post, 'held', { draftId, reason: 'desired-post-invalid', detail: error.message }); return; }
+    origin = 'held-draft';
+    if (typeof transforms.captureOwnerState === 'function')
+      ownerState = await transforms.captureOwnerState(desired, post, ownerState);
+    commitGeneration(projectDir, post, draftId, desired, origin, 'captured', undefined,
+      { ownerState, finalSlug: (liveDraft.draftPost || liveDraft).slug || null });
+    const readSlug = (liveDraft.draftPost || liveDraft).slug || null;
+    if (!readSlug) { if (state.phase.reason !== 'slug-missing-in-response') phase(projectDir, post, 'held', { draftId, reason: 'slug-missing-in-response' }); return; }
+    if (slug && readSlug !== slug) { if (state.phase.reason !== 'slug-changed-while-held') phase(projectDir, post, 'held', { draftId, reason: 'slug-changed-while-held', slug }); return; }
+    slug = readSlug;
+  }
+  if (!heldResume && (state.phase.phase === 'drafted' || state.phase.phase === 'held' || state.phase.phase === 'contained')) {
+    if (!slug || post.forceSlugUpdate) {
+      const sourceSlug = post.slug || desired.seoSlug;
+      if (!sourceSlug) { phase(projectDir, post, 'held', { draftId, reason: 'slug-missing-in-response' }); return; }
+      desired.seoSlug = sourceSlug;
+      const update = await updateWithIntent(projectDir, post, client, draftId, desired,
+        { seoSlug: sourceSlug, media: desired.media }, origin, ownerState);
+      desired = update.desiredPost;
+      slug = update.response.slug || null;
+      if (!slug) { phase(projectDir, post, 'held', { draftId, reason: 'slug-missing-in-response' }); return; }
+      phase(projectDir, post, 'slug-set', { draftId, slug, expectedPath: expectedPath(slug, post) });
+    }
+  }
+  if (!slug) { phase(projectDir, post, 'held', { draftId, reason: 'slug-missing-in-response' }); return; }
+  if (options.slugOnly) return;
+  const index = options.slugIndex || new Map();
+  const rewritten = transforms.rewriteLinks ? await transforms.rewriteLinks(structuredClone(desired), post, index) : desired;
+  if (rewritten?.waitingFor?.length) {
+    phase(projectDir, post, 'held', { draftId, slug, reason: 'waiting-for-linked-post', waitingFor: rewritten.waitingFor }); return;
+  }
+  const next = rewritten?.desiredPost || rewritten;
+  if (ledger.canonical(next.richContent) !== ledger.canonical(desired.richContent)) {
+    desired = next;
+    const update = await updateWithIntent(projectDir, post, client, draftId, desired,
+      { richContent: desired.richContent, media: desired.media }, origin, ownerState);
+    desired = update.desiredPost;
+    if (!update.response.slug) { phase(projectDir, post, 'held', { draftId, reason: 'slug-missing-in-response' }); return; }
+    if (update.response.slug !== slug) {
+      phase(projectDir, post, 'held', { draftId, slug, reason: 'slug-changed-while-held' });
+      return;
+    }
+    slug = update.response.slug;
+  }
+  const leftovers = transforms.detectLeftovers ? await transforms.detectLeftovers(desired, post, index) : [];
+  ledger.appendRow(projectDir, { kind: 'leftover-set', sourceStableKey: key, findings: leftovers });
+  const blockingLeftover = leftovers.find(f => f.blocking);
+  if (blockingLeftover) {
+    const reason = blockingLeftover.check === 'source-address' ? 'source-address-outside-link' :
+      blockingLeftover.reason === 'source-address-outside-link' ? blockingLeftover.reason : 'leftover-after-rewrite';
+    if (state.phase.phase !== 'held' || state.phase.reason !== reason)
+      phase(projectDir, post, 'held', { draftId, slug, reason });
+    return;
+  }
+  phase(projectDir, post, 'links-final', { draftId, slug, expectedPath: expectedPath(slug, post) });
+}
+async function proveAbsence(client, id, waits = [1000, 2000, 4000, 8000, 15000]) {
+  for (const wait of waits) {
+    if (wait) await sleep(wait);
+    const published = await readOrNull(value => client.getPost(value), id);
+    if (published) return { published: true, post: published };
+  }
+  const draft = await readOrNull(value => client.getDraft(value), id);
+  if (!draft) throw new Error(`blog post ${id}: absence ambiguous; both post and draft missing`);
+  return { published: false, draft };
+}
+async function verifyPost(projectDir, post, client, checks, sampled, via = 'read', fetchLivePage = true,
+  alreadyRead = null) {
+  const key = stableKey(post);
+  const state = current(projectDir, key);
+  const id = latestId(state);
+  const published = alreadyRead || await client.getPost(id);
+  const expected = [...state.rows].reverse().find(row => row.expectedPath)?.expectedPath;
+  const ctx = { sourceStableKey: key, sourcePost: post, expectedPath: expected, sampled };
+  const findings = [];
+  const byKind = new Map();
+  for (const check of checks) {
+    const result = await check.run(published, ctx);
+    if (!Array.isArray(result)) throw new Error(`blog check ${check.name} did not return findings`);
+    if (!byKind.has(check.kind)) byKind.set(check.kind, []);
+    for (const finding of result) {
+      if (!finding?.findingKey) throw new Error(`blog check ${check.name} returned a finding without findingKey`);
+      const normalized = { ...finding, check: check.name, blocking: check.blocking };
+      findings.push(normalized);
+      byKind.get(check.kind).push(normalized);
+    }
+  }
+  if (sampled && fetchLivePage) {
+    if (typeof client.fetchPage !== 'function') throw new Error('live-page fetch required for the verification sample');
+    const page = await client.fetchPage(expected);
+    if (page.status !== 200 || String(page.body || '').includes('fit/w_0')) {
+      findings.push(makeFinding('live-page', false, { key, expected }, { status: page.status }));
+    }
+    const covers = page.coverUrls || [];
+    if (covers.length > 3) throw new Error('sample page reported more than three cover URLs');
+    for (const url of covers) {
+      if (typeof client.fetchImage !== 'function') throw new Error('cover-image fetch required for a sampled page with a cover');
+      const result = await client.fetchImage(url);
+      if (result.status !== 200) findings.push(makeFinding('cover-url', false, { key, url }, { status: result.status }));
+    }
+  }
+  for (const [kind, ownFindings] of byKind) {
+    if (kind !== 'verify') ledger.appendRow(projectDir, { kind, sourceStableKey: key, findings: ownFindings });
+  }
+  if (!fetchLivePage) {
+    for (const old of state.openFindings?.verify || []) {
+      if (['live-page', 'cover-url'].includes(old.check)) findings.push(old);
+    }
+  }
+  ledger.appendRow(projectDir, { kind: 'verify', sourceStableKey: key, findings, sampled,
+    publishedPath: publishedPath(published) });
+  const blocking = findings.some(finding => finding.blocking);
+  if (blocking) return { blocking, findings, published };
+  if (findings.length) phase(projectDir, post, 'verify-failed', { draftId: id,
+    postId: id, publishedPath: publishedPath(published), reason: 'checks-failed' });
+  else phase(projectDir, post, 'verified', { draftId: id, postId: id,
+    publishedPath: publishedPath(published), via });
+  return { blocking, findings, published };
+}
+async function containPost(projectDir, post, client, crosswalk, expectedHashes = [], options = {}) {
+  const key = stableKey(post);
+  let state = current(projectDir, key);
+  const id = state.containmentOpen
+    ? [...state.rows].reverse().find(row => row.phase === 'containing')?.postId
+    : latestId(state);
+  if (!state.containmentOpen) {
+    const snap = [...state.rows].reverse().find(row => row.phase === 'snapshot-saved');
+    const evidenceFile = options.published
+      ? ledger.savePublishedEvidence(projectDir, key, options.published) : null;
+    phase(projectDir, post, 'containing', { draftId: id, postId: id,
+      snapshotSha: snap?.snapshotSha, evidenceFile,
+      exposedFrom: [...state.rows].reverse().find(row =>
+        ['publishing', 'adopted-published'].includes(row.phase))?.ts });
+    state = current(projectDir, key);
+  }
+  let last = state.phase.phase;
+  if (last === 'containing' || last === 'contain-failed' && state.phase.reason === 'delete-failed') {
+    try {
+      const before = await readOrNull(value => client.getPost(value), id);
+      if (before) await client.deletePost(id);
+      const missing = await readOrNull(value => client.getPost(value), id);
+      if (missing) throw new Error('published post still exists');
+      phase(projectDir, post, 'contain-deleted', { draftId: id, postId: id, containedAt: new Date().toISOString() });
+    } catch (error) {
+      phase(projectDir, post, 'contain-failed', { draftId: id, postId: id, reason: 'delete-failed', detail: error.message });
+      throw error;
+    }
+  }
+  state = current(projectDir, key); last = state.phase.phase;
+  const snap = [...state.rows].reverse().find(row => row.phase === 'snapshot-saved');
+  const sourceRecovery = [...state.rows].reverse().find(row => row.phase === 'contain-recreating' && row.snapshotSha);
+  let saved;
+  try { saved = ledger.loadGeneration(projectDir, sourceRecovery?.snapshotSha || snap?.snapshotSha, key); }
+  catch (error) {
+    const approval = options.confirmSourceRebuild;
+    if (!approval || !String(approval.confirmedBy || '').trim() || !String(approval.note || '').trim()) {
+      if (last !== 'contain-failed' || state.phase.reason !== 'snapshot-missing')
+        phase(projectDir, post, 'contain-failed', { draftId: id, postId: id, reason: 'snapshot-missing' });
+      throw new Error(`blog post ${key}: snapshot-missing requires a named source-rebuild confirmation`);
+    }
+    if (sourceRecovery) throw new Error(`blog post ${key}: confirmed source-rebuild snapshot is missing`);
+    const rebuilt = bodyFrom(post);
+    const row = commitGeneration(projectDir, post, id, rebuilt, 'source', 'captured', undefined,
+      { ownerState: post.ownerState });
+    phase(projectDir, post, 'contain-recreating', { draftId: id, postId: id,
+      fingerprint: ledger.fingerprint(rebuilt), createBodySha: ledger.bodySha(rebuilt),
+      snapshotSha: row.snapshotSha, sourceRebuildBy: approval.confirmedBy,
+      sourceRebuildNote: approval.note });
+    state = current(projectDir, key); last = state.phase.phase;
+    saved = ledger.loadGeneration(projectDir, row.snapshotSha, key);
+  }
+  if (last === 'contain-deleted' || last === 'contain-failed' && state.phase.reason !== 'delete-failed') {
+    let draft = await readOrNull(value => client.getDraft(value), id);
+    if (!draft) {
+      const previousIntent = [...state.rows].reverse().find(row => row.phase === 'contain-recreating');
+      if (!previousIntent || last === 'contain-deleted') {
+        phase(projectDir, post, 'contain-recreating', { draftId: id,
+          fingerprint: ledger.fingerprint(saved.desiredPost), createBodySha: ledger.bodySha(saved.desiredPost) });
+        state = current(projectDir, key);
+      }
+      last = 'contain-recreating';
+    }
+    if (draft) {
+      const newId = (draft.draftPost || draft).id;
+      phase(projectDir, post, 'contain-drafted', { draftId: newId, postId: id,
+        storedBodySha: ledger.bodySha(draft), survivedDelete: true });
+      commitGeneration(projectDir, post, newId, saved.desiredPost, saved.snapshotOrigin, 'captured', undefined,
+        { ownerState: saved.ownerState, finalSlug: saved.finalSlug });
+    }
+  }
+  state = current(projectDir, key); last = state.phase.phase;
+  if (last === 'contain-recreating' || last === 'contain-failed' &&
+    ['recreate-failed', 'recreate-ambiguous'].includes(state.phase.reason)) {
+    const intent = [...state.rows].reverse().find(row => row.phase === 'contain-recreating');
+    let found = await candidateDrafts(client, intent, post, ledger.fold(ledger.readRows(projectDir)),
+      crosswalk, expectedHashes.length ? expectedHashes : [intent.createBodySha], saved.desiredPost.title);
+    if (!found.matches.length && !found.problems.length) {
+      await sleep(options.settleMs ?? 10_000);
+      found = await candidateDrafts(client, intent, post, ledger.fold(ledger.readRows(projectDir)),
+        crosswalk, expectedHashes.length ? expectedHashes : [intent.createBodySha], saved.desiredPost.title);
+    }
+    if (found.problems.length || found.matches.length > 1) {
+      phase(projectDir, post, 'contain-failed', { draftId: id, postId: id, reason: 'recreate-ambiguous',
+        candidates: [...found.matches.map(x => x.id), ...found.problems.map(x => x.id)] });
+      throw new Error(`blog post ${key}: recreate-ambiguous`);
+    }
+    let draft;
+    const recreatedAfterIntent = found.matches.length === 0;
+    try { draft = found.matches[0] || await client.createDraft(saved.desiredPost); }
+    catch (error) { phase(projectDir, post, 'contain-failed', { draftId: id, postId: id, reason: 'recreate-failed' }); throw error; }
+    const newId = (draft.draftPost || draft).id;
+    if (!newId || !recreatedAfterIntent && ledger.bodySha(draft) !== intent.createBodySha) {
+      phase(projectDir, post, 'contain-failed', { draftId: id, postId: id, reason: 'recreate-ambiguous' });
+      throw new Error(`blog post ${key}: recreated draft body mismatch`);
+    }
+    phase(projectDir, post, 'contain-drafted', { draftId: newId, postId: id,
+      storedBodySha: ledger.bodySha(draft), recreatedAfterIntent });
+    commitGeneration(projectDir, post, newId, saved.desiredPost, saved.snapshotOrigin, 'captured', undefined,
+      { ownerState: saved.ownerState, finalSlug: saved.finalSlug });
+  }
+  state = current(projectDir, key); last = state.phase.phase;
+  if (last === 'contain-drafted') {
+    if (crosswalk && typeof crosswalk.set !== 'function') throw new Error('containment requires crosswalk.set');
+    if (crosswalk?.set) await crosswalk.set(key, latestId(state));
+    phase(projectDir, post, 'contain-linked', { draftId: latestId(state), postId: id });
+  }
+  state = current(projectDir, key);
+  if (state.phase.phase === 'contain-linked') {
+    const operation = [...state.rows].reverse().find(row => row.phase === 'containing');
+    const deletion = [...state.rows].reverse().find(row => row.phase === 'contain-deleted');
+    phase(projectDir, post, 'contained', { draftId: latestId(state), postId: id,
+      reason: 'leftover-after-publish', exposedFrom: operation?.exposedFrom,
+      containedAt: deletion?.containedAt, snapshotSha: operation?.snapshotSha });
+  }
+}
+async function publishPost(projectDir, post, client, checks, sampled, options) {
+  const key = stableKey(post);
+  let state = current(projectDir, key);
+  if (!state || state.containmentOpen) return;
+  const id = latestId(state);
+  if (state.phase.phase === 'links-final') {
+    const currentBody = desiredFor(projectDir, key);
+    const saved = commitGeneration(projectDir, post, id, currentBody.desiredPost,
+      currentBody.snapshotOrigin, 'captured', undefined,
+      { ownerState: currentBody.ownerState, finalSlug: state.phase.slug });
+    ledger.loadGeneration(projectDir, saved.snapshotSha);
+    phase(projectDir, post, 'snapshot-saved', { draftId: id,
+      slug: state.phase.slug, expectedPath: state.phase.expectedPath, snapshotSha: saved.snapshotSha });
+  }
+  state = current(projectDir, key);
+  if (state.phase.phase === 'snapshot-saved') {
+    ledger.loadGeneration(projectDir, state.phase.snapshotSha);
+    phase(projectDir, post, 'publishing', { draftId: id, expectedPath: state.phase.expectedPath });
+    await client.publishDraft(id);
+    phase(projectDir, post, 'published', { draftId: id, postId: id,
+      expectedPath: state.phase.expectedPath });
+  } else if (state.phase.phase === 'publishing') {
+    const absence = await proveAbsence(client, id, options.absenceWaits);
+    if (!absence.published) await client.publishDraft(id);
+    phase(projectDir, post, 'published', { draftId: id, postId: id,
+      expectedPath: state.phase.expectedPath });
+  }
+  state = current(projectDir, key);
+  if (!['published', 'adopted-published'].includes(state.phase.phase)) return;
+  const result = await verifyPost(projectDir, post, client, checks, sampled, 'read', true,
+    options.publishedCache?.get(key));
+  if (result.blocking) {
+    await containPost(projectDir, post, client, options.crosswalk, options.expectedHashes,
+      { ...options, published: result.published });
+    throw new Error(`blog post ${key}: blocking verification failed; contained`);
+  }
+  return result;
+}
+async function runBlogBuild({ projectDir, posts, client, crosswalk, checks = [], transforms = {}, options = {} }) {
+  validateClient(client);
+  const originalClient = client;
+  const measured = [];
+  let activeKey = null;
+  client = Object.create(originalClient);
+  for (const name of ['createDraft', 'updateDraft', 'publishDraft', 'getDraft', 'getPost',
+    'listDrafts', 'deletePost', 'fetchPage', 'fetchImage']) {
+    if (typeof originalClient[name] !== 'function') continue;
+    client[name] = async (...args) => {
+      const started = Date.now();
+      try { return await originalClient[name](...args); }
+      finally { measured.push({ name, key: activeKey, ms: Date.now() - started }); }
+    };
+  }
+  if (!Array.isArray(posts)) throw new Error('blog posts must be an array');
+  const ordered = sortPosts(posts);
+  const budget = budgetPlan(ordered, transforms);
+  const log = options.log || console.log;
+  log(`Blog preflight estimate (before writes): N=${budget.N}, S0=${budget.S0}, L=${budget.L}; ` +
+    `added-call ceiling ${budget.ceiling}, expected ${budget.expected} (plus existing creates/publishes; 40 is a fixed maximum).`);
+  const registry = checkRegistry(checks);
+  return ledger.withLock(projectDir, async () => {
+    let finalReport;
+    try {
+      ledger.setRunId(projectDir, options.runId);
+      ledger.resetSnapshotMetrics(projectDir);
+      const publishedCache = new Map();
+      const hashes = [];
+      const invalidKeys = new Set();
+      for (const post of ordered.filter(item => item.desiredPost)) {
+        const state = current(projectDir, stableKey(post));
+        try {
+          hashes.push(ledger.bodySha(state?.desired ? desiredFor(projectDir, stableKey(post)).desiredPost : bodyFrom(post)));
+        } catch (error) {
+          // A referenced generation is durable recovery state. Corruption cannot be
+          // reclassified as a source validation hold and must stop before Wix writes.
+          if (state?.desired && !state.containmentOpen) throw error;
+          if (state?.containmentOpen ||
+            ['published', 'adopted-published', 'verified', 'verify-failed'].includes(state?.phase?.phase)) {
+            const original = state.rows.find(row => row.createBodySha)?.createBodySha;
+            if (original) hashes.push(original);
+            continue;
+          }
+          invalidKeys.add(stableKey(post));
+          if (state?.phase?.phase !== 'held' || state.phase.reason !== 'desired-post-invalid')
+            phase(projectDir, post, 'held', { draftId: state && latestId(state),
+              reason: 'desired-post-invalid', detail: error.message });
+        }
+      }
+      await duplicates.finishPendingEvidence(projectDir, client, crosswalk);
+      for (const post of ordered) {
+        const key = stableKey(post);
+        activeKey = key;
+        if (invalidKeys.has(key)) continue;
+        const state = current(projectDir, key);
+        if (state?.containmentOpen) {
+          await containPost(projectDir, post, client, crosswalk, hashes, options);
+          throw new Error(`blog post ${key}: containment completed; run stopped`);
+        }
+        if (['verified', 'verify-failed', 'published', 'adopted-published'].includes(state?.phase?.phase)) continue;
+        if (post.mediaReady === false) {
+          const reason = post.mediaPendingReason || 'media-not-ready';
+          if (!state?.phase || state.phase.phase !== 'media-pending' || state.phase.reason !== reason)
+            phase(projectDir, post, 'media-pending', { reason });
+          continue;
+        }
+        if (!state?.phase || state.phase.phase === 'media-pending' || state.phase.phase === 'creating' ||
+          state.phase.phase === 'held' && state.phase.reason === 'desired-post-invalid' && !latestId(state)) {
+          await captureCreate(projectDir, post, client, crosswalk, hashes,
+            { ...options, publishedCache });
+        }
+      }
+      const exactSlugUpdates = ordered.filter(post => {
+        const state = current(projectDir, stableKey(post));
+        return state?.phase?.phase === 'drafted' && (!latestSlug(state) || post.forceSlugUpdate);
+      }).length;
+      log(`Blog preflight estimate (after drafts, before updates): N=${budget.N}, S=${exactSlugUpdates}, ` +
+        `L=${budget.L}; added-call ceiling ${budget.N + exactSlugUpdates + budget.L + 40}.`);
+      const slugIndex = new Map();
+      for (const post of ordered) {
+        activeKey = stableKey(post);
+        const state = current(projectDir, stableKey(post));
+        if (state?.phase?.phase === 'drafted' && !latestSlug(state)) {
+          await finalizePost(projectDir, post, client, transforms, { slugOnly: true });
+        }
+      }
+      for (const post of ordered) {
+        activeKey = stableKey(post);
+        const state = current(projectDir, stableKey(post));
+        const slug = state && latestSlug(state);
+        if (slug) slugIndex.set(stableKey(post), slug);
+      }
+      for (const post of ordered) {
+        activeKey = stableKey(post);
+        await finalizePost(projectDir, post, client, transforms, { slugIndex });
+        const state = current(projectDir, stableKey(post));
+        const slug = state && latestSlug(state);
+        if (slug) slugIndex.set(stableKey(post), slug);
+      }
+      const sample = sampleKeys(ordered.filter(post => {
+        const state = current(projectDir, stableKey(post));
+        return state?.phase && !state.containmentOpen &&
+          !['media-pending', 'held', 'contain-failed', 'contained'].includes(state.phase.phase);
+      }));
+      if (sample.size && (typeof client.fetchPage !== 'function' || typeof client.fetchImage !== 'function')) {
+        throw new Error('blog sample requires fetchPage and fetchImage before the first publish');
+      }
+      let canaryDone = false;
+      for (const post of ordered) {
+        activeKey = stableKey(post);
+        const state = current(projectDir, stableKey(post));
+        if (state?.phase && ['links-final', 'snapshot-saved', 'publishing', 'published', 'adopted-published'].includes(state.phase.phase)) {
+          if (state.rows.some(row => ['drafted', 'contain-drafted'].includes(row.phase) && row.recreatedAfterIntent)) {
+            await duplicates.detectExtraDrafts(projectDir, client, crosswalk, stableKey(post));
+          }
+          const result = await publishPost(projectDir, post, client, registry, sample.has(stableKey(post)),
+            { ...options, crosswalk, expectedHashes: hashes, publishedCache });
+          if (!canaryDone) {
+            if (result?.findings?.length) throw new Error(`blog canary ${stableKey(post)} failed verification`);
+            canaryDone = true;
+            const added = measured.filter(item => item.key === stableKey(post) &&
+              ['updateDraft', 'getPost', 'fetchPage', 'fetchImage'].includes(item.name));
+            const snapshots = ledger.snapshotMetrics(projectDir, stableKey(post));
+            log(`Blog canary local snapshots (measured): ${snapshots.generations} generations, ` +
+              `${snapshots.bytes} serialized bytes, ${snapshots.ms.toFixed(1)} ms.`);
+            if (added.length) {
+              const meanMs = added.reduce((sum, item) => sum + item.ms, 0) / added.length;
+              log(`Blog canary timing (measured ${added.length} added calls): mean ${meanMs.toFixed(1)} ms; ` +
+                `estimated clean added-call ceiling ${((budget.N + exactSlugUpdates + budget.L + 40) * meanMs / 1000).toFixed(1)} s. ` +
+                'The estimate excludes unchanged creates/publishes and local snapshot I/O.');
+            }
+          }
+        }
+      }
+      await duplicates.detectExtraDrafts(projectDir, client, crosswalk);
+    } finally {
+      try { finalReport = (await reports.refreshBlogHandoff(projectDir)).report; }
+      finally { ledger.setRunId(projectDir, null); }
+    }
+    return finalReport;
+  });
+}
+async function reverify({ projectDir, post, client, crosswalk, checks = [], sampled, options = {} }) {
+  validateClient(client);
+  return ledger.withLock(projectDir, async () => {
+    const state = current(projectDir, stableKey(post));
+    if (state?.phase?.phase !== 'verify-failed') throw new Error('post is not verify-failed');
+    const result = await verifyPost(projectDir, post, client, checkRegistry(checks),
+      sampled === undefined ? state.snapshots.verify?.sampled === true : sampled, 'reverify', false);
+    if (result.blocking) { await containPost(projectDir, post, client, crosswalk, [ledger.bodySha(bodyFrom(post))], options); }
+    return (await reports.refreshBlogHandoff(projectDir)).report;
+  });
+}
+
+module.exports = { runBlogBuild, reverify, sampleKeys, sortPosts, checkRegistry,
+  makeFinding, allDrafts, proveAbsence, isNotFound, expectedPath };