feat(serenity): derive + inject prompt origin server-side — WP-O2b (LLMO-6275)

docs/openapi/prompts-v2-api.yaml

@@ -254,6 +254,11 @@ v2-prompts-by-brand-and-id:
     tags:
       - customer-config
     summary: Update a single prompt
+    description: >-
+      Updates a single prompt. `origin` is NOT patchable — it is fixed by the
+      writer that created the row and is never re-derived on update
+      (origin-dimension.md §3 item 3); an `origin` in the body is ignored,
+      leaving the stored value untouched.
     operationId: updatePromptByBrandAndId
     security:
       - ims_key: [ ]

docs/openapi/schemas.yaml

@@ -6510,6 +6510,12 @@ V2PromptListResponse:
 V2Prompt:
   type: object
   description: A prompt with brand, category, and topic enrichment
+  # FIX (MysticatBot suggestion): `origin` is required (non-nullable) in the
+  # response — it is NOT NULL in production and `mapRowToPrompt` returns it
+  # verbatim with no fallback (origin-dimension.md §2.3 / §3 item 4), so
+  # SDK-generated types must reflect it as always-present, never optional.
+  required:
+    - origin
   properties:
     id:
       type: string
@@ -6643,6 +6649,13 @@ V2PromptInput:
       type: string
       enum: [ai, human]
       default: human
+      description: >-
+        Who authored the prompt's text. SERVICE-PRINCIPAL-ONLY and read-only for
+        end users: a user-authenticated request (IMS/JWT) has this field IGNORED
+        (never rejected) and the value derived as `human`; only a service
+        principal (e.g. the generation pipeline) may assert it, validated against
+        the enum. It is never patched on update — it is fixed by the writer that
+        created the row (origin-dimension.md §3).
     source:
       type: string
       description: The source system or process that created the prompt

src/controllers/brands.js

