feat(serenity): bump project-engine-client to 1.2.0 and document v1/v2 read drift

[rainer-friederich]

1. Abstract

Bumps @adobe/spacecat-shared-project-engine-client from 1.1.1 to 1.2.0 and lands two Serenity/Semrush implementation adjustments tracked in the running issue: documentation of the v1/v2 read-layer split, and a guard test for the model-edit republish contract.

2. Reasoning

1.2.0 is latest on npm and moves the Semrush aio/init_status route from /v1 to /v2, removing the /v1 route from the generated contract — so the transport must follow or it no longer type-checks. While in this code, two adjustments from the migration-readiness review (serenity-docs risk analysis) were closed: the v1/v2 read-drift that silently misreads an unpublished draft as empty/US, and locking in that a standalone model-set edit always republishes to the live layer.

3. High-level overview of the changes

• Client bump 1.1.1 → 1.2.0. The only behavioural consequence for us is getInitStatus, which now calls GET /v2/workspaces/{id}/projects/{id}/aio/init_status (the /v1 route was removed upstream). init_status is an AIO-readiness boolean, not draft settings, so reading it from v2's live-view carries no draft-faithfulness concern. The other 1.2.0 changes (several response fields tightened to required; addAiModel 200→201; createProjectTags response object→array) are inert here — those consumers discard the response body and the transport's unwrap accepts any response.ok.
• v1/v2 read-drift documentation (issue item 2). No code move — the only prompt read (listPromptsByTags) has no v1 variant, so it inherently reads the live (published) layer; an unpublished draft therefore reads empty (the "201-but-count-0" source). Added explaining comments on listPromptsByTags and listTagsForProject, and a new ADR recording which layer each Serenity read observes (v1 = draft settings, v2 prompts = live-only).
• Model-edit republish guard (issue item 1). Behaviour was already correct (the standalone PUT /serenity/models path defaults publish: true; only brand-create batches its own publish). Added a guard test pinning that a publish/publishMode flag smuggled into the request body cannot suppress the republish.

No customer-visible API shape change; the /serenity/* surface consumed by elmo is unchanged.

4. Required information

• Jira / issue: Serenity/Semrush: multiple adjustments — there will be more #2687
• Implementation plan: docs/specs/2026-06-15-serenity-subworkspace-dual-mode-implementation-plan.md (transport table row updated for the init_status v1→v2 move)
• ADR(s): docs/decisions/006-serenity-v1-v2-read-drift.md (new)

6. Additional information outside the code

• Diffed the published 1.1.1 vs 1.2.0 client paths types to scope the bump: confirmed aio/init_status is the only route that moved (v1 removed, v2 added) and that prompts remain v2-only in 1.2.0 (no v1 by_tags variant exists), which is why issue item 2 is documentation rather than a version swap.
• Verified the two 1.2.0 runtime response-shape changes are inert by reading every consumer: addAiModel (markets.js) and createProjectTags (markets-subworkspace.js) both discard the response body, and unwrap gates on response.ok rather than a literal 200.

7. Test plan

• (a) Ran the affected Serenity unit suites and the Serenity controller + OpenAPI-contract suites locally against the installed 1.2.0 client; the new model-edit guard test and the updated init_status assertion exercise the changed paths.
• (b) dev: for a live (published) subworkspace brand, call the market-detail read (GET /serenity/markets/:geoTargetId/:languageCode) which triggers getInitStatus, and confirm initialized still resolves (now served by the v2 route). No prod/stage-specific steps — the change is an internal upstream-contract follow + docs/tests.

8. Deployment & merge order

• feat(serenity): split publish out of create + publish-after-populate finalize (LLMO-5492) #2584 — related (not a hard dependency). Issue item 1 also asks to ensure that publish-split refactor preserves the live-edit republish; feat(serenity): split publish out of create + publish-after-populate finalize (LLMO-5492) #2584 is still open, so that confirmation remains open and should be re-checked when it lands.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[github-actions]

This PR will trigger a minor release when merged.

[MysticatBot]

Hey @rainer-friederich,

Verdict: Approve - well-scoped dependency bump with thorough documentation and a solid guard test.
Complexity: HIGH - medium diff; dependency bump with expanded transitive surface.
Changes: Bumps project-engine-client from 1.1.1 to 1.2.0, moves getInitStatus from /v1 to /v2 (route removed upstream), adds ADR-006 documenting the v1/v2 read-layer split, and pins the model-edit republish contract with a guard test (8 files).
Note: Recommend a human read before merge - this change amends an architectural decision record in docs/decisions/. The bot review is a complement to, not a replacement for, a human read here.

Non-blocking (3): minor issues and suggestions

• nit: ADR-006 table describes writes as "mixed" without enumerating which operations use v1 vs v2; a future developer adding a write has no guidance from this row - docs/decisions/006-serenity-v1-v2-read-drift.md:50
• nit: Lockfile top-level specifier records ^1.2.0 while package.json pins exact 1.2.0; functionally harmless (npm resolves from the lock entry) but would drift on a fresh install without the lockfile - package-lock.json:31
• suggestion: Consider a single canonical pointer comment at the top of rest-transport.js referencing ADR-006 for developers adding new endpoints who may not discover the per-method JSDoc - src/support/serenity/rest-transport.js:1

---

_{Skill: pr-review | Model: us.anthropic.claude-opus-4-6-v1[1m] | Duration: 14m 26s | Cost: $7.60 | Commit: 36960631ca88abb7382abe855a1449dba912fd62
If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[rainer-friederich]

Addressed all three non-blocking items from the MysticatBot review in bee2bd9f.

MysticatBot (non-blocking):

• nit: ADR-006 writes row says "mixed" without v1/v2 guidance — done. Reworked the row to per-op with a footnote: writes are out of this ADR's read-scope, the API version doesn't affect draft-faithfulness for a write (every mutation stages in draft regardless of v1/v2 and only goes live on publishProject), and the authoritative per-method write map lives in the transport JSDoc + the serenity v2-endpoint audit. A developer adding a write now has an explicit pointer.
• nit: lockfile records ^1.2.0 while package.json pins exact 1.2.0 — done. Pinned the top-level package-lock.json specifier to 1.2.0; npm install reconciles cleanly and leaves it exact.
• suggestion: add a canonical ADR-006 pointer at the top of rest-transport.js — done. Added a module-level comment steering anyone adding a read endpoint to ADR-006 before defaulting to v2, alongside the existing per-method JSDoc.

Also rebased onto the latest feat/2687 (which the pipeline had merged main into — picks up 1.602.1 + http-utils 1.31.0). type-check and lint clean.

Noted your callout that this amends an ADR and merits a human read — agreed; leaving that for the CODEOWNER.

[solaris007]

🎉 This PR is included in version 1.603.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