feat(serenity): rename the authorship dimension root from source to origin

WP-O2a: renames DIMENSION.SOURCE -> DIMENSION.ORIGIN (and SOURCE_VALUE ->
ORIGIN_VALUE) in prompt-tags.js, and gives the authorship root its own
tolerant resolver in tag-tree.js (resolveAuthorshipRoot): it reuses an
existing `origin` root, else adopts a legacy `source` root whose children
are a subset of {ai, human}, else mints a new `origin` root — never a
second, empty one. ensureDimensionRoots/provisionDimensionTree/
ensureClosedValue route through this resolver instead of blind-creating
the authorship root. parseCreateTagBody and the provisioning seams in
markets-subworkspace.js already validate/seed against ALL_DIMENSIONS/
DIMENSION_ROOT_NAMES, so they pick up the rename automatically.

WP-O2b: generalizes makeTypeInjector (handlers/prompts.js, and its
subworkspace twin) to also strip+inject `origin` on every prompt write:
CREATE always derives to `ai`; UPDATE re-injects whichever `origin` tag
the request already carries (never re-derived), falling back to `ai`
only if none is found. prompts-storage.js's upsertPrompts now derives
`origin` from the caller's authenticated principal (service principal:
honor an asserted ai/human value; user principal: always override to
human) via the new resolveOriginForWrite; updatePromptById no longer
accepts `origin` in a PATCH body; mapRowToPrompt drops the `|| 'human'`
read fallback. brands.js wires isServicePrincipal from context.s2sConsumer
into upsertPrompts. OpenAPI docs updated to describe the new origin
semantics without changing the query filter/sort surface.

