feat(data-access): status transition guard + deriveSuggestionStatus (SITES-47091)

[alinarublea]

What & why (SITES-47091)

Adds the JS-side enforcement primitives for the Suggestion ↔ FixEntity status lifecycle defined in ADR adobe/mysticat-architecture#174. Today spacecat-shared validates status only as a closed enum — any value from any value, no state machine. This PR adds the transition table + guard + the shared bubble-up function, shipped warn-only by default.

Changes (spacecat-shared-data-access only)

• Transition tables + predicates — fix-entity.transitions.js (canonical FixEntity table from the ADR), suggestion.transitions.js (intentionally V1-permissive; the warn logs inform tightening before enforce).
• util/status-transition-guard.js — getEnforcementMode() reads STATUS_TRANSITION_ENFORCEMENT ∈ off | warn | enforce, default warn. guardTransition(): allowed/no-op → pass; warn → log violation (Entity id from -> to) and proceed; enforce → throw ValidationError; off → skip.
• setStatus override + transitionStatus alias on FixEntity and Suggestion models — a model-defined setStatus blocks the auto-generated setter (base.model.js:128), so this is a single chokepoint capturing every JS writer (api-service single PATCH, bulkUpdateStatus, autofix-worker). Default warn is byte-equivalent to the old setter (isReference was always false for status).
• deriveSuggestionStatus — the non-CWV 1:1 bubble-up only (DEPLOYED/PUBLISHED→FIXED, FAILED→ERROR, PENDING→IN_PROGRESS, ROLLED_BACK→SKIPPED; severity collapse for >1 fix).
• Barrel + .d.ts exports.

Rollout / behavior

Default warn ⇒ zero behavior change on consumer bump. Consumers adopt and observe violation logs, then flip to enforce — tracked in SITES-47286. This guard covers only the two JS writers; mystique (Python direct-DB) bypasses it and needs a separate guard later.

Deferred (agreed, split out)

The CWV multi-issue bubble-up is deferred to SITES-47285: the ADR's per-issue vocabulary (cwvIssueStatus = PATCH_*/GUIDANCE_GENERATED) exists only in mystique, written into the overloaded per-issue status field via direct-DB, while the JS ISSUE_STATUSES enum lists only the Suggestion vocabulary. deriveSuggestionStatus throws if a non-empty issues[] is passed until that's reconciled. FixEntity.REJECTED is likewise omitted (not in the enum yet).

Tests

2441 data-access tests pass; all new files at 100% coverage; lint clean.

Tracking: SITES-47091 · parent SITES-47076 · follow-ups SITES-47285, SITES-47286.

🤖 Generated with Claude Code

[github-actions]

This PR will trigger a minor release when merged.

[MysticatBot]

Hey @alinarublea,

Verdict: Approve - well-designed state machine guard with a safe warn-only rollout strategy.
Complexity: HIGH - large diff (977 lines, 16 files).
Changes: Adds status transition tables, a tri-mode enforcement guard, setStatus overrides on FixEntity and Suggestion models, and deriveSuggestionStatus bubble-up function (16 files).

Non-blocking (3): minor issues and suggestions

• nit: Duplicate status constants across fix-entity.transitions.js, suggestion.transitions.js, and derive-status.js create a sync hazard when the enum grows - packages/spacecat-shared-data-access/src/models/fix-entity/fix-entity.transitions.js:17. The circular-import rationale is sound, but consider extracting to a leaf constants module before flipping to enforce mode.
• suggestion: transitionStatus(to) is a pure pass-through to setStatus with no distinct behavior or documented guidance on when to prefer it - packages/spacecat-shared-data-access/src/models/fix-entity/fix-entity.model.js:63. Either document the intended semantic split or defer the alias until behavior diverges.
• suggestion: deriveSuggestionStatus silently returns null when a fix entry is null/undefined or has an unrecognized status. Consider adding a test pinning this edge-case behavior (e.g. deriveSuggestionStatus([null]) returns null) so the contract is explicit - packages/spacecat-shared-data-access/src/models/suggestion/derive-status.js:90.

---

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