feat(serenity): confirm publish completion via publish_status poll (LLMO-5492 AC3)

Implements AC3 (publish-completion polling), previously deferred because the
transport had no way to read a project's publish state.

- rest-transport: add getProjectStatus(ws, pid) -> GET /v1/workspaces/{ws}/
  projects/{pid} (v1 default view, which echoes publish_status faithfully;
  the v2/live=true view empties a never-published draft's config).
- handlers/publish-status.js (new): the reusable read/classify/poll mechanism
  built on the publish_status enum (draft | publishing | initial_publish_failed
  | live | live_with_unpublished_updates). classifyPublishStatus maps to
  published/failed/pending; pollProjectPublished bounds the poll by attempts/
  interval. The DRS/audit worker's unbounded <=900s reconcile loop consumes the
  same helper; finalize uses a tiny in-Lambda bound.
- finalize: after the async publish (202) is accepted, do a bounded best-effort
  confirm. Opt-in via `typeof transport.getProjectStatus === 'function'`, so the
  existing 6-arg callers/tests are unchanged; new 7th `options` arg
  {confirmAttempts, confirmIntervalMs}. Confirmed live -> published;
  initial_publish_failed -> publishFailed (surfaced early); still draft/
  publishing within budget or status unreadable -> stays published (accepted;
  the worker reconciles) so an in-progress async publish is not mislabeled.

Tests: rest-transport (getProjectStatus URL), publish-status (classify + poll),
finalize (confirm outcomes). 61 passing across the three suites; lint clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: 2 people

src/support/serenity/handlers/finalize.js

@@ -15,6 +15,7 @@ import { hasText } from '@adobe/spacecat-shared-utils';
 import { ErrorWithStatusCode } from '../../utils.js';
 import { handleCreatePrompts } from './prompts.js';
 import { handleUpdateModels } from './markets.js';
+import { pollProjectPublished, PUBLISH_OUTCOME } from './publish-status.js';
 
 /**
  * LLMO-5492 — publish-after-populate finalize step.
@@ -49,6 +50,11 @@ import { handleUpdateModels } from './markets.js';
  * @param {string} semrushWorkspaceId - Org's Semrush workspace id.
  * @param {object} body - { prompts?: Array, models?: Array<{geoTargetId, languageCode, modelIds}> }
  * @param {object} [log] - Logger.
+ * @param {object} [options] - Publish-confirm tuning (AC3).
+ * @param {number} [options.confirmAttempts=1] - Max getProjectStatus reads per
+ *   project after publish (bounded to the Lambda budget; the unbounded ≤900s
+ *   reconcile loop is the DRS/worker's job, not this Lambda's).
+ * @param {number} [options.confirmIntervalMs=0] - Delay between confirm reads.
  * @returns {Promise<{prompts: object, models: Array, published: string[], publishFailed: Array}>}
  */
 export async function finalizeSerenityProjects(
@@ -58,6 +64,7 @@ export async function finalizeSerenityProjects(
   semrushWorkspaceId,
   body,
   log,
+  options = {},
 ) {
   if (!hasText(brandId)) {
     throw new ErrorWithStatusCode('brandId is required', 400);
@@ -149,20 +156,63 @@ export async function finalizeSerenityProjects(
   const projectIds = [...new Set(
     rows.map((r) => r.getSemrushProjectId()).filter((id) => hasText(id)),
   )];
+  // AC3: publish is async (202) with no completion webhook. After the publish
+  // is accepted we do a BOUNDED, best-effort confirm via the project's
+  // `publish_status` (handlers/publish-status.js). The bound stays inside the
+  // Lambda wall budget — the unbounded ≤900s reconcile poll is the DRS/worker's
+  // job. Confirm semantics:
+  //   - confirmed live                → published
+  //   - initial_publish_failed        → publishFailed (terminal, surfaced early)
+  //   - still draft/publishing/unknown within budget, OR status unreadable
+  //                                    → published (accepted; the worker
+  //                                      reconciles) — we do NOT mislabel an
+  //                                      in-progress async publish as a failure.
+  const { confirmAttempts = 1, confirmIntervalMs = 0 } = options;
+  const canConfirm = typeof transport.getProjectStatus === 'function';
   const published = [];
   const publishFailed = [];
   for (const projectId of projectIds) {
     try {
       // eslint-disable-next-line no-await-in-loop
       await transport.publishProject(semrushWorkspaceId, projectId);
-      published.push(projectId);
     } catch (e) {
       log?.error?.('finalizeSerenityProjects: publish failed', {
         brandId,
         projectId,
         error: e.message,
       });
       publishFailed.push({ projectId, error: e.message });
+      // eslint-disable-next-line no-continue
+      continue;
+    }
+
+    if (!canConfirm) {
+      published.push(projectId);
+      // eslint-disable-next-line no-continue
+      continue;
+    }
+
+    // eslint-disable-next-line no-await-in-loop
+    const confirm = await pollProjectPublished(transport, semrushWorkspaceId, projectId, {
+      attempts: confirmAttempts,
+      intervalMs: confirmIntervalMs,
+      log,
+    });
+    if (confirm.outcome === PUBLISH_OUTCOME.FAILED) {
+      log?.error?.('finalizeSerenityProjects: publish reported failed by upstream', {
+        brandId,
+        projectId,
+        publishStatus: confirm.status,
+        failedReason: confirm.failedReason,
+      });
+      publishFailed.push({
+        projectId,
+        error: confirm.failedReason || confirm.status || 'initial_publish_failed',
+        publishStatus: confirm.status,
+      });
+    } else {
+      // published (confirmed live) or pending (accepted, worker reconciles).
+      published.push(projectId);
     }
   }
 

src/support/serenity/handlers/publish-status.js

@@ -0,0 +1,170 @@
+/*
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+/**
+ * LLMO-5492 / AC3 — publish-completion status reading.
+ *
+ * Semrush publishes a project asynchronously: POST .../publish returns 202 and
+ * the project's `publish_status` attribute transitions in the background, with
+ * no completion webhook. Completion is therefore observed by re-reading the
+ * project (transport.getProjectStatus) and inspecting `publish_status`.
+ *
+ * This module is the reusable read/classify/poll mechanism. Two consumers:
+ *   - finalize.js does a BOUNDED, best-effort confirm within the Lambda's wall
+ *     budget (one or a few reads) to catch an early hard failure.
+ *   - the DRS/audit worker (a separate repo, SQS-driven, ≤900s) drives the
+ *     UNBOUNDED long-poll using the same classify logic.
+ *
+ * Enum (serenity-docs §6):
+ *   draft | publishing | initial_publish_failed | live | live_with_unpublished_updates
+ */
+
+export const PUBLISH_STATUS = {
+  DRAFT: 'draft',
+  PUBLISHING: 'publishing',
+  INITIAL_PUBLISH_FAILED: 'initial_publish_failed',
+  LIVE: 'live',
+  LIVE_WITH_UNPUBLISHED_UPDATES: 'live_with_unpublished_updates',
+};
+
+// "Published" = the project is live to consumers, whether or not it carries
+// later unpublished draft edits.
+const PUBLISHED_STATES = new Set([
+  PUBLISH_STATUS.LIVE,
+  PUBLISH_STATUS.LIVE_WITH_UNPUBLISHED_UPDATES,
+]);
+
+// Terminal failure of the FIRST publish. `publishing` is in-progress (not a
+// failure); only `initial_publish_failed` is terminal-bad.
+const FAILED_STATES = new Set([PUBLISH_STATUS.INITIAL_PUBLISH_FAILED]);
+
+/**
+ * Outcome buckets returned by classifyPublishStatus / pollProjectPublished.
+ * `pending` covers draft, publishing, and any unknown/absent status — i.e.
+ * "not yet confirmed live, not yet confirmed failed".
+ */
+export const PUBLISH_OUTCOME = {
+  PUBLISHED: 'published',
+  FAILED: 'failed',
+  PENDING: 'pending',
+};
+
+const DEFAULT_ATTEMPTS = 1;
+const DEFAULT_INTERVAL_MS = 0;
+
+const defaultSleep = (ms) => new Promise((resolve) => {
+  setTimeout(resolve, ms);
+});
+
+/**
+ * Reads `publish_status` off a project payload, tolerating both the upstream
+ * snake_case form and a normalised camelCase form.
+ * @param {object} project - Raw project JSON from getProjectStatus.
+ * @returns {string|null}
+ */
+export function readPublishStatus(project) {
+  return project?.publish_status ?? project?.publishStatus ?? null;
+}
+
+/**
+ * Maps a project payload to a PUBLISH_OUTCOME.
+ * @param {object} project - Raw project JSON from getProjectStatus.
+ * @returns {'published'|'failed'|'pending'}
+ */
+export function classifyPublishStatus(project) {
+  const status = readPublishStatus(project);
+  if (PUBLISHED_STATES.has(status)) {
+    return PUBLISH_OUTCOME.PUBLISHED;
+  }
+  if (FAILED_STATES.has(status)) {
+    return PUBLISH_OUTCOME.FAILED;
+  }
+  return PUBLISH_OUTCOME.PENDING;
+}
+
+/**
+ * Polls getProjectStatus until the project is confirmed live or confirmed
+ * failed, or the attempt budget is exhausted. A status-read error is non-fatal
+ * to the poll (logged, retried, and reported as `pending` if it persists) —
+ * the caller decides how to treat an unconfirmed publish.
+ *
+ * Bounded by `attempts`/`intervalMs`. finalize uses a tiny budget (the long
+ * ≤900s reconcile loop is the worker's job); the worker passes a large one.
+ *
+ * @param {object} transport - Serenity REST transport (needs getProjectStatus).
+ * @param {string} semrushWorkspaceId
+ * @param {string} projectId
+ * @param {object} [opts]
+ * @param {number} [opts.attempts=1] - Max status reads (>=1).
+ * @param {number} [opts.intervalMs=0] - Delay between reads.
+ * @param {object} [opts.log] - Logger.
+ * @param {function} [opts.sleep] - Injectable delay (tests pass a no-op).
+ * @returns {Promise<{outcome:string, status:(string|null), publishedAt:(string|null),
+ *   failedReason:(string|null), attempts:number, error?:string}>}
+ */
+export async function pollProjectPublished(
+  transport,
+  semrushWorkspaceId,
+  projectId,
+  {
+    attempts = DEFAULT_ATTEMPTS,
+    intervalMs = DEFAULT_INTERVAL_MS,
+    log,
+    sleep = defaultSleep,
+  } = {},
+) {
+  const total = Math.max(1, attempts);
+  let last = {
+    outcome: PUBLISH_OUTCOME.PENDING,
+    status: null,
+    publishedAt: null,
+    failedReason: null,
+    attempts: 0,
+  };
+
+  for (let i = 0; i < total; i += 1) {
+    let project;
+    let readError;
+    try {
+      // eslint-disable-next-line no-await-in-loop
+      project = await transport.getProjectStatus(semrushWorkspaceId, projectId);
+    } catch (e) {
+      readError = e;
+      log?.warn?.('pollProjectPublished: status read failed', {
+        projectId, attempt: i + 1, error: e.message,
+      });
+    }
+
+    if (!readError) {
+      const status = readPublishStatus(project);
+      last = {
+        outcome: classifyPublishStatus(project),
+        status,
+        publishedAt: project?.published_at ?? project?.publishedAt ?? null,
+        failedReason: project?.publishing_failed_reason ?? project?.publishingFailedReason ?? null,
+        attempts: i + 1,
+      };
+      if (last.outcome !== PUBLISH_OUTCOME.PENDING) {
+        return last;
+      }
+    } else {
+      last = { ...last, attempts: i + 1, error: readError.message };
+    }
+
+    if (i < total - 1 && intervalMs > 0) {
+      // eslint-disable-next-line no-await-in-loop
+      await sleep(intervalMs);
+    }
+  }
+
+  return last;
+}

src/support/serenity/rest-transport.js

@@ -223,6 +223,25 @@ export function createSerenityTransport({ env, imsToken }) {
       return request('POST', url, imsToken, undefined);
     },
 
+    /**
+     * GET /v1/workspaces/{ws}/projects/{pid} — fetches a single project,
+     * including its `publish_status` attribute. Publish is asynchronous and
+     * Semrush emits no completion webhook, so publish completion is observed by
+     * re-reading this resource (see handlers/publish-status.js for the
+     * classify + poll helpers built on top of this).
+     *
+     * Uses the v1 DEFAULT view (no `live` query param) deliberately: the v2
+     * list and the v1 `live=true` view return a live-view materialisation that
+     * defaults the location and empties config for a never-published draft,
+     * whereas the v1 default view echoes the draft's real settings and
+     * `publish_status` faithfully (verified against the tenant, serenity-docs
+     * §10). Returns the raw project JSON.
+     */
+    async getProjectStatus(semrushWorkspaceId, projectId) {
+      const url = `${root}${API_PREFIX}/v1/workspaces/${enc(semrushWorkspaceId)}/projects/${enc(projectId)}`;
+      return request('GET', url, imsToken, undefined);
+    },
+
     /**
      * GET /v1/workspaces/{ws}/projects/{pid}/ai_models — list AI models
      * configured for a project. `model.key` is the value the Reporting API