Skip to content

feat(serenity): opt-in async provisioning for the 3 remaining skip-mode call sites (LLMO-7352/LLMO-7418 Phase 4) #3249

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
IrisAlexandrescu wants to merge 11 commits into
base: feat/LLMO-7418-async-provisioning-endpoints
Choose a base branch
from
Open

feat(serenity): opt-in async provisioning for the 3 remaining skip-mode call sites (LLMO-7352/LLMO-7418 Phase 4) #3249

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
75183d0
feat(serenity): opt-in async provisioning for the 3 remaining skip-mo…
Sep 9, 2026
837001d
fix(serenity): remove the unguarded, redundant status-write in activa…
Sep 9, 2026
fb236e6
fix(serenity): activate's async begin-sites reconcile stale attempts …
Sep 9, 2026
4ac1265
fix(serenity): activate's 2 skip-mode async branches pass a real sub-…
Sep 9, 2026
5d68170
fix(serenity): record the first-hop job id at the remaining 3 async p…
Sep 10, 2026
7ccf698
fix(serenity): fix 4 Medium external-review findings (async 202 shape…
Sep 10, 2026
badbe6e
fix(serenity): retry transient upstream/network errors during a works…
Sep 10, 2026
ea68ae4
fix(serenity): add a server-side kill switch for async provisioning (…
Sep 10, 2026
fe80d7d
feat(serenity): global async-provisioning master switch, default off …
Sep 10, 2026
35d4e02
test(serenity): pin the async master switch at all 6 gates, not just 1
Sep 10, 2026
b1c4843
fix(serenity): one spelling per async-provisioning 409, registered in…
Sep 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 8 additions & 7 deletions docs/openapi/brands-v2-api.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,13 +81,14 @@ v2-brands-for-org:
$ref: './schemas.yaml#/V2Brand'
'202':
description: |
PR-C (LLMO-7352/LLMO-7418): the request set `async: true` alongside
`semrushMarket`. The brand row is persisted immediately (visible,
The request set `async: true` (PR-C, LLMO-7352/LLMO-7418, alongside
`semrushMarket`; or Phase 4, same epic, on a bare create with no
market). The brand row is persisted immediately (visible,
non-active — "Setting up", no workspace pointer yet); the
sub-workspace ready-check and the initial market's project create/
publish are enqueued to a background job chain instead of running
inline. Poll the returned `jobId` at `GET .../serenity/jobs/{jobId}`
for status + result.
sub-workspace ready-check — and, when `semrushMarket` was supplied,
the initial market's project create/publish — are enqueued to a
background job chain instead of running inline. Poll the returned
`jobId` at `GET .../serenity/jobs/{jobId}` for status + result.
content:
application/json:
schema:
Expand Down Expand Up @@ -117,7 +118,7 @@ v2-brands-for-org:
organization (`code: brand_site_org_mismatch`).
- The brand's primary URL is already the primary URL (base site) of
another brand in this organization.
- (PR-C, `async: true` only) a provisioning attempt is already in flight
- (`async: true` only) a provisioning attempt is already in flight
for this brand (`error: semrushProvisioningInProgress`).
headers:
X-Error:
Expand Down
50 changes: 30 additions & 20 deletions docs/openapi/schemas.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8101,17 +8101,21 @@ V2BrandInput:
type: boolean
default: false
description: >
PR-C (LLMO-7352/LLMO-7418). Only meaningful when `semrushMarket` is
supplied. When true, the brand row is persisted first (visible,
non-active — "Setting up"), then the sub-workspace ready-check and the
initial market's project create/publish are enqueued to a background
job chain instead of running inline, and the endpoint returns 202 with
a job id to poll via `GET .../serenity/jobs/{jobId}`. Omitted/false
processes synchronously as today (still 201) — this is opt-in only and
not yet the default. Unlike `SerenityCreatePromptsRequest`'s `async`
PR-C (LLMO-7352/LLMO-7418), extended by Phase 4 (LLMO-6405 "B"). Meaningful on
either of this endpoint's two Semrush-provisioning creates: with `semrushMarket`
supplied (sub-workspace ready-check + initial market's project create/publish,
enqueued as a job chain), or without it, for a sub-workspace-only active create
anchored by `baseSiteId` (sub-workspace create/adopt only, no project). In both
cases, true persists the brand row first (visible, non-active — "Setting up")
and returns 202 with a job id to poll via `GET .../serenity/jobs/{jobId}`.
Ignored (no error, brand created synchronously) when the organization is not
serenity-active (a flat/brandalf org) or the brand is created `pending` (a
pending brand always defers ALL Semrush provisioning regardless of this flag).
Omitted/false processes synchronously as today (still 201) — this is opt-in
only and not yet the default. Unlike `SerenityCreatePromptsRequest`'s `async`
flag, this one is not intended to be a permanent dual-mode feature: the
synchronous path is the LLMO-7352 bug pattern itself, and is expected
to be retired once known callers have migrated to `async: true`.
synchronous path is the LLMO-7352 bug pattern itself, and is expected to be
retired once known callers have migrated to `async: true`.

V2BrandUpdateInput:
type: object
Expand Down Expand Up @@ -12676,12 +12680,15 @@ SerenityActivateRequest:
type: boolean
default: false
description: >
PR-C (LLMO-7352/LLMO-7418). Only meaningful on the already-active-brand,
markets-supplied path — a pending or bare-reactivation activation always
stays synchronous regardless of this flag. When true, the sub-workspace
ready-check and the per-market project create/publish + site-link + active
flip are enqueued to a background job chain instead of running inline, and
the endpoint returns 202 with a job id to poll via
PR-C (LLMO-7352/LLMO-7418), extended by Phase 4. Meaningful on all three
activation shapes this endpoint supports: the already-active-brand,
markets-supplied path (sub-workspace ready-check + per-market project
create/publish + site-link + active flip, enqueued as a job chain); the
pending→active activation (sub-workspace create/adopt only, enqueued as
`provision-workspace-job` -> `activate-brand-workspace-job`); and bare
reactivation of an already-active, pointer-less brand (same chain). In
every case, true enqueues the work to a background job chain instead of
running inline, and the endpoint returns 202 with a job id to poll via
`GET .../serenity/jobs/{jobId}`. Omitted/false processes synchronously as
today — this is opt-in only and not yet the default.

Expand Down Expand Up @@ -12818,12 +12825,15 @@ SerenityCreateMarketRequest:
type: boolean
default: false
description: >
PR-C (LLMO-7352/LLMO-7418). When true (sub-workspace-mode brands only),
the sub-workspace-ready check and the project create/publish are
PR-C (LLMO-7352/LLMO-7418). When true, and only for a sub-workspace-mode
brand, the sub-workspace-ready check and the project create/publish are
enqueued to a background job chain instead of running inline, and the
endpoint returns 202 with a job id to poll via
`GET .../serenity/jobs/{jobId}`. Omitted/false processes synchronously
as today — this is opt-in only and not yet the default. Unlike
`GET .../serenity/jobs/{jobId}`. Ignored (no error, market created
synchronously) for a flat-mode brand — flat mode has no sub-workspace
readiness to await, so there is nothing to defer. Omitted/false
processes synchronously as today — this is opt-in only and not yet the
default. Unlike
`SerenityCreatePromptsRequest`'s `async` flag, this one is not intended
to be a permanent dual-mode feature: the synchronous path is the
LLMO-7352 bug pattern itself, and is expected to be retired once known
Expand Down
51 changes: 31 additions & 20 deletions docs/openapi/serenity-api.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -612,7 +612,14 @@ v2-serenity-markets:
'404':
description: Organization has no workspace, or serenity is not active for the organization.
'409':
description: A market already exists for this (brandId, geoTargetId, languageCode) slice, or (async only) a provisioning attempt is already in flight for this brand.
description: >-
One of three conflicts, distinguished by the `error` token: (a) a market already exists
for this (brandId, geoTargetId, languageCode) slice; (b) `semrushProvisioningInProgress`
(`async: true` only) — a provisioning attempt is already in flight for this brand, so
retry shortly; or (c) `semrushProvisioningIncomplete` — the brand's Semrush sub-workspace
is pending or has failed to provision, so it has no workspace of its own to add a market
in. (b) converges on retry; (c) does not, and needs the brand's provisioning to complete
first.
'502':
description: Upstream returned a non-2xx response.
content:
Expand Down Expand Up @@ -1203,12 +1210,12 @@ v2-serenity-activate:
intact; retry converges idempotently). An already-active brand re-supplying
markets is never downgraded (a partial failure is reported as 207).

PR-C (LLMO-7352/LLMO-7418): when a primary URL/domain and markets are
present (the branch described above — NOT the sub-workspace-only pending
or bare-reactivation paths, which always stay synchronous), the caller may
set `async: true` to enqueue the whole batch to a background job chain
instead of running it inline; see the `202` response. Absent/false runs
synchronously as described above — this is opt-in only and not yet the
LLMO-7352/LLMO-7418: the caller may set `async: true` on ANY of the 3
branches — project activation (PR-C), the sub-workspace-only
pending→active flip, and bare reactivation (both Phase 4) — to enqueue
that branch's work to a background job chain instead of running it
inline; see the `202` response. Absent/false runs synchronously as
described above on every branch — this is opt-in only and not yet the
default.
operationId: activateSerenityBrand
security:
Expand All @@ -1226,17 +1233,20 @@ v2-serenity-activate:
schema: { $ref: './schemas.yaml#/SerenityActivateResponse' }
'202':
description: |
PR-C (LLMO-7352/LLMO-7418): the request set `async: true` on the
project-activation branch (primary URL + markets present). The whole
batch (sub-workspace ready-check, every market's project create/
publish, the site link, and the active flip) is enqueued to a
background job chain instead of running inline. Poll the returned
`jobId` at `GET .../serenity/jobs/{jobId}` for status + result — the
polling endpoint transparently follows the job chain to its
EFFECTIVE terminal hop, so `status` only reports `COMPLETED` once
the actual batch has run, not merely once the sub-workspace became
ready; on COMPLETED, `result` is the same body a synchronous
`200`/`207` would have returned.
The request set `async: true`. On the project-activation branch
(primary URL + markets present — PR-C), the whole batch
(sub-workspace ready-check, every market's project create/publish,
the site link, and the active flip) is enqueued to a background job
chain. On the sub-workspace-only pending→active or bare-reactivation
branches (Phase 4), only the sub-workspace ready-check + the status
flip are enqueued — there is no project/market work on those
branches. Either way, poll the returned `jobId` at
`GET .../serenity/jobs/{jobId}` for status + result — the polling
endpoint transparently follows the job chain to its EFFECTIVE
terminal hop, so `status` only reports `COMPLETED` once the actual
batch (or status flip) has run, not merely once the sub-workspace
became ready; on COMPLETED, `result` is the same body the branch's
own synchronous `200`/`207`/`502` would have returned.
content:
application/json:
schema: { $ref: './schemas.yaml#/SerenityPromptsJobAccepted' }
Expand All @@ -1258,8 +1268,9 @@ v2-serenity-activate:
outcomes — the operator must choose a different primary URL; (b)
misconfiguration: the brand's sub-workspace equals the organization parent
workspace (refused to avoid acting on the shared parent pool); or (c)
(PR-C, `async: true` only) a provisioning attempt is already in flight for
this brand (`error: semrush_provisioning_in_progress`) — retry shortly.
(`async: true` only, any branch) a provisioning attempt is already in
flight for this brand (`error: semrushProvisioningInProgress`) —
retry shortly.
content:
application/json:
schema:
Expand Down
Loading
Loading