@adobe/spacecat-shared-data-access 4.2.0 → 4.3.1

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [@adobe/spacecat-shared-data-access-v4.3.1](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v4.3.0...@adobe/spacecat-shared-data-access-v4.3.1) (2026-07-09)
+
+### Bug Fixes
+
+* **ticket-suggestion:** use createdAt as belongs_to sort key instead of updatedAt ([#1798](https://github.com/adobe/spacecat-shared/issues/1798)) ([711eecd](https://github.com/adobe/spacecat-shared/commit/711eecdc187ec9a21a79dedca808e6622bd18933)), closes [#2661](https://github.com/adobe/spacecat-shared/issues/2661)
+
+## [@adobe/spacecat-shared-data-access-v4.3.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v4.2.0...@adobe/spacecat-shared-data-access-v4.3.0) (2026-07-09)
+
+### Features
+
+* **data-access:** status transition guard + deriveSuggestionStatus (SITES-47091) ([#1748](https://github.com/adobe/spacecat-shared/issues/1748)) ([0888866](https://github.com/adobe/spacecat-shared/commit/0888866df45778a8e28a86ce2b11c721b81cf0c0))
+
 ## [@adobe/spacecat-shared-data-access-v4.2.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v4.1.1...@adobe/spacecat-shared-data-access-v4.2.0) (2026-07-07)
 
 ### Features

package/CLAUDE.md

@@ -213,6 +213,38 @@ const liveSites = await dataAccess.Site.all(
 | `POSTGREST_API_KEY` | No | JWT for `postgrest_writer` role (enables UPDATE/DELETE) |
 | `S3_CONFIG_BUCKET` | No | Only for `Configuration` entity |
 | `AWS_REGION` | No | Only for `Configuration` entity |
+| `STATUS_TRANSITION_ENFORCEMENT` | No | Status-transition guard mode: `off` \| `warn` \| `enforce`. Default `warn`. See "Status Transition Lifecycle". |
+
+## Status Transition Lifecycle (SITES-47091)
+
+`Suggestion.status` and `FixEntity.status` are governed by a transition guard
+(canonical design: ADR [adobe/mysticat-architecture#174]). The guard runs on the
+`setStatus` override of both models — so **every** writer (api-service single
+PATCH, `SuggestionCollection.bulkUpdateStatus`, autofix-worker) is checked at one
+chokepoint.
+
+**Enforcement is env-controlled** via `STATUS_TRANSITION_ENFORCEMENT`, read at call time:
+
+| Mode | Behavior |
+|------|----------|
+| `off` | no check |
+| `warn` (**default**) | logs a violation (`<Entity> <id> <from> -> <to>`) and **still applies** the change — byte-equivalent to the old setter |
+| `enforce` | throws `ValidationError` on a disallowed transition |
+
+Rollout intent: ship `warn` to surface today's illegal transitions in logs for
+~1–2 weeks, then flip to `enforce`. A no-op (`from === to`) always passes.
+
+**APIs** (exported from the package root):
+- `setStatus(value)` / `transitionStatus(to)` on `Suggestion` and `FixEntity` — both guard the transition; `transitionStatus` is the intention-revealing alias for new code.
+- `isAllowedFixTransition(from, to)` / `isAllowedSuggestionTransition(from, to)` + the `FIX_ENTITY_TRANSITIONS` / `SUGGESTION_TRANSITIONS` tables (a null/undefined `from` means entity creation).
+- `deriveSuggestionStatus(fixes, issues = [])` — derives a Suggestion status from its fix entities. **Implements the non-CWV 1:1 bubble-up only** (`DEPLOYED`/`PUBLISHED`→`FIXED`, `FAILED`→`ERROR`, `PENDING`→`IN_PROGRESS`, `ROLLED_BACK`→`SKIPPED`; severity-collapses for >1 fix). **Throws** if a non-empty `issues` array is passed — the CWV multi-issue bubble-up is deferred (SITES-47285), because the per-issue codefix vocabulary (`PATCH_*`/`GUIDANCE_GENERATED`, written by mystique into the overloaded `issue.status` field) is not yet reconciled with the JS `ISSUE_STATUSES` enum.
+
+Notes: the `FixEntity` table is the canonical one from the ADR; the `Suggestion`
+table is intentionally **permissive in V1** (tune it from the warn-log findings
+before enforcing). `FixEntity.REJECTED` is omitted (not in `FixEntity.STATUSES`).
+Consumer adoption (bump + route writes + warn→enforce) is tracked in SITES-47286.
+
+[adobe/mysticat-architecture#174]: https://github.com/adobe/mysticat-architecture/blob/main/platform/decisions/design-suggestion-fix-entity-status-lifecycle.md
 
 ## Site Config: Import Types
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/spacecat-shared-data-access",
-  "version": "4.2.0",
+  "version": "4.3.1",
   "description": "Shared modules of the Spacecat Services - Data Access",
   "type": "module",
   "engines": {

package/src/models/fix-entity/fix-entity.model.js

@@ -10,6 +10,8 @@
  * governing permissions and limitations under the License.
  */
 import BaseModel from '../base/base.model.js';
+import { guardTransition } from '../../util/status-transition-guard.js';
+import { isAllowedFixTransition } from './fix-entity.transitions.js';
 
 /**
  * FixEntity - A class representing a FixEntity for a Suggestion.
@@ -39,6 +41,40 @@ class FixEntity extends BaseModel {
     REPORTING: 'reporting',
   };
 
+  /**
+   * Sets the fix status, guarding the transition against the canonical table
+   * (fix-entity.transitions.js). Overrides the auto-generated setter so EVERY
+   * writer is checked at one chokepoint. Behavior is governed by
+   * STATUS_TRANSITION_ENFORCEMENT (default `warn` — logs violations, still
+   * applies; `enforce` — throws ValidationError; `off` — no check).
+   *
+   * @param {string} value - target status
+   * @returns {this}
+   */
+  setStatus(value) {
+    guardTransition({
+      entityName: FixEntity.ENTITY_NAME,
+      entityId: this.getId(),
+      from: this.getStatus(),
+      to: value,
+      isAllowed: isAllowedFixTransition,
+      log: this.log,
+    });
+    this.patcher.patchValue('status', value, false);
+    return this;
+  }
+
+  /**
+   * Explicit, intention-revealing alias for setStatus for new callers that want
+   * to signal a guarded lifecycle transition. Same behavior as setStatus.
+   *
+   * @param {string} to - target status
+   * @returns {this}
+   */
+  transitionStatus(to) {
+    return this.setStatus(to);
+  }
+
   async getSuggestions() {
     const fixEntityCollection = this.entityRegistry.getCollection('FixEntityCollection');
     return fixEntityCollection

package/src/models/fix-entity/fix-entity.transitions.js

@@ -0,0 +1,65 @@
+/*
+ * Copyright 2025 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.
+ */
+/**
+ * FixEntity status literals.
+ *
+ * Duplicated from `FixEntity.STATUSES` (fix-entity.model.js) to avoid a circular
+ * import — fix-entity.model.js imports this module for its setStatus guard.
+ * Keep in sync if the enum ever changes. (Same pattern as suggestion.data-schemas.js.)
+ */
+const STATUSES = {
+  PENDING: 'PENDING',
+  DEPLOYED: 'DEPLOYED',
+  PUBLISHED: 'PUBLISHED',
+  FAILED: 'FAILED',
+  ROLLED_BACK: 'ROLLED_BACK',
+};
+
+/**
+ * Canonical FixEntity status transition table.
+ *
+ * Source of truth: ADR adobe/mysticat-architecture#174
+ * (platform/decisions/design-suggestion-fix-entity-status-lifecycle.md, §"Proposed rollout").
+ *
+ * The `<create>` case (no prior status) is represented by the CREATE key and is
+ * matched when `from` is null/undefined.
+ *
+ * NOTE: the ADR table also lists a `REJECTED` terminal fix status, but
+ * `FixEntity.STATUSES` does not (yet) define REJECTED. It is intentionally
+ * omitted here until the enum + the post-merge/publish detector that would set
+ * it exist (tracked under SITES-47076).
+ */
+export const FIX_ENTITY_CREATE = Symbol('FIX_ENTITY_CREATE');
+
+export const FIX_ENTITY_TRANSITIONS = {
+  [FIX_ENTITY_CREATE]: [STATUSES.PENDING, STATUSES.DEPLOYED, STATUSES.FAILED],
+  [STATUSES.PENDING]: [STATUSES.DEPLOYED, STATUSES.FAILED],
+  [STATUSES.DEPLOYED]: [STATUSES.PUBLISHED, STATUSES.ROLLED_BACK],
+  // bounded retry; the attempts cap (SITES-46548) is not enforced here.
+  [STATUSES.FAILED]: [STATUSES.PENDING],
+  [STATUSES.PUBLISHED]: [STATUSES.ROLLED_BACK],
+  [STATUSES.ROLLED_BACK]: [], // terminal
+};
+
+/**
+ * Returns true if the FixEntity status transition `from` -> `to` is allowed.
+ * A null/undefined `from` is treated as entity creation.
+ *
+ * @param {string|null|undefined} from - current status (null/undefined => create)
+ * @param {string} to - target status
+ * @returns {boolean}
+ */
+export const isAllowedFixTransition = (from, to) => {
+  const key = (from === null || from === undefined) ? FIX_ENTITY_CREATE : from;
+  const allowed = FIX_ENTITY_TRANSITIONS[key];
+  return Array.isArray(allowed) && allowed.includes(to);
+};

package/src/models/fix-entity/index.d.ts

@@ -30,6 +30,7 @@ export interface FixEntity extends BaseModel {
   setPublishedAt(value: string): this;
   getStatus(): string;
   setStatus(value: string): this;
+  transitionStatus(to: string): this;
   getType(): string;
 }
 
@@ -43,3 +44,11 @@ export interface FixEntityCollection extends BaseCollection<FixEntity> {
   getAllFixesWithSuggestionByCreatedAt(opportunityId: string, fixEntityCreatedDate: string): Promise<Array<{fixEntity: FixEntity, suggestions: Array<Suggestion>}>>;
   getAllFixesWithSuggestionsByOpportunityId(opportunityId: string): Promise<Array<{fixEntity: FixEntity, suggestions: Array<Suggestion>}>>;
 }
+
+// Canonical FixEntity status transition table + predicate (SITES-47091).
+export declare const FIX_ENTITY_CREATE: unique symbol;
+export declare const FIX_ENTITY_TRANSITIONS: Record<string | symbol, string[]>;
+export declare function isAllowedFixTransition(
+  from: string | null | undefined,
+  to: string,
+): boolean;

package/src/models/fix-entity/index.js

@@ -17,3 +17,10 @@ export {
   FixEntity,
   FixEntityCollection,
 };
+
+// Canonical FixEntity status transition table + predicate (SITES-47091).
+export {
+  FIX_ENTITY_TRANSITIONS,
+  FIX_ENTITY_CREATE,
+  isAllowedFixTransition,
+} from './fix-entity.transitions.js';

package/src/models/suggestion/derive-status.js

@@ -0,0 +1,112 @@
+/*
+ * Copyright 2025 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.
+ */
+
+/**
+ * Suggestion + FixEntity status literals.
+ *
+ * Duplicated from the model enums to keep this a dependency-light pure module.
+ * Keep in sync if either enum changes. (Same pattern as suggestion.data-schemas.js.)
+ */
+const SUGGESTION = {
+  NEW: 'NEW',
+  IN_PROGRESS: 'IN_PROGRESS',
+  SKIPPED: 'SKIPPED',
+  FIXED: 'FIXED',
+  ERROR: 'ERROR',
+};
+
+const FIX = {
+  PENDING: 'PENDING',
+  DEPLOYED: 'DEPLOYED',
+  PUBLISHED: 'PUBLISHED',
+  FAILED: 'FAILED',
+  ROLLED_BACK: 'ROLLED_BACK',
+};
+
+/**
+ * Normalizes a fix entry to its status string. Accepts a FixEntity model
+ * instance (`getStatus()`), a plain `{ status }` object, or a status string.
+ */
+const toStatus = (fix) => {
+  if (typeof fix === 'string') {
+    return fix;
+  }
+  if (fix && typeof fix.getStatus === 'function') {
+    return fix.getStatus();
+  }
+  return fix?.status;
+};
+
+/**
+ * Derives a Suggestion's status from its fix entities — the **non-CWV (1:1)**
+ * bubble-up from ADR adobe/mysticat-architecture#174 §"Bubble-up rule (non-CWV
+ * opportunities)":
+ *
+ *   FAILED      -> ERROR
+ *   PENDING     -> IN_PROGRESS
+ *   DEPLOYED    -> FIXED
+ *   PUBLISHED   -> FIXED
+ *   ROLLED_BACK -> SKIPPED
+ *
+ * For a single fix this is exactly the ADR map. For multiple fixes it collapses
+ * by severity (ERROR > IN_PROGRESS > FIXED > SKIPPED) so partial failure wins —
+ * consistent with the CWV severity ordering. `Fix.REJECTED` is intentionally
+ * absent: it is not in `FixEntity.STATUSES` (see SITES-47076).
+ *
+ * The **CWV multi-issue** bubble-up is deliberately NOT implemented here: the
+ * ADR's per-issue vocabulary (`cwvIssueStatus` = PATCH_GENERATED / GUIDANCE_*
+ * / PATCH_FAILED_*) does not match the data layer (mystique writes those into
+ * the overloaded per-issue `status` field; the JS `ISSUE_STATUSES` enum lists
+ * only Suggestion statuses). Reconciling that is a follow-up sub-task,
+ * SITES-47285. Passing a non-empty `issues` argument throws to prevent a caller
+ * from silently receiving an unimplemented CWV result.
+ *
+ * @param {Array<object|string>} fixes - fix entities / `{status}` / status strings
+ * @param {Array<object>} [issues] - CWV per-issue data; MUST be empty for now
+ * @param {string|null} [currentStatus] - the Suggestion's current status, returned as the
+ *   fallback when nothing is derivable (no fixes / all-null / no matching rule) so a derive
+ *   call never clobbers a status set elsewhere. Defaults to null (prior behavior).
+ * @returns {string|null} derived Suggestion status, or `currentStatus` when nothing is derivable
+ * @throws {Error} if a non-empty `issues` array is supplied (CWV deferred)
+ */
+export const deriveSuggestionStatus = (fixes, issues = [], currentStatus = null) => {
+  if (Array.isArray(issues) && issues.length > 0) {
+    throw new Error('deriveSuggestionStatus: CWV multi-issue bubble-up is not yet implemented (deferred to SITES-47285)');
+  }
+
+  if (!Array.isArray(fixes) || fixes.length === 0) {
+    return currentStatus;
+  }
+
+  // Drop null/undefined entries (e.g. a sparse junction result) so one malformed
+  // entry cannot nullify an otherwise well-defined derivation; degrades to the
+  // same "no fixes" behavior as an empty array.
+  const statuses = fixes.map(toStatus).filter((s) => s != null);
+  if (statuses.length === 0) {
+    return currentStatus;
+  }
+
+  if (statuses.includes(FIX.FAILED)) {
+    return SUGGESTION.ERROR;
+  }
+  if (statuses.includes(FIX.PENDING)) {
+    return SUGGESTION.IN_PROGRESS;
+  }
+  if (statuses.includes(FIX.DEPLOYED) || statuses.includes(FIX.PUBLISHED)) {
+    return SUGGESTION.FIXED;
+  }
+  if (statuses.every((s) => s === FIX.ROLLED_BACK)) {
+    return SUGGESTION.SKIPPED;
+  }
+
+  return currentStatus;
+};

package/src/models/suggestion/index.d.ts

@@ -25,6 +25,7 @@ export interface Suggestion extends BaseModel {
   setOpportunityId(opportunityId: string): Suggestion;
   setRank(rank: number): Suggestion;
   setStatus(status: string): Suggestion;
+  transitionStatus(to: string): Suggestion;
 }
 
 export interface SuggestionCollection extends BaseCollection<Suggestion> {
@@ -35,3 +36,15 @@ export interface SuggestionCollection extends BaseCollection<Suggestion> {
   findByOpportunityIdAndStatus(opportunityId: string, status: string, options?: QueryOptions): Promise<Suggestion | null>;
   getFixEntitiesBySuggestionId(suggestionId: string): Promise<{data: Array<FixEntity>, unprocessed: Array<string>}>;
 }
+
+// Status transition table + predicate, and the 1:1 bubble-up (SITES-47091).
+export declare const SUGGESTION_CREATE: unique symbol;
+export declare const SUGGESTION_TRANSITIONS: Record<string | symbol, string[]>;
+export declare function isAllowedSuggestionTransition(
+  from: string | null | undefined,
+  to: string,
+): boolean;
+export declare function deriveSuggestionStatus(
+  fixes: Array<FixEntity | { status?: string } | string>,
+  issues?: Array<object>,
+): string | null;

package/src/models/suggestion/index.js

@@ -28,3 +28,12 @@ export {
   ISSUE_STATUSES,
   ISSUE_SKIP_REASONS,
 } from './suggestion.data-schemas.js';
+
+// Suggestion status transition table + predicate, and the 1:1 bubble-up
+// (SITES-47091). CWV multi-issue bubble-up deferred (see derive-status.js).
+export {
+  SUGGESTION_TRANSITIONS,
+  SUGGESTION_CREATE,
+  isAllowedSuggestionTransition,
+} from './suggestion.transitions.js';
+export { deriveSuggestionStatus } from './derive-status.js';

package/src/models/suggestion/suggestion.model.js

@@ -13,6 +13,8 @@
 import BaseModel from '../base/base.model.js';
 import { DATA_SCHEMAS } from './suggestion.data-schemas.js';
 import { FIELD_TRANSFORMERS, FALLBACK_PROJECTION } from './suggestion.projection-utils.js';
+import { guardTransition } from '../../util/status-transition-guard.js';
+import { isAllowedSuggestionTransition } from './suggestion.transitions.js';
 
 /**
  * Suggestion - A class representing a Suggestion entity.
@@ -120,6 +122,40 @@ class Suggestion extends BaseModel {
     }
   }
 
+  /**
+   * Sets the suggestion status, guarding the transition against the (V1
+   * permissive) table in suggestion.transitions.js. Overrides the auto-generated
+   * setter so every writer — single PATCH, bulkUpdateStatus, autofix-worker —
+   * is checked at one chokepoint. Behavior is governed by
+   * STATUS_TRANSITION_ENFORCEMENT (default `warn`; `enforce` throws; `off` skips).
+   *
+   * @param {string} value - target status
+   * @returns {this}
+   */
+  setStatus(value) {
+    guardTransition({
+      entityName: Suggestion.ENTITY_NAME,
+      entityId: this.getId(),
+      from: this.getStatus(),
+      to: value,
+      isAllowed: isAllowedSuggestionTransition,
+      log: this.log,
+    });
+    this.patcher.patchValue('status', value, false);
+    return this;
+  }
+
+  /**
+   * Explicit, intention-revealing alias for setStatus for new callers that want
+   * to signal a guarded lifecycle transition. Same behavior as setStatus.
+   *
+   * @param {string} to - target status
+   * @returns {this}
+   */
+  transitionStatus(to) {
+    return this.setStatus(to);
+  }
+
   // add your customized method here
 }
 

package/src/models/suggestion/suggestion.transitions.js

@@ -0,0 +1,83 @@
+/*
+ * Copyright 2025 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.
+ */
+
+/**
+ * Suggestion status literals.
+ *
+ * Duplicated from `Suggestion.STATUSES` (suggestion.model.js) to avoid a circular
+ * import — suggestion.model.js imports this module for its setStatus guard.
+ * Keep in sync if the enum ever changes. (Same pattern as suggestion.data-schemas.js.)
+ */
+const S = {
+  NEW: 'NEW',
+  APPROVED: 'APPROVED',
+  IN_PROGRESS: 'IN_PROGRESS',
+  SKIPPED: 'SKIPPED',
+  FIXED: 'FIXED',
+  ERROR: 'ERROR',
+  OUTDATED: 'OUTDATED',
+  PENDING_VALIDATION: 'PENDING_VALIDATION',
+  REJECTED: 'REJECTED',
+};
+
+export const SUGGESTION_CREATE = Symbol('SUGGESTION_CREATE');
+
+/**
+ * Suggestion status transition table.
+ *
+ * Source of truth: ADR adobe/mysticat-architecture#174. Unlike FixEntity, the
+ * Suggestion lifecycle is mostly *derived* (bubble-up from fix entities) plus a
+ * few direct writes from audit-worker / ESE-review / UI / api-service. This map
+ * is intentionally **permissive** in V1: it encodes the transitions we believe
+ * are legitimate today so the warn-only guard surfaces genuine anomalies without
+ * drowning real flows in false warnings. The warn logs from the rollout period
+ * inform which entries to tighten before flipping to enforce.
+ *
+ * The one hard rule already enforced by api-service is preserved exactly:
+ * REJECTED is only reachable from PENDING_VALIDATION (suggestions.js).
+ */
+export const SUGGESTION_TRANSITIONS = {
+  // audit-worker creates as NEW (non-paid) or PENDING_VALIDATION (paid); OUTDATED at audit time.
+  [SUGGESTION_CREATE]: [S.NEW, S.PENDING_VALIDATION, S.OUTDATED],
+  // ESE/TBYB review (-> NEW), mystique (-> IN_PROGRESS), bubble-up, UI skip, re-audit.
+  [S.NEW]: [S.APPROVED, S.IN_PROGRESS, S.FIXED, S.ERROR, S.SKIPPED, S.OUTDATED],
+  // paid-review gate: approve -> NEW, decline -> REJECTED (the one hard rule), or skip/outdate.
+  // IN_PROGRESS: api-service autofixSuggestions accepts PENDING_VALIDATION and sets IN_PROGRESS.
+  [S.PENDING_VALIDATION]: [S.NEW, S.IN_PROGRESS, S.REJECTED, S.SKIPPED, S.OUTDATED],
+  [S.APPROVED]: [S.IN_PROGRESS, S.FIXED, S.ERROR, S.SKIPPED, S.NEW, S.OUTDATED],
+  // bubble-up after fix-entity transitions.
+  [S.IN_PROGRESS]: [S.FIXED, S.ERROR, S.SKIPPED, S.NEW, S.OUTDATED],
+  // re-detection can reopen a fixed suggestion (-> NEW), retry (-> IN_PROGRESS), or outdate it.
+  [S.FIXED]: [S.NEW, S.IN_PROGRESS, S.ERROR, S.OUTDATED],
+  // errors are recoverable: re-attempt or reopen.
+  [S.ERROR]: [S.NEW, S.IN_PROGRESS, S.FIXED, S.SKIPPED, S.OUTDATED],
+  // un-skip / re-detect.
+  [S.SKIPPED]: [S.NEW, S.OUTDATED],
+  // re-detection reopens an outdated suggestion.
+  [S.OUTDATED]: [S.NEW],
+  // near-terminal: allow reopen to NEW to correct an incorrect classification (sandsinh review).
+  [S.REJECTED]: [S.NEW],
+};
+
+/**
+ * Returns true if the Suggestion status transition `from` -> `to` is allowed.
+ * A null/undefined `from` is treated as suggestion creation.
+ *
+ * @param {string|null|undefined} from - current status (null/undefined => create)
+ * @param {string} to - target status
+ * @returns {boolean}
+ */
+export const isAllowedSuggestionTransition = (from, to) => {
+  const key = (from === null || from === undefined) ? SUGGESTION_CREATE : from;
+  const allowed = SUGGESTION_TRANSITIONS[key];
+  return Array.isArray(allowed) && allowed.includes(to);
+};

package/src/models/ticket-suggestion/ticket-suggestion.schema.js

@@ -29,7 +29,10 @@ const schema = new SchemaBuilder(TicketSuggestion, TicketSuggestionCollection)
     type: 'string', required: false, readOnly: true, postgrestIgnore: true,
   })
   .addAttribute('updatedBy', { type: 'string', required: false, postgrestIgnore: true })
-  .addReference('belongs_to', 'Ticket')
+  // Sort key uses createdAt (not the default updatedAt) because ticket_suggestions is
+  // append-only — the table has no updated_at column, so ORDER BY updated_at would
+  // cause PostgREST to error on allByTicketId queries.
+  .addReference('belongs_to', 'Ticket', ['createdAt'])
   .addAttribute('suggestionId', {
     type: 'string',
     required: true,

package/src/util/status-transition-guard.js

@@ -0,0 +1,77 @@
+/*
+ * Copyright 2025 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.
+ */
+import { ValidationError } from '../errors/index.js';
+
+export const ENFORCEMENT_MODES = {
+  OFF: 'off',
+  WARN: 'warn',
+  ENFORCE: 'enforce',
+};
+
+/**
+ * Resolves the status-transition enforcement mode from the environment.
+ *
+ * `STATUS_TRANSITION_ENFORCEMENT` ∈ { off, warn, enforce }; defaults to `warn`.
+ * Read at call time so deployments (and tests) can flip it without a re-import.
+ * Rollout (SITES-47091): ship `warn` to surface today's illegal transitions in
+ * logs for ~1-2 weeks, then flip to `enforce`.
+ *
+ * @returns {string} one of ENFORCEMENT_MODES
+ */
+export const getEnforcementMode = () => {
+  const raw = (process.env.STATUS_TRANSITION_ENFORCEMENT || '').trim().toLowerCase();
+  return Object.values(ENFORCEMENT_MODES).includes(raw) ? raw : ENFORCEMENT_MODES.WARN;
+};
+
+/**
+ * Guards a status transition. A no-op (`from === to`) and any allowed transition
+ * pass silently. An illegal transition is, depending on the enforcement mode,
+ * ignored (`off`), logged without blocking (`warn`), or rejected (`enforce`).
+ *
+ * @param {object} params
+ * @param {string} params.entityName - e.g. 'FixEntity' / 'Suggestion' (for the message)
+ * @param {string} [params.entityId] - entity id (for the message)
+ * @param {string|null|undefined} params.from - current status (null/undefined => create)
+ * @param {string} params.to - target status
+ * @param {(from: string|null|undefined, to: string) => boolean} params.isAllowed
+ *   - transition predicate (isAllowedFixTransition / isAllowedSuggestionTransition)
+ * @param {object} [params.log] - logger with a `warn` method; the detailed
+ *   violation is logged in both `warn` and `enforce` modes
+ * @throws {ValidationError} in `enforce` mode when the transition is not allowed
+ */
+export const guardTransition = ({
+  entityName, entityId, from, to, isAllowed, log,
+}) => {
+  if (from === to) {
+    return;
+  }
+
+  const mode = getEnforcementMode();
+  if (mode === ENFORCEMENT_MODES.OFF) {
+    return;
+  }
+  if (isAllowed(from, to)) {
+    return;
+  }
+
+  // Detailed message goes to the server-side log (both warn and enforce) for ops/debugging.
+  const message = `status transition violation: ${entityName} ${entityId ?? '<unknown>'} ${from ?? '<create>'} -> ${to}`;
+  if (log) {
+    log.warn(message);
+  }
+
+  // enforce: throw a sanitized error (no entity id / current status) so an illegal
+  // transition surfaced via the API layer cannot be used as an existence/state oracle.
+  if (mode === ENFORCEMENT_MODES.ENFORCE) {
+    throw new ValidationError(`Invalid status transition for ${entityName}: cannot transition to ${to}`);
+  }
+};