@adobe/spacecat-shared-data-access 4.11.0 → 4.12.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [@adobe/spacecat-shared-data-access-v4.12.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v4.11.0...@adobe/spacecat-shared-data-access-v4.12.0) (2026-07-23)
+
+### Features
+
+* **data-access:** canonical v2 changeDetails schema + validator for FixEntity (SITES-47997) ([#1828](https://github.com/adobe/spacecat-shared/issues/1828)) ([afdb546](https://github.com/adobe/spacecat-shared/commit/afdb5464d6af6ac6ea9f6f0075d798feb38a5699))
+
 ## [@adobe/spacecat-shared-data-access-v4.11.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v4.10.1...@adobe/spacecat-shared-data-access-v4.11.0) (2026-07-21)
 
 ### Features

package/CLAUDE.md

@@ -247,6 +247,43 @@ Consumer adoption (bump + route writes + warn→enforce) is tracked in SITES-472
 
 [adobe/mysticat-architecture#174]: https://github.com/adobe/mysticat-architecture/blob/main/platform/decisions/design-suggestion-fix-entity-status-lifecycle.md
 
+## Deploy-action `changeDetails` v2 (SITES-47997)
+
+`FixEntity.changeDetails` has a canonical **v2 shape** — the structured,
+validated "deploy action" record (who/when/what/which-pages/result) from ADR
+[adobe/mysticat-architecture#200]. It is defined in
+`src/models/fix-entity/change-details.schema.js` (Joi) and wired into the
+`changeDetails` attribute validator.
+
+- **Reader-tolerant / additive.** The DB column stays `type: 'any'` — no
+  migration. Records **without `schemaVersion: 2`** are legacy freeform (v1) and
+  keep the old non-empty-object guard; only `schemaVersion: 2` records are
+  schema-validated. This runs on the **create** path (`#validateItem` →
+  `collection.create`), not on `save()` updates.
+- **Shape.** `{ schemaVersion: 2, surface, actorType, target, result? }`.
+  `target` = the proposal (intent): `changeType` + `changes[{ targetPath,
+  property, intendedValue }]`. `result` = the outcome: `callStatus`
+  (`success|no_op|client_error|server_error|timeout`), `applied`
+  (**enum `ALL|PARTIAL|NONE`, not a boolean**), `changeResults[]` (key-matched to
+  `target.changes` by `(targetPath, property)`), `pre/postVerify` verdicts, and
+  `deployResponsePayload` (**≤ 4 KB cap**) + `deployResponseSha256` (hex).
+- **APIs** (exported from the package root):
+  - `validateChangeDetails(value)` — the attribute validator; `false` on a
+    non-object, `true` for legacy/valid-v2, **throws** with a descriptive message
+    on an invalid v2 record.
+  - `changeDetailsV2Schema` — the raw Joi `ObjectSchema` (strict; unknown keys
+    rejected) for consumers that want to validate directly.
+  - `FixEntity.CHANGE_DETAILS` — the enum bundle (`SURFACES`, `ACTOR_TYPES`,
+    `CALL_STATUSES`, `APPLIED`, `CHANGE_RESULT_STATUSES`, `VERIFY_VERDICTS`,
+    `SCHEMA_VERSION`, `DEPLOY_RESPONSE_PAYLOAD_MAX_BYTES`). Kept on the model
+    (not the barrel) to avoid collisions on these generic names.
+- **Not yet done** (tracked on SITES-47997): the `publishedBy` column +
+  `executedBy/At` → `deployedBy/At` rename (dual-write, needs a companion
+  mysticat-data-service migration), and gating the `DEPLOYED`/`PUBLISHED`
+  transition on `result` presence (extends the SITES-47091 guard).
+
+[adobe/mysticat-architecture#200]: https://github.com/adobe/mysticat-architecture/blob/main/platform/decisions/deploy-action-provenance-and-verify.md
+
 ## Site Config: Import Types
 
 Site configuration lives in `src/models/site/config.js` and defines the available import types, their validation schemas, and default configs. This is one of the most frequently changed files in the package.

package/package.json

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

package/src/models/fix-entity/change-details.schema.js

@@ -0,0 +1,262 @@
+/*
+ * 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 Joi from 'joi';
+import { isNonEmptyObject } from '@adobe/spacecat-shared-utils';
+
+/**
+ * Canonical v2 shape for `FixEntity.changeDetails` — the structured, validated
+ * "deploy action" record defined by ADR
+ * adobe/mysticat-architecture#200 (platform/decisions/deploy-action-provenance-and-verify.md,
+ * SITES-47997): *who* deployed/published, *when*, *what entity/property* is
+ * proposed to change, *which pages* are affected, and *the result of the call*.
+ *
+ * The DB column stays `type: 'any'` (no destructive migration); this module is
+ * the machine-readable schema the JS write chokepoint validates against, so the
+ * freeform bag cannot silently drift across the two runtimes (autofix-worker JS
+ * + mystique Python). Records without `schemaVersion === 2` are legacy freeform
+ * (v1) and are intentionally NOT schema-validated — the migration is additive
+ * and reader-tolerant (ADR "V1 / V2 backwards compatibility").
+ */
+
+export const CHANGE_DETAILS_SCHEMA_VERSION = 2;
+
+// Deploy CHANNEL / "where" the fix went live.
+export const SURFACES = {
+  ASO: 'ASO',
+  AUTHOR_PUBLISH: 'AUTHOR_PUBLISH',
+  GIT_MERGE: 'GIT_MERGE',
+  SYSTEM: 'SYSTEM',
+};
+
+// WHO acted. Orthogonal to `surface` — DETECTOR is an actor (an audit that
+// observed a live fix), not a deploy channel, so it is an actorType not a surface.
+export const ACTOR_TYPES = {
+  IMS_USER: 'IMS_USER',
+  SERVICE: 'SERVICE',
+  GITHUB: 'GITHUB',
+  DETECTOR: 'DETECTOR',
+  UNKNOWN: 'UNKNOWN',
+};
+
+// Classified outcome of the deploy/apply call — transport-agnostic (JCR writes
+// and git ops classify the same way HTTP does). Set independently by the
+// transport adapter; NOT derived from `changeResults`. `no_op` is the case
+// SITES-47077 / SITES-47078 silently mis-read as success.
+export const CALL_STATUSES = {
+  SUCCESS: 'success',
+  NO_OP: 'no_op',
+  CLIENT_ERROR: 'client_error',
+  SERVER_ERROR: 'server_error',
+  TIMEOUT: 'timeout',
+};
+
+// Whole-action roll-up of the per-change `changeResults[].status`. NOT a boolean
+// — a deploy action may write >1 property, so "2-of-3" is first-class.
+export const APPLIED = {
+  ALL: 'ALL',
+  PARTIAL: 'PARTIAL',
+  NONE: 'NONE',
+};
+
+// Per-change outcome, key-matched to `target.changes` by (targetPath, property).
+export const CHANGE_RESULT_STATUSES = {
+  APPLIED: 'applied',
+  UNCHANGED: 'unchanged',
+  FAILED: 'failed',
+};
+
+// Verify verdict. Distinguishes NEGATIVE (`rejected` — verify ran, the change did
+// not render as expected → revert-eligible) from ERRORED (`verify_failed` —
+// verify could not complete → MUST NOT auto-revert). Mirrors the post-verify POC.
+export const VERIFY_VERDICTS = {
+  VERIFIED: 'verified',
+  REJECTED: 'rejected',
+  INCONCLUSIVE: 'inconclusive',
+  VERIFY_FAILED: 'verify_failed',
+};
+
+// `deployResponsePayload` size cap (bytes). MUST hold on a shared DB column — one
+// runaway payload degrades read latency for every consumer. Writers hash-first,
+// then cap/redact, so `deployResponseSha256` always covers the pre-redact payload.
+export const DEPLOY_RESPONSE_PAYLOAD_MAX_BYTES = 4096;
+
+const enumValues = (obj) => Object.values(obj);
+
+const byteLength = (value) => Buffer.byteLength(
+  typeof value === 'string' ? value : JSON.stringify(value ?? ''),
+  'utf8',
+);
+
+const verdictBase = {
+  verdict: Joi.string().valid(...enumValues(VERIFY_VERDICTS)).required(),
+  reasonCode: Joi.string(),
+  evidence: Joi.any(),
+};
+
+const preVerifySchema = Joi.object({
+  ...verdictBase,
+  preVerifiedAt: Joi.string().isoDate(),
+});
+
+const postVerifySchema = Joi.object({
+  ...verdictBase,
+  revert: Joi.any(),
+  postVerifiedAt: Joi.string().isoDate(),
+});
+
+// The PROPOSAL — intent only (`intendedValue`). Baseline (`previousValue`) and
+// observed outcome (`appliedValue`, `status`) live per-change in `changeResults`.
+const targetChangeSchema = Joi.object({
+  targetPath: Joi.string().required(),
+  property: Joi.string().required(),
+  intendedValue: Joi.any().required(),
+});
+
+const changeResultSchema = Joi.object({
+  targetPath: Joi.string().required(),
+  property: Joi.string().required(),
+  previousValue: Joi.any(),
+  appliedValue: Joi.any(),
+  status: Joi.string().valid(...enumValues(CHANGE_RESULT_STATUSES)).required(),
+});
+
+const targetSchema = Joi.object({
+  system: Joi.string(),
+  changeType: Joi.string().required(),
+  siteId: Joi.string(),
+  pageId: Joi.string(),
+  documentPath: Joi.string(),
+  detectedPageAuthorUrl: Joi.string(),
+  changes: Joi.array().items(targetChangeSchema).min(1).required(),
+});
+
+const resultSchema = Joi.object({
+  callStatus: Joi.string().valid(...enumValues(CALL_STATUSES)).required(),
+  applied: Joi.string().valid(...enumValues(APPLIED)).required(),
+  deployResponsePayload: Joi.any().custom((value, helpers) => {
+    let size;
+    try {
+      size = byteLength(value);
+    } catch {
+      // Un-serializable payload (e.g. a circular reference) — it must be
+      // serialized/truncated into deployResponseSha256 at the write chokepoint
+      // before persist, so reject it here rather than throw a raw TypeError.
+      return helpers.error('any.invalid');
+    }
+    if (size > DEPLOY_RESPONSE_PAYLOAD_MAX_BYTES) {
+      return helpers.error('any.invalid');
+    }
+    return value;
+  }).messages({
+    'any.invalid': `result.deployResponsePayload exceeds ${DEPLOY_RESPONSE_PAYLOAD_MAX_BYTES} bytes; hash it into deployResponseSha256 and truncate at the write chokepoint`,
+  }),
+  deployResponseSha256: Joi.string().pattern(/^[a-f0-9]{64}$/i),
+  changeResults: Joi.array().items(changeResultSchema),
+  preVerify: preVerifySchema,
+  postVerify: postVerifySchema,
+});
+
+// Composite match key for (targetPath, property). JSON.stringify gives an
+// unambiguous, collision-safe delimiter regardless of what the strings contain.
+const changeKey = (change) => JSON.stringify([change.targetPath, change.property]);
+
+/**
+ * Canonical Joi schema for a v2 `changeDetails` record. Strict (unknown keys are
+ * rejected) so v2 writers cannot re-introduce freeform drift.
+ */
+export const changeDetailsV2Schema = Joi.object({
+  // `.strict()` — no type coercion: writers MUST pass the integer 2, never the
+  // string '2'. A coerced-then-persisted '2' would read as legacy (!= 2) in
+  // mystique's Python runtime, the exact cross-runtime divergence this
+  // discriminator exists to prevent.
+  schemaVersion: Joi.number().valid(CHANGE_DETAILS_SCHEMA_VERSION).strict().required(),
+  surface: Joi.string().valid(...enumValues(SURFACES)).required(),
+  actorType: Joi.string().valid(...enumValues(ACTOR_TYPES)).required(),
+  target: targetSchema.required(),
+  result: resultSchema,
+}).custom((value, helpers) => {
+  // Blocking constraint: `result.changeResults` and `target.changes` MUST
+  // key-match by (targetPath, property) — not positional — so a writer that
+  // skips or reorders an entry cannot silently misalign the proposal (intent)
+  // against the observed outcome. When either side is absent the required-field
+  // rules already reject the record, so we only cross-check once both are arrays.
+  const changeResults = value.result?.changeResults;
+  const changes = value.target?.changes;
+  const appliedAll = value.result?.applied === APPLIED.ALL;
+  // (a) `applied: ALL` claims every proposed change landed, so it MUST carry the
+  // per-change evidence — an ALL with no changeResults is an unfalsifiable claim.
+  if (appliedAll && !Array.isArray(changeResults)) {
+    return helpers.message('result.applied is ALL but result.changeResults is missing');
+  }
+  if (Array.isArray(changeResults) && Array.isArray(changes)) {
+    const intentKeys = new Set(changes.map(changeKey));
+    // (b) no orphan outcome — every changeResult maps to a proposed change.
+    if (changeResults.some((r) => !intentKeys.has(changeKey(r)))) {
+      return helpers.message('result.changeResults contains an entry with no matching target.changes (targetPath, property)');
+    }
+    // (c) completeness for a whole-action success — every proposed change MUST
+    // have a recorded outcome. PARTIAL/NONE legitimately omit entries.
+    if (appliedAll) {
+      const resultKeys = new Set(changeResults.map(changeKey));
+      if (changes.some((c) => !resultKeys.has(changeKey(c)))) {
+        return helpers.message('result.applied is ALL but a target.changes entry has no matching result.changeResults');
+      }
+    }
+  }
+  return value;
+});
+
+/**
+ * Validator for the `FixEntity.changeDetails` attribute. Reader-tolerant:
+ * legacy freeform records (schemaVersion absent or !== 2) keep the pre-existing
+ * non-empty-object guard; v2 records are validated against {@link changeDetailsV2Schema}.
+ *
+ * @param {*} value - the changeDetails value being persisted.
+ * @returns {boolean} true when valid (schema builders treat `false` as a failure).
+ * @throws {Error} with a descriptive message when a v2 record is invalid.
+ */
+export function validateChangeDetails(value) {
+  if (!isNonEmptyObject(value)) {
+    return false;
+  }
+  // Only an ABSENT schemaVersion (or an explicit v1) is legacy freeform, per the
+  // ADR ("absent/1 ⇒ legacy freeform"). Anything else is claiming to be
+  // structured, so it MUST run through the v2 schema — a stray `schemaVersion:
+  // '2'` (int-vs-string drift) or a future version must never silently pass.
+  const { schemaVersion } = value;
+  if (schemaVersion === undefined || schemaVersion === null
+    || schemaVersion === 1 || schemaVersion === '1') {
+    return true;
+  }
+  const { error } = changeDetailsV2Schema.validate(value, { abortEarly: false });
+  if (error) {
+    throw new Error(`changeDetails (v2) invalid: ${error.message}`);
+  }
+  return true;
+}
+
+/**
+ * Bundle of the v2 changeDetails enums + limits, attached to the FixEntity model
+ * as `FixEntity.CHANGE_DETAILS` (mirrors `FixEntity.STATUSES`). Kept off the
+ * package root barrel to avoid collisions on these generic names.
+ */
+export const CHANGE_DETAILS = {
+  SCHEMA_VERSION: CHANGE_DETAILS_SCHEMA_VERSION,
+  SURFACES,
+  ACTOR_TYPES,
+  CALL_STATUSES,
+  APPLIED,
+  CHANGE_RESULT_STATUSES,
+  VERIFY_VERDICTS,
+  DEPLOY_RESPONSE_PAYLOAD_MAX_BYTES,
+};

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

@@ -12,6 +12,7 @@
 import BaseModel from '../base/base.model.js';
 import { guardTransition } from '../../util/status-transition-guard.js';
 import { isAllowedFixTransition } from './fix-entity.transitions.js';
+import { CHANGE_DETAILS } from './change-details.schema.js';
 
 /**
  * FixEntity - A class representing a FixEntity for a Suggestion.
@@ -41,6 +42,10 @@ class FixEntity extends BaseModel {
     REPORTING: 'reporting',
   };
 
+  // Canonical v2 changeDetails enums + limits (SITES-47997, ADR
+  // adobe/mysticat-architecture#200). e.g. FixEntity.CHANGE_DETAILS.SURFACES.ASO.
+  static CHANGE_DETAILS = CHANGE_DETAILS;
+
   /**
    * Sets the fix status, guarding the transition against the canonical table
    * (fix-entity.transitions.js). Overrides the auto-generated setter so EVERY

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

@@ -10,12 +10,13 @@
  * governing permissions and limitations under the License.
  */
 
-import { isIsoDate, isNonEmptyObject } from '@adobe/spacecat-shared-utils';
+import { isIsoDate } from '@adobe/spacecat-shared-utils';
 
 import SchemaBuilder from '../base/schema.builder.js';
 import FixEntity from './fix-entity.model.js';
 import FixEntityCollection from './fix-entity.collection.js';
 import Suggestion from '../suggestion/suggestion.model.js';
+import { validateChangeDetails } from './change-details.schema.js';
 
 const schema = new SchemaBuilder(FixEntity, FixEntityCollection)
   .addReference('has_many', 'FixEntitySuggestion', ['updatedAt'], { removeDependents: true })
@@ -39,7 +40,10 @@ const schema = new SchemaBuilder(FixEntity, FixEntityCollection)
   .addAttribute('changeDetails', {
     type: 'any',
     required: true,
-    validate: (value) => isNonEmptyObject(value),
+    // Reader-tolerant: legacy freeform (v1) records keep the non-empty guard;
+    // schemaVersion:2 records are validated against the canonical shape
+    // (SITES-47997, ADR adobe/mysticat-architecture#200).
+    validate: (value) => validateChangeDetails(value),
   })
   .addAttribute('status', {
     type: Object.values(FixEntity.STATUSES),

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

@@ -10,6 +10,7 @@
  * governing permissions and limitations under the License.
  */
 
+import type { ObjectSchema } from 'joi';
 import type {
   BaseCollection, BaseModel, Opportunity, Suggestion, FixEntitySuggestion,
 } from '../index';
@@ -52,3 +53,9 @@ export declare function isAllowedFixTransition(
   from: string | null | undefined,
   to: string,
 ): boolean;
+
+// Canonical v2 changeDetails shape + validator (SITES-47997, ADR
+// adobe/mysticat-architecture#200).
+export declare const CHANGE_DETAILS_SCHEMA_VERSION: number;
+export declare const changeDetailsV2Schema: ObjectSchema;
+export declare function validateChangeDetails(value: unknown): boolean;

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

@@ -24,3 +24,12 @@ export {
   FIX_ENTITY_CREATE,
   isAllowedFixTransition,
 } from './fix-entity.transitions.js';
+
+// Canonical v2 changeDetails shape + validator (SITES-47997, ADR
+// adobe/mysticat-architecture#200). The generic enum names live on
+// FixEntity.CHANGE_DETAILS to keep them off the package-root barrel.
+export {
+  CHANGE_DETAILS_SCHEMA_VERSION,
+  changeDetailsV2Schema,
+  validateChangeDetails,
+} from './change-details.schema.js';