Tracks WP-O2a (spacecat-api-service#2816, SITES-48001) and WP-O2b
(spacecat-api-service#2817, SITES-48002) from serenity-docs PR #46.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: byteclimber

docs/openapi/prompts-v2-api.yaml

@@ -254,6 +254,10 @@ v2-prompts-by-brand-and-id:
     tags:
       - customer-config
     summary: Update a single prompt
+    description: >-
+      `origin` in the body is not honored on PATCH — it is set once at create
+      time (see `V2PromptInput.origin`) and can never be changed afterward, so
+      any `origin` sent here is ignored.
     operationId: updatePromptByBrandAndId
     security:
       - ims_key: [ ]

docs/openapi/schemas.yaml

@@ -6643,6 +6643,11 @@ V2PromptInput:
       type: string
       enum: [ai, human]
       default: human
+      description: >-
+        Who authored the prompt. Service-principal only: honored (and
+        validated against the enum) only when the caller authenticates as an
+        S2S service; for a user-authenticated request this field is ignored
+        and always overridden to `human`, regardless of what is sent.
     source:
       type: string
       description: The source system or process that created the prompt

src/controllers/brands.js

@@ -554,6 +554,11 @@ function BrandsController(ctx, log, env) {
 
       const { postgrestClient } = context.dataAccess.services;
       const updatedBy = context.attributes?.authInfo?.profile?.email || 'system';
+      // Service principals (e.g. llmo-data-retrieval-service) authenticate over
+      // s2sAuthWrapper, which sets `context.s2sConsumer`; a user principal never
+      // carries it. Gates whether a per-prompt `origin` in the body is honored —
+      // see `resolveOriginForWrite`.
+      const isServicePrincipal = Boolean(context.s2sConsumer);
 
       const brandUuid = await resolveBrandUuid(spaceCatId, brandId, postgrestClient);
       if (!brandUuid) {
@@ -567,6 +572,7 @@ function BrandsController(ctx, log, env) {
         postgrestClient,
         updatedBy,
         classifyIntent: classifyIntent ?? undefined,
+        isServicePrincipal,
       });
 
       return createResponse({ created, updated, prompts: outPrompts }, 201);

src/support/prompts-storage.js

@@ -17,6 +17,33 @@ import { hasText, isValidUUID } from '@adobe/spacecat-shared-utils';
 import { classifyIntents } from './intent-classifier.js';
 import { throwOnPgConstraintViolation } from './errors.js';
 import { INTENT_VALUES, normalizeIntent } from './intent.js';
+import { ORIGIN_VALUE } from './serenity/prompt-tags.js';
+
+const ORIGIN_VALUES = new Set(Object.values(ORIGIN_VALUE));
+
+/**
+ * Resolves the `origin` a prompt write should carry, from the caller's
+ * authenticated principal rather than trusting the request body outright.
+ *
+ * A SERVICE principal (e.g. llmo-data-retrieval-service, which POSTs with a
+ * hardcoded `origin: "ai"`) may assert either enum value; an unrecognized
+ * value is treated as absent rather than rejected — a write must never fail
+ * over this field. A USER principal's asserted value is always ignored: a
+ * human hitting this endpoint is definitionally authoring the prompt
+ * themselves, so the body's `origin` (if any) is silently overridden, never
+ * used to reject the request.
+ *
+ * @param {*} candidate - the request body's asserted `origin`, if any.
+ * @param {boolean} isServicePrincipal - true when the caller authenticated as
+ *   an S2S service (see `context.s2sConsumer` at the controller boundary).
+ * @returns {'ai' | 'human'}
+ */
+export function resolveOriginForWrite(candidate, isServicePrincipal) {
+  if (isServicePrincipal && ORIGIN_VALUES.has(candidate)) {
+    return candidate;
+  }
+  return ORIGIN_VALUE.HUMAN;
+}
 
 // Re-exported for backward compatibility — `normalizeIntent`/`INTENT_VALUES` now
 // live in `./intent.js` so the LLM intent classifier can reuse them without an
@@ -405,7 +432,9 @@ function mapRowToPrompt(row) {
     name: row.name,
     regions: row.regions || [],
     status: row.status || 'active',
-    origin: row.origin || 'human',
+    // No fallback: the column has zero NULLs in production, so `|| 'human'`
+    // was dead code that would otherwise silently mislabel a null as human.
+    origin: row.origin,
     source: row.source || 'config',
     intent: row.intent ?? null,
     createdAt: row.created_at,
@@ -706,6 +735,9 @@ export async function getPromptById({
  *   text without an explicit intent. Non-fatal: a null result leaves intent unset.
  * @param {number} [params.classifyIntentBatchTimeoutMs] - Cap on the classifier
  *   batch (ms); the upsert proceeds without intent once it elapses.
+ * @param {boolean} [params.isServicePrincipal] - true when the caller
+ *   authenticated as an S2S service; gates whether a per-prompt `origin` in
+ *   the request body is honored (see {@link resolveOriginForWrite}).
  * @returns {Promise<{created: number, updated: number, prompts: object[]}>}
  */
 export async function upsertPrompts({
@@ -716,6 +748,7 @@ export async function upsertPrompts({
   updatedBy = 'system',
   classifyIntent,
   classifyIntentBatchTimeoutMs = 8000,
+  isServicePrincipal = false,
 }) {
   if (!postgrestClient?.from) {
     throw new Error('PostgREST client is required for prompts');
@@ -789,7 +822,7 @@ export async function upsertPrompts({
       category_id: categoryUuid,
       topic_id: topicUuid,
       status: p.status || 'active',
-      origin: p.origin || 'human',
+      origin: resolveOriginForWrite(p.origin, isServicePrincipal),
       source: p.source || 'config',
       intent: normalizeIntent(p.intent),
       updated_by: updatedBy,
@@ -1003,9 +1036,9 @@ export async function updatePromptById({
   if (updates.status !== undefined) {
     patch.status = updates.status;
   }
-  if (updates.origin !== undefined) {
-    patch.origin = updates.origin;
-  }
+  // `origin` is never patchable via the PATCH body — mirrors `source`, which is
+  // already absent here. It is set once at create time (from the authenticated
+  // principal — see `upsertPrompts`) and never re-derived or overridden later.
   if (updates.intent !== undefined) {
     // The shared fallback strips intent when the column is known-absent.
     patch.intent = normalizeIntent(updates.intent);

src/support/serenity/handlers/prompts-subworkspace.js

@@ -279,7 +279,7 @@ export async function handleUpdatePromptSubworkspace(
   const injectComputedType = makeTypeInjector(transport, workspaceId, classifyPromptType, log);
   const typed = await injectComputedType(projectId, {
     text: nextText, geoTargetId, tagIds: nextTagIds,
-  });
+  }, { mode: 'update' });
 
   try {
     await transport.deletePromptsByIds(workspaceId, projectId, [semrushPromptId]);

src/support/serenity/handlers/prompts.js

@@ -19,7 +19,8 @@ import { redactUpstreamMessage } from '../rest-transport.js';
 import { ERROR_CODES, isUpstreamGone } from '../errors.js';
 import { normalizeGeoTargetId, normalizeLanguageCode, isValidTagIdFormat } from '../validation.js';
 import { invalidateTagCacheForProject } from './markets.js';
-import { resolveTypeValueInjection } from '../tag-tree.js';
+import { resolveTypeValueInjection, resolveOriginValueInjection } from '../tag-tree.js';
+import { ORIGIN_VALUE } from '../prompt-tags.js';
 
 // TWIN FILE: the slice→project orchestration here is paralleled by the
 // subworkspace-mode handlers in prompts-subworkspace.js. The duplication is
@@ -344,60 +345,115 @@ export async function createOnePrompt(transport, semrushWorkspaceId, projectId,
 }
 
 /**
- * Builds the per-request `type` injector — the UNIFIED classification layer
- * (serenity-docs#31). Given a pure `classifyPromptType(text, geoTargetId)`
+ * Builds the per-request `type` + `origin` injector — the UNIFIED
+ * classification layer (serenity-docs#31, extended by the-origin-dimension
+ * spec for `origin`). Given a pure `classifyPromptType(text, geoTargetId)`
  * closure (built by the controller from the brand name + region-clamped
  * aliases) that yields a BARE `type` value (`branded` / `non-branded`), it
- * returns `injectComputedType(projectId, input)` which:
- *   - STRIPS every caller-supplied tag id that lives under the `type` root (the
- *     client may never set the value), and
- *   - APPENDS the pre-resolved upstream id of the server-computed value. The
- *     atomic `createPromptsByIds` 500s on an unresolved id, so it is resolved
+ * returns `injectComputedType(projectId, input, options)` which, for BOTH
+ * dimensions:
+ *   - STRIPS every caller-supplied tag id that lives under the dimension's root
+ *     (the client may never set either value directly), and
+ *   - APPENDS a resolved upstream tag id in its place. The atomic
+ *     `createPromptsByIds` 500s on an unresolved id, so ids are resolved
  *     BEFORE the write.
  * The returned input carries the rewritten `tagIds`, so the caller's response
- * echo reflects the computed type without a refetch (decision 5).
+ * echo reflects the computed values without a refetch (decision 5).
  *
- * The strip set is every id under the `type` root, not a name prefix: a tag's
- * dimension is its root, and a sub-category could legitimately be named
- * `branded` without being a `type` value.
+ * The strip set for each dimension is every id under that dimension's root,
+ * not a name prefix: a tag's dimension is its root, and a sub-category could
+ * legitimately be named `branded` or `ai` without being a `type`/`origin` value.
  *
- * Resolution ({@link resolveTypeValueInjection}, two tag-tree reads per distinct
- * `type` value per project — the root level plus the `type` root's children) is
- * memoized for the request, so a bulk create fans out over the distinct computed
- * values rather than over the items. A non-function `classifyPromptType`
- * (defensive) is a pass-through.
+ * `type` is always freshly classified from the write's own text. `origin` is
+ * asymmetric between create and update (`options.mode`, default `'create'`):
+ *   - `'create'`: derives to {@link ORIGIN_VALUE.AI} — every prompt this layer
+ *     creates is AI-generated.
+ *   - `'update'`: re-injects whichever `origin` tag id is ALREADY in
+ *     `input.tagIds` (the client round-trips the tags it read off the prior
+ *     list call), rather than deriving a new one from anything in the update
+ *     request. This is deliberate: `origin` records who authored the prompt
+ *     ORIGINALLY, which an edit does not change. If none is found (a prompt
+ *     tagged before this dimension existed), it falls back to `AI` rather than
+ *     leave the prompt untagged — a strip-without-inject would make it invisible
+ *     to origin-based filtering.
  *
- * `resolveTypeValueInjection` resolves or throws, so the computed tag is always
- * attached. It must never be dropped: `type` is the one dimension a client may
- * not set, so a prompt written without it stays unclassified forever, and the
- * caller sees a 2xx. Failing the write instead is free — the upstream bulk create
- * is atomic and has not run yet.
+ * Resolution (two tag-tree reads per distinct value per project — the root
+ * level plus that dimension root's children) is memoized for the request per
+ * dimension, so a bulk create fans out over the distinct computed values
+ * rather than over the items. A non-function `classifyPromptType` (defensive)
+ * skips the `type` step; `origin` is always injected.
+ *
+ * Both resolvers resolve or throw, so the computed tags are always attached.
+ * They must never be dropped: neither dimension is client-settable, so a
+ * prompt written without one stays unclassified forever, and the caller sees a
+ * 2xx. Failing the write instead is free — the upstream bulk create is atomic
+ * and has not run yet.
  *
  * @param {object} transport - Serenity transport (Semrush proxy client).
  * @param {string} semrushWorkspaceId
  * @param {((text: string, geoTargetId: number) => string) | undefined} classifyPromptType
  * @param {object} [log]
  * @returns {(projectId: string, input: { text: string, geoTargetId: number,
- *   tagIds: string[] }) =>
+ *   tagIds: string[] }, options?: { mode?: 'create' | 'update' }) =>
  *   Promise<{ text: string, geoTargetId: number, tagIds: string[] }>}
  */
 export function makeTypeInjector(transport, semrushWorkspaceId, classifyPromptType, log) {
   /** @type {Map<string, Promise<{ computedId: string, typeTagIds: string[] }>>} */
-  const cache = new Map();
-  return async function injectComputedType(projectId, input) {
-    if (typeof classifyPromptType !== 'function') {
-      return input;
+  const typeCache = new Map();
+  /** @type {Map<string, Promise<{ computedId: string, originTagIds: string[] }>>} */
+  const originCache = new Map();
+
+  return async function injectComputedType(projectId, input, { mode = 'create' } = {}) {
+    let out = input;
+
+    if (typeof classifyPromptType === 'function') {
+      const typeValue = classifyPromptType(input.text, input.geoTargetId);
+      const typeKey = `${projectId} ${typeValue}`;
+      let typePending = typeCache.get(typeKey);
+      if (!typePending) {
+        typePending = resolveTypeValueInjection(
+          transport,
+          semrushWorkspaceId,
+          projectId,
+          typeValue,
+          log,
+        );
+        typeCache.set(typeKey, typePending);
+      }
+      const { computedId, typeTagIds } = await typePending;
+      const stripped = out.tagIds.filter((id) => !typeTagIds.includes(id));
+      out = { ...out, tagIds: [...stripped, computedId] };
     }
-    const typeValue = classifyPromptType(input.text, input.geoTargetId);
-    const key = `${projectId} ${typeValue}`;
-    let pending = cache.get(key);
-    if (!pending) {
-      pending = resolveTypeValueInjection(transport, semrushWorkspaceId, projectId, typeValue, log);
-      cache.set(key, pending);
+
+    // `origin` resolution is the same tree lookup on both create and update —
+    // every id under the root, plus the resolved `AI` id — only what CREATE
+    // does with it differs from what UPDATE does.
+    const originKey = `${projectId} ${ORIGIN_VALUE.AI}`;
+    let originPending = originCache.get(originKey);
+    if (!originPending) {
+      originPending = resolveOriginValueInjection(
+        transport,
+        semrushWorkspaceId,
+        projectId,
+        ORIGIN_VALUE.AI,
+        log,
+      );
+      originCache.set(originKey, originPending);
     }
-    const { computedId, typeTagIds } = await pending;
-    const stripped = input.tagIds.filter((id) => !typeTagIds.includes(id));
-    return { ...input, tagIds: [...stripped, computedId] };
+    const { computedId: aiId, originTagIds } = await originPending;
+    const stripped = out.tagIds.filter((id) => !originTagIds.includes(id));
+
+    // UPDATE re-injects whichever origin tag the caller already carried — it
+    // never derives a new one. CREATE always derives to AI. Falling back to AI
+    // when update finds none avoids a strip-without-inject (which would make
+    // the prompt invisible to origin-based filtering) for a prompt tagged
+    // before this dimension existed.
+    const nextOriginId = mode === 'update'
+      ? (out.tagIds.find((id) => originTagIds.includes(id)) ?? aiId)
+      : aiId;
+    out = { ...out, tagIds: [...stripped, nextOriginId] };
+
+    return out;
   };
 }
 
@@ -690,7 +746,7 @@ export async function handleUpdatePrompt(
   );
   const typed = await injectComputedType(projectId, {
     text: nextText, geoTargetId, tagIds: nextTagIds,
-  });
+  }, { mode: 'update' });
 
   try {
     await transport.deletePromptsByIds(semrushWorkspaceId, projectId, [semrushPromptId]);

src/support/serenity/prompt-tags.js

@@ -19,7 +19,7 @@
  * serenity flow.
  *
  * A tag's DIMENSION is its root ancestor, not a prefix on its name. Every
- * project's tag tree has exactly four roots — `category`, `intent`, `source`,
+ * project's tag tree has exactly four roots — `category`, `intent`, `origin`,
  * `type` — and every tag value is a bare-named descendant of one of them. No
  * tag name contains a `:`. A tag's dimension is therefore `path[0]` of the
  * upstream breadcrumb (verified against the live Semrush API: `path[]` is a
@@ -30,8 +30,15 @@
  * The upstream API caps neither, so nothing here does either.
  *
  * Names are NOT unique on their own — upstream uniqueness is scoped per
- * `(project, parent)`. A sub-category named `human` and the `source` value
+ * `(project, parent)`. A sub-category named `human` and the `origin` value
  * `human` are two distinct tags. Never key a tag by name alone; key by id.
+ *
+ * `origin` used to be named `source`. Some live projects still carry the
+ * authorship root under that old name — `tag-tree.js`'s
+ * `resolveAuthorshipRoot` is the tolerant resolver that reuses a project's
+ * existing `source` root instead of minting a second, empty `origin` root; see
+ * that module for the full rationale. This module only names the CURRENT
+ * (`origin`) vocabulary; it has no notion of the legacy name.
  */
 
 /**
@@ -40,20 +47,20 @@
 export const DIMENSION = Object.freeze({
   CATEGORY: 'category',
   INTENT: 'intent',
-  SOURCE: 'source',
+  ORIGIN: 'origin',
   TYPE: 'type',
 });
 
 /** Root names, in the order they are provisioned on a project. */
 export const DIMENSION_ROOT_NAMES = Object.freeze([
   DIMENSION.CATEGORY,
   DIMENSION.INTENT,
-  DIMENSION.SOURCE,
+  DIMENSION.ORIGIN,
   DIMENSION.TYPE,
 ]);
 
-/** `source` values — who authored the prompt. */
-export const SOURCE_VALUE = Object.freeze({
+/** `origin` values — who authored the prompt. */
+export const ORIGIN_VALUE = Object.freeze({
   AI: 'ai',
   HUMAN: 'human',
 });
@@ -98,14 +105,14 @@ export const TYPE_VALUE = Object.freeze({
  */
 export const CLOSED_DIMENSION_VALUES = Object.freeze({
   [DIMENSION.INTENT]: Object.freeze(Object.values(INTENT_VALUE)),
-  [DIMENSION.SOURCE]: Object.freeze(Object.values(SOURCE_VALUE)),
+  [DIMENSION.ORIGIN]: Object.freeze(Object.values(ORIGIN_VALUE)),
   [DIMENSION.TYPE]: Object.freeze(Object.values(TYPE_VALUE)),
 });
 
 /** The closed dimensions — fixed vocabularies, never customer-authored. */
 export const CLOSED_DIMENSIONS = Object.freeze([
   DIMENSION.INTENT,
-  DIMENSION.SOURCE,
+  DIMENSION.ORIGIN,
   DIMENSION.TYPE,
 ]);
 
@@ -120,7 +127,7 @@ export const OPEN_DIMENSIONS = Object.freeze([DIMENSION.CATEGORY]);
 export const ALL_DIMENSIONS = Object.freeze([...OPEN_DIMENSIONS, ...CLOSED_DIMENSIONS]);
 
 /**
- * The closed-dimension values applied to EVERY AI-generated prompt: `source:ai`
+ * The closed-dimension values applied to EVERY AI-generated prompt: `origin:ai`
  * (AI-authored) plus the default `Informational` intent (the most common intent
  * for brand-topic prompts; re-classification can refine it later). The `type`
  * value is classified per prompt at generation time (branded vs non-branded —
@@ -130,7 +137,7 @@ export const ALL_DIMENSIONS = Object.freeze([...OPEN_DIMENSIONS, ...CLOSED_DIMEN
  * the pair to an upstream tag id against the project's tree.
  */
 export const STANDARD_PROMPT_TAG_VALUES = Object.freeze([
-  Object.freeze({ dimension: DIMENSION.SOURCE, name: SOURCE_VALUE.AI }),
+  Object.freeze({ dimension: DIMENSION.ORIGIN, name: ORIGIN_VALUE.AI }),
   Object.freeze({ dimension: DIMENSION.INTENT, name: INTENT_VALUE.INFORMATIONAL }),
 ]);