feat(serenity): expose semrush provisioning status on brand reads (LLMO-7352/LLMO-7418)

Surfaces brands.semrush_provisioning_status/semrush_provisioning_error as
read-only fields (semrushProvisioningStatus/semrushProvisioningError) on the
V2 Brand DTO. These columns previously existed only for the async
provisioning worker's own internal CAS bookkeeping (getBrandProvisioningState's
narrow PROVISIONING_SELECT) -- no GET response exposed them, so a client had
no way to show a persistent provisioning-status indicator without relying on
an `async: true` create/activate response's one-shot jobId.

mapDbBrandToV2 is the single mapping point for all 3 GET paths
(listBrandsForOrg/getBrandForOrg/getBrandForOrgSite) and the create/update
write-response paths (all route through withSerenityState, which just spreads
whatever the mapper produced) -- fixing it there propagates everywhere for
free, no SELECT/query changes needed since PostgREST's `'*'` already returns
every brands column.

Prerequisite for the frontend UI-states work (LLMO-7419): a persistent
Setting-up/Ready/Setup-failed indicator on the brand list/detail views can't
exist without a backend field to read it from.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: Iris Alexandrescu

docs/openapi/schemas.yaml

@@ -7920,6 +7920,27 @@ V2Brand:
       description: >-
         Read-only deferred Semrush provisioning data for a pending (draft)
         brand. Null for a non-pending brand. See V2PendingSemrushProvisioning.
+    semrushProvisioningStatus:
+      type:
+        - string
+        - 'null'
+      enum: [pending, ready, failed, null]
+      readOnly: true
+      description: >-
+        Read-only (LLMO-7352/LLMO-7418): the brand's async Semrush
+        provisioning state, so the caller can show a persistent Setting-up/
+        Ready/Setup-failed indicator without relying on an `async: true`
+        create/activate response's one-shot `jobId`. Null for a brand that
+        has never gone through an async provisioning attempt.
+    semrushProvisioningError:
+      type:
+        - string
+        - 'null'
+      readOnly: true
+      description: >-
+        Read-only (LLMO-7352/LLMO-7418): the failure detail recorded on the
+        last failed provisioning attempt. Null unless
+        `semrushProvisioningStatus` is `failed`.
     updatedAt:
       $ref: '#/DateTime'
     updatedBy:

src/support/brands-storage.js

@@ -312,6 +312,18 @@ function mapDbBrandToV2(row) {
     // sub-workspace minted yet). Consumers use it to scope per-brand Semrush
     // views to the sub-workspace.
     semrushSubWorkspaceId: row.semrush_sub_workspace_id || null,
+    // Read-only (LLMO-7352/LLMO-7418): the brand's async Semrush provisioning state — the
+    // same CAS state the provisioning worker itself reads/writes (see
+    // beginProvisioningAttempt/promoteProvisioningReady/promoteProvisioningFailed below), now
+    // surfaced to a normal GET so the frontend can show a persistent Setting-up/Ready/Setup-
+    // failed indicator instead of relying on the one-shot `jobId` an `async: true` create/
+    // activate response carries. Null for a brand that has never gone through an async
+    // provisioning attempt (every brand created before this column existed, and every
+    // synchronous create/activate).
+    semrushProvisioningStatus: row.semrush_provisioning_status || null,
+    // Read-only (LLMO-7352/LLMO-7418): the failure detail recorded on the LAST failed
+    // provisioning attempt. Null unless semrushProvisioningStatus is 'failed'.
+    semrushProvisioningError: row.semrush_provisioning_error || null,
     // Read-only: deferred Semrush provisioning data for a pending (draft) brand
     // (serenity dual-mode). Object { primaryUrl, markets: [{ market,
     // languageCode }] } the wizard collected before provisioning; null once

test/support/brands-storage.test.js

@@ -412,6 +412,34 @@ describe('brands-storage', () => {
       expect(flatResult.pendingSemrushProvisioning).to.equal(null);
     });
 
+    it('maps semrush_provisioning_status/error to semrushProvisioningStatus/Error, null when absent (LLMO-7352/LLMO-7418)', async () => {
+      const failedRow = makeBrandRow({
+        semrush_provisioning_status: 'failed',
+        semrush_provisioning_error: 'Semrush sub-workspace provisioning failed and cannot be recovered automatically.',
+      });
+      const failedQuery = createChainableQuery({ data: failedRow, error: null });
+      const failedResult = await getBrandById(
+        ORG_ID,
+        BRAND_ID,
+        { from: sinon.stub().returns(failedQuery) },
+      );
+      expect(failedResult.semrushProvisioningStatus).to.equal('failed');
+      expect(failedResult.semrushProvisioningError).to.equal(
+        'Semrush sub-workspace provisioning failed and cannot be recovered automatically.',
+      );
+
+      // A brand that has never gone through an async provisioning attempt (every brand
+      // created before these columns existed, and every synchronous create/activate).
+      const flatQuery = createChainableQuery({ data: makeBrandRow(), error: null });
+      const flatResult = await getBrandById(
+        ORG_ID,
+        BRAND_ID,
+        { from: sinon.stub().returns(flatQuery) },
+      );
+      expect(flatResult.semrushProvisioningStatus).to.equal(null);
+      expect(flatResult.semrushProvisioningError).to.equal(null);
+    });
+
     it('defaults to empty regions when competitor regions is missing', async () => {
       const dbRow = makeBrandRow({
         competitors: [{ name: 'Rival', url: null }], // no regions key — triggers || []