@@ -49,6 +49,7 @@ import {
   getPromptStats,
   resolveBrandUuid,
   findPromptsBlockingRegionRemoval,
+  deriveV2PromptOrigin,
 } from '../support/prompts-storage.js';
 import {
   listBrands,
@@ -572,10 +573,36 @@ function BrandsController(ctx, log, env) {
         return notFound(`Brand not found: ${brandId}`);
       }
 
+      // `origin` is derived from the request PRINCIPAL, never trusted from the
+      // body (origin-dimension.md §3): a user (IMS/JWT) write is `human`, body
+      // ignored; a service principal (e.g. DRS via admin x-api-key, whose auth
+      // type is neither `ims` nor `jwt`) is believed. The auth type is read from
+      // the per-request context — the same source as `updatedBy` above — so it
+      // reflects the actual caller. Stamp it here so the store writes the derived
+      // value on insert; on update the stored origin is preserved (upsertPrompts)
+      // and never patched (updatePromptById).
+      //
+      // Fail SAFE to the least-privileged (USER) principal: an ABSENT or
+      // indeterminate auth type must NEVER fall through to the privileged service
+      // path that honours a body-supplied `origin`. Only a KNOWN non-user auth
+      // type (jwt/ims are user; anything else, e.g. DRS admin x-api-key, is
+      // service) is trusted as a service principal. `authWrapper` blocks
+      // unauthenticated requests today, but a future unwrapped caller (an internal
+      // queue consumer, re-ordered middleware) must not silently gain service
+      // privilege — hence `!authType → user`, and a non-function `getType` resolves
+      // to `undefined` (→ user) rather than throwing.
+      const { authInfo } = context.attributes ?? {};
+      const authType = typeof authInfo?.getType === 'function' ? authInfo.getType() : undefined;
+      const isUserPrincipal = !authType || authType === 'jwt' || authType === 'ims';
+      const derivedPrompts = prompts.map((p) => ({
+        ...p,
+        origin: deriveV2PromptOrigin(p?.origin, isUserPrincipal),
+      }));
+
       const { created, updated, prompts: outPrompts } = await upsertPrompts({
         organizationId: spaceCatId,
         brandUuid,
-        prompts,
+        prompts: derivedPrompts,
         postgrestClient,
         updatedBy,
         classifyIntent: classifyIntent ?? undefined,

src/support/prompts-storage.js

@@ -24,6 +24,45 @@ import { INTENT_VALUES, normalizeIntent } from './intent.js';
 // import cycle. Existing importers of these from `prompts-storage.js` keep working.
 export { INTENT_VALUES, normalizeIntent };
 
+/**
+ * The closed `origin` vocabulary — who authored the prompt's text
+ * (origin-dimension.md §1). Matches the `category_origin` enum on `prompts.origin`.
+ */
+export const V2_PROMPT_ORIGINS = Object.freeze(['ai', 'human']);
+const DEFAULT_ORIGIN = 'human';
+
+/**
+ * Derives the `origin` to store for a v2-prompts write, as a function of the
+ * request PRINCIPAL, never of the caller-supplied body value (origin-dimension.md
+ * §3). `origin` records who authored the prompt's text and is read-only wherever a
+ * user can reach it:
+ *
+ *   - a USER-authenticated principal (IMS / JWT) always writes `human`; any
+ *     `origin` in the body is IGNORED (never rejected — the derived value is
+ *     authoritative, so the caller loses nothing);
+ *   - a SERVICE principal (e.g. DRS via admin `x-api-key`) is believed: its body
+ *     value is honoured, validated against {@link V2_PROMPT_ORIGINS}, defaulting
+ *     to `human` only when absent or out-of-vocabulary. This is the DRS contract
+ *     (`origin: 'ai'`); dropping it would relabel every generated prompt `human`
+ *     on its next upsert (origin-dimension.md §3 consequence 1).
+ *
+ * This governs CREATE only — `origin` is never patched on update (it is fixed by
+ * the writer that created the row), which the update path enforces by not writing
+ * the column at all.
+ *
+ * @param {unknown} bodyOrigin - the caller-supplied `origin`, or undefined.
+ * @param {boolean} isUserPrincipal - true for an IMS/JWT user request.
+ * @returns {string} the origin to store (`ai` or `human`).
+ */
+export function deriveV2PromptOrigin(bodyOrigin, isUserPrincipal) {
+  if (isUserPrincipal) {
+    return DEFAULT_ORIGIN;
+  }
+  return V2_PROMPT_ORIGINS.includes(/** @type {string} */ (bodyOrigin))
+    ? /** @type {string} */ (bodyOrigin)
+    : DEFAULT_ORIGIN;
+}
+
 /**
  * Per-client cache of whether `prompts.intent` is selectable/writable. Keyed by
  * the PostgREST client so unit tests (fresh mock clients) never bleed state and
@@ -406,7 +445,16 @@ function mapRowToPrompt(row) {
     name: row.name,
     regions: row.regions || [],
     status: row.status || 'active',
-    origin: row.origin || 'human',
+    // Return the stored `origin` verbatim — deliberately NO `|| 'human'` AND no
+    // `?? 'human'` fallback (origin-dimension.md §WP-O2b item 4 / §2.3).
+    // INVARIANT: `prompts.origin` is NOT NULL in production (zero NULLs in
+    // 265,980 rows, §2.3). Any fallback — including nullish-coalescing, which
+    // masks NULL exactly as `||` masks it for a NULL — would silently mislabel a
+    // model-written (`ai`) prompt as `human` were a NULL ever present, the exact
+    // corruption this dimension exists to prevent. Surfacing the raw value is the
+    // fail-loud choice over a fabricated `human`; unlike `source`/`status`, whose
+    // fallbacks are cosmetic, an origin fallback is a correctness hazard.
+    origin: row.origin,
     source: row.source || 'config',
     intent: row.intent ?? null,
     createdAt: row.created_at,
@@ -850,6 +898,12 @@ export async function upsertPrompts({
           status: 'active',
           intent: row.intent ?? match.intent,
           source: match.source ?? source,
+          // `origin` is fixed by the writer that created the row and is never
+          // re-derived on a later write (origin-dimension.md §3): preserve the
+          // stored value across a reactivation. `?? row.origin` is a defensive
+          // fallback for an in-memory/test match without an origin, mirroring
+          // `source` above — not a backfill path (prod has zero NULL origins).
+          origin: match.origin ?? row.origin,
         };
         toUpdate.push(reactivated);
         processed.push({ ...reactivated, prompt_id: promptId });
@@ -859,7 +913,18 @@ export async function upsertPrompts({
     }
 
     if (match) {
-      const updated = { ...row, id: match.id, source: match.source ?? source };
+      // `source` AND `origin` are both immutable on an UPDATE: source names the
+      // producing system, origin names the writer that created the row, and
+      // neither is re-derived on a later write (origin-dimension.md §3). Preserve
+      // the stored values so a user-principal derive of `human` cannot relabel an
+      // existing `ai` prompt. `?? row.*` is the same defensive in-memory/test
+      // fallback used for `source` — not a backfill.
+      const updated = {
+        ...row,
+        id: match.id,
+        source: match.source ?? source,
+        origin: match.origin ?? row.origin,
+      };
       toUpdate.push(updated);
       processed.push({ ...updated, prompt_id: promptId });
     } else {
@@ -1050,9 +1115,10 @@ export async function updatePromptById({
   if (updates.status !== undefined) {
     patch.status = updates.status;
   }
-  if (updates.origin !== undefined) {
-    patch.origin = updates.origin;
-  }
+  // `origin` is deliberately NOT patchable: it is fixed by the writer that
+  // created the row and is never re-derived on update (origin-dimension.md §3
+  // item 3 / §1 item 5). A caller-supplied `origin` in the PATCH body is ignored,
+  // leaving the stored value — including an `ai` prompt's — untouched.
   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

@@ -22,7 +22,7 @@ import {
   buildPromptDto,
   normalizePromptInput,
   createOnePrompt,
-  makeTypeInjector,
+  makePromptTagInjector,
   parseUpdatePromptBody,
   mapLimit,
   publishAffected,
@@ -32,6 +32,7 @@ import {
   BULK_CREATE_CONCURRENCY,
   BULK_PROMPTS_MAX_ITEMS,
 } from './prompts.js';
+import { ORIGIN_VALUE } from '../prompt-tags.js';
 import { resolveProject, buildSliceProjectMap, sliceKey } from '../subworkspace-projects.js';
 import { redactUpstreamMessage } from '../rest-transport.js';
 import { createHeadroomGuard } from '../dynamic-allocation-active.js';
@@ -140,7 +141,15 @@ export async function handleCreatePromptsSubworkspace(
   }
 
   const projectsBySlice = await buildSliceProjectMap(transport, workspaceId, log);
-  const injectComputedType = makeTypeInjector(transport, workspaceId, classifyPromptType, log);
+  // CREATE: user-authenticated write → derived `origin` is `human` (see the
+  // flat-mode twin handleCreatePrompts and origin-dimension.md §3).
+  const injectComputedTags = makePromptTagInjector(
+    transport,
+    workspaceId,
+    classifyPromptType,
+    log,
+    { originValue: ORIGIN_VALUE.HUMAN },
+  );
 
   // PROMPT metering seam (Rainer, live-verified LLMO-6190): the metered write is
   // `createPromptsByIds` (inside `createOnePrompt` below), NOT publish — a disguised-quota 405
@@ -176,8 +185,9 @@ export async function handleCreatePromptsSubworkspace(
     }
     const projectId = String(project.id);
     try {
-      // Unified layer: strip any caller-supplied type + inject the computed one.
-      const typed = await injectComputedType(projectId, input);
+      // Unified layer: strip any caller-supplied type/origin + inject the
+      // computed type and the derived origin (`human`).
+      const typed = await injectComputedTags(projectId, input);
       // LLMO-6190 follow-up: the metered write itself can still 405 as a disguised metered-quota
       // rejection despite the pre-loop sizing above (the live-verified ~9s gateway
       // write-enforcement lag after a JIT top-up) — route it through `headroom.retryOnQuota` (a
@@ -299,8 +309,11 @@ export async function handleUpdatePromptSubworkspace(
   // Recompute the type tag from the NEW text BEFORE any upstream write (see
   // the flat-mode twin): a classification failure aborts cleanly with the
   // prompt completely untouched.
-  const injectComputedType = makeTypeInjector(transport, workspaceId, classifyPromptType, log);
-  const typed = await injectComputedType(projectId, {
+  // No `originValue`: origin is never re-derived on edit (origin-dimension.md §3
+  // item 3); the stored origin the caller echoes rides through untouched. See the
+  // flat-mode twin handleUpdatePrompt.
+  const injectComputedTags = makePromptTagInjector(transport, workspaceId, classifyPromptType, log);
+  const typed = await injectComputedTags(projectId, {
     text: nextText, geoTargetId, tagIds: nextTagIds,
   });