@@ -40,23 +40,29 @@ Following ADR-0001's test (*true for every consumer → shared; specific to one
 
 **Consumers own:**
 - Caching. The durable query-embedding cache (`semantic_query_embedding`) and its key policy (`hash(normalizedText)+model+dims`) live in the data-access helpers/consumer, not the client — staleness/keying is a consumer concern.
-- Model/dimension policy at the call site (the cache key and the stored `vector(N)` column pin the model+dims contract).
+- Model/dimension values come from `SEMANTIC_MATCHING_CONFIG` (`embeddingModel`, `embeddingDims`) in `data-access`, which owns the stored index; consumers import it and pass it as `model` / `dims`. It is a code constant, not env config: the label is persisted on every row and in the cache key, so writer and reader must never disagree, and changing it is a re-embed. `embeddingDims` must match the `vector(N)` columns. The helpers still accept any `model` / `dims`, so a same-dims model change can run the online re-embed below.
 - Translating a client failure into an HTTP response (api-service returns 503; the audit-worker write path degrades best-effort).
 
 ### 4. Semantic-index helpers live in `data-access`, mirroring the URL index
 
 `semantic-index.utils.js` mirrors `url-index.utils.js`: `syncOpportunitySemantic` (full-replace per `source_type`), `lookupOpportunitiesByVectors` (ANN read RPC wrapper, many query vectors per call), the batched `semantic_query_embedding` cache helpers (`getQueryEmbeddings` / `upsertQueryEmbeddings` / `touchQueryEmbeddings`), and `copyEntityVectors` (a thin wrapper over the `wrpc_copy_opportunity_semantic_vectors` **server-side** write RPC — the copy runs as `INSERT … SELECT`, no rows materialized in the caller). Text normalization + hashing live in this layer so a value written always matches a later read/re-sync. **The shared layer stores and reads pre-embedded vectors; it never embeds** — embedding is the writer's (audit-worker's) job via the client above.
 
+**Type registries.** `OPPORTUNITY_SEMANTIC_SOURCE_TYPES` (kinds of embedded text: `topic`, later `claim`) and `OPPORTUNITY_SEMANTIC_ENTITY_TYPES` (opportunity types, from `OPPORTUNITY_TYPES`) are exported from this layer and are the only values the writer stores and the reader accepts; anything else is a `ValidationError`. The reader takes `sourceTypes` (required, non-empty) and optional `entityTypes` (omitted or empty = all), deduped, so a list can never exceed its registry. The DB does not duplicate the registries: the RPC only rejects an empty source-type list and NULL elements. A team that wants its opportunities searchable adds its source kind and/or opportunity type to the registries, indexes with them, and callers opt in by passing them.
+
 ## Consequences
 
 - `gpt-client` gains an embeddings surface and its own `AZURE_EMBEDDING_*` config (documented in its README); the intended cost, not a drawback.
 - The shared embedding model is a cross-repo contract: both the write and read paths must point at the **same deployment**. ANN search is **scoped to one generation** — `lookupOpportunitiesByVectors` (and the `rpc_opportunity_semantic_search` RPC) filter on `model`+`dims`, and the query cache is keyed on `model+dims`. This makes a **same-dims model change an online, forward-only re-embed** (chosen over an atomic swap — see Alternatives): the read path queries the new generation immediately while the write path back-populates it opportunity-by-opportunity on the normal refresh cadence. **Accepted cost:** during the migration window, opportunities not yet re-embedded don't match new-generation queries (reduced recall), self-healing as the backfill completes. A **dimension change** is out of this online path — it needs a new `vector(N)` column and an atomic swap, not a forward-only re-embed.
-- **Deploy ordering:** `lookupOpportunitiesByVectors` calls `rpc_opportunity_semantic_search` with `p_query_embeddings` (a list of vectors) plus `p_model`/`p_dims`, so the data-service release carrying that signature must be deployed **before** any consumer upgrades to this library version — otherwise PostgREST can't resolve the function (`PGRST202`).
+- **Deploy ordering:** `lookupOpportunitiesByVectors` calls `rpc_opportunity_semantic_search` with `p_source_types`/`p_entity_types` (lists) and `p_query_embeddings` (a list of vectors) plus `p_model`/`p_dims`, so the data-service release carrying that signature must be deployed **before** any consumer upgrades to this library version — otherwise PostgREST can't resolve the function (`PGRST202`).
 - Consumers stay thin: they inject the `EmbeddingProvider`, own their cache/status mapping, and call the `data-access` helpers — no matching logic is reimplemented per consumer.
 
 ## Alternatives considered
 
 - **A new `spacecat-shared-embedding-client` package.** Rejected for now: same vendor/auth as `gpt-client`; deferred behind the `EmbeddingProvider` seam so a later extraction is non-breaking.
 - **Overloading `AzureOpenAIClient`.** Rejected: embeddings are a different API surface; a distinct class keeps each client cohesive.
 - **Embedding inside the shared data-access layer.** Rejected: transport/auth belongs in a client (ADR-0001 boundary), and the write side (audit-worker) owns when/what to embed.
+- **Producer-namespaced source types (e.g. `offsite_topic`).** Rejected: `entity_type` already identifies the producer, so namespacing `source_type` would duplicate it. Generic kinds plus an optional `entityTypes` filter keep the two axes separate. Accepted cost: a new producer that indexes `topic` shows up in by-topics results by default unless callers pass `entityTypes`.
+- **A `*` (all types) wildcard.** Rejected: results would change silently whenever a new producer starts indexing, and an exact scan's cost grows with every type included. Callers that want every kind pass `Object.values(OPPORTUNITY_SEMANTIC_SOURCE_TYPES)` explicitly.
+- **Registries enforced in the DB (CHECK/enum).** Rejected: a migration for every new type; the registries live next to the helpers that enforce them.
+- **Embedding model label from env (e.g. derived from `AZURE_EMBEDDING_DEPLOYMENT`).** Rejected: writer and reader have separate env configs, so a mismatch would silently return no matches; a deployment name is an alias, not a model id; and changing the label is a re-embed, which should be a reviewed release.
 - **Atomic-swap migration (full index rebuild + coordinated cutover) instead of the online, generation-scoped re-embed.** Rejected: it would require rebuilding the whole opportunity index and flipping the read path over in lockstep across four repos — high operational risk and coordination cost for a rare event. The chosen online path (ANN search filtered by `model`+`dims`) lets the read path move to the new generation immediately while the write path back-populates on its normal cadence; the accepted cost is reduced recall for not-yet-re-embedded opportunities during the migration window (see Consequences). Atomic swap remains the required approach for a **dimension** change, which the online path deliberately does not cover.
@@ -148,14 +148,19 @@ For the topic vector index (`opportunity_semantic_embedding`) and the global que
 import {
   syncOpportunitySemantic, copyEntityVectors, lookupOpportunitiesByVectors,
   getQueryEmbeddings, upsertQueryEmbeddings, touchQueryEmbeddings,
+  OPPORTUNITY_SEMANTIC_SOURCE_TYPES, OPPORTUNITY_SEMANTIC_ENTITY_TYPES, SEMANTIC_MATCHING_CONFIG,
 } from '@adobe/spacecat-shared-data-access';
 
 const { postgrestClient } = dataAccess.services;
-const scope = { model: 'azure/text-embedding-3-small', dims: 1536 };
+const scope = {
+  model: SEMANTIC_MATCHING_CONFIG.embeddingModel, dims: SEMANTIC_MATCHING_CONFIG.embeddingDims,
+};
+const { TOPIC } = OPPORTUNITY_SEMANTIC_SOURCE_TYPES;
+const { CITED_ANALYSIS } = OPPORTUNITY_SEMANTIC_ENTITY_TYPES;
 
 // writer (needs the postgrest_writer role): full-replace an opportunity's topic vectors
 await syncOpportunitySemantic(postgrestClient, {
-  siteId, entityId, entityType, sourceType: 'topic', sources: [{ text, vector, ...scope }],
+  siteId, entityId, entityType: CITED_ANALYSIS, sourceType: TOPIC, sources: [{ text, vector, ...scope }],
 });
 
 // writer: copy an opportunity's vector rows to another opportunity in the same site
@@ -166,12 +171,17 @@ const cached = await getQueryEmbeddings(postgrestClient, { texts, ...scope });
 await upsertQueryEmbeddings(postgrestClient, { entries: [{ text, vector }], ...scope });
 await touchQueryEmbeddings(postgrestClient, { textHashes, ...scope });
 
-// reader, batched: one best-first list of { entityId, entityType, score } per query vector
+// reader, batched: one best-first list of { entityId, entityType, score } per query vector.
+// entityTypes is optional (omitted or [] searches all entity types).
 const matches = await lookupOpportunitiesByVectors(postgrestClient, {
-  siteId, sourceType: 'topic', vectors, k: 10, minScore: 0.5, ...scope,
+  siteId, sourceTypes: [TOPIC], entityTypes: [CITED_ANALYSIS], vectors, k: 10, minScore: 0.5, ...scope,
 });
 ```
 
+`OPPORTUNITY_SEMANTIC_SOURCE_TYPES` (kinds of embedded text) and `OPPORTUNITY_SEMANTIC_ENTITY_TYPES` (opportunity types) are the registries for `source_type` and `entity_type`: the writer and reader reject any value outside them. To index a new kind or opportunity type, add it to the registry first.
+
+`SEMANTIC_MATCHING_CONFIG` (`embeddingModel`, `embeddingDims`) is the embedding generation the writer and reader both use; pass it as `model` / `dims` rather than hardcoding the values. It is a code constant, not env config, so the two sides can never disagree.
+
 The batched helpers group their calls internally (search in groups of up to 20 vectors, cache reads/touches in groups of 50 hashes), so callers pass whole lists rather than looping per item.
 
 ## Field Mapping Behavior
 
@@ -44,6 +44,9 @@ export {
   SEMANTIC_CHUNK_SIZE,
   QUERY_HASH_CHUNK_SIZE,
   MAX_SOURCE_TEXT_LENGTH,
+  OPPORTUNITY_SEMANTIC_SOURCE_TYPES,
+  OPPORTUNITY_SEMANTIC_ENTITY_TYPES,
+  SEMANTIC_MATCHING_CONFIG,
   normalizeText,
   hashText,
   cleanTopicText,
 
@@ -12,6 +12,8 @@
 
 import { createHash } from 'crypto';
 
+import { OPPORTUNITY_TYPES } from '@adobe/spacecat-shared-utils';
+
 import { DataAccessError, ValidationError } from '../errors/index.js';
 import { DEFAULT_PAGE_SIZE } from './postgrest.utils.js';
 
@@ -39,6 +41,34 @@ export const QUERY_HASH_CHUNK_SIZE = 50;
 /** Max topic/query text length; matches the `source_text` DB CHECK. */
 export const MAX_SOURCE_TEXT_LENGTH = 2048;
 
+/**
+ * Kinds of source text in `opportunity_semantic_embedding.source_type`. The writer and reader
+ * reject any other value; add a kind here before indexing or searching it.
+ */
+export const OPPORTUNITY_SEMANTIC_SOURCE_TYPES = Object.freeze({
+  TOPIC: 'topic',
+});
+
+/**
+ * Opportunity types allowed in `opportunity_semantic_embedding.entity_type`. The writer and
+ * reader reject any other value; add a type here before indexing or filtering by it.
+ */
+export const OPPORTUNITY_SEMANTIC_ENTITY_TYPES = Object.freeze({
+  CITED_ANALYSIS: OPPORTUNITY_TYPES.CITED_ANALYSIS,
+  REDDIT_ANALYSIS: OPPORTUNITY_TYPES.REDDIT_ANALYSIS,
+  YOUTUBE_ANALYSIS: OPPORTUNITY_TYPES.YOUTUBE_ANALYSIS,
+});
+
+/**
+ * The embedding generation every semantic writer and reader uses: stored on each row and part of
+ * the query-cache key. `embeddingDims` must match the data-service `vector(1536)` columns and
+ * CHECKs. A code constant, not env config: writer and reader must never disagree.
+ */
+export const SEMANTIC_MATCHING_CONFIG = Object.freeze({
+  embeddingModel: 'azure/text-embedding-3-small',
+  embeddingDims: 1536,
+});
+
 function assertClient(postgrestClient) {
   if (!postgrestClient || typeof postgrestClient.from !== 'function') {
     throw new ValidationError('postgrestClient is required');
@@ -66,6 +96,34 @@ function assertModel(value) {
   }
 }
 
+function assertAllowed(value, name, registry) {
+  const allowed = Object.values(registry);
+  if (!allowed.includes(value)) {
+    throw new ValidationError(`${name} must be one of: ${allowed.join(', ')}`);
+  }
+}
+
+/**
+ * Validates a type list against its registry and dedups it, so its length never exceeds the
+ * registry's. Omitted/empty returns null (no filter) unless `required`.
+ */
+function toAllowedList(values, name, registry, { required }) {
+  if (values === undefined || values === null || (Array.isArray(values) && values.length === 0)) {
+    if (required) {
+      throw new ValidationError(`${name} must be a non-empty array`);
+    }
+    return null;
+  }
+  if (!Array.isArray(values)) {
+    throw new ValidationError(`${name} must be an array`);
+  }
+  const allowed = Object.values(registry);
+  if (!values.every((value) => allowed.includes(value))) {
+    throw new ValidationError(`${name} must only contain: ${allowed.join(', ')}`);
+  }
+  return [...new Set(values)];
+}
+
 /** Only an empty/omitted `sources` clears; a non-empty input reduced to nothing throws. */
 function assertClearable(sources, entityId, sourceType) {
   const explicitClear = sources === undefined || sources === null
@@ -268,8 +326,9 @@ async function clearEntitySource(postgrestClient, table, siteId, entityId, sourc
  * @param {object} params
  * @param {string} params.siteId - the site the opportunity belongs to
  * @param {string} params.entityId - the opportunity id
- * @param {string} params.entityType - the opportunity type stored on each row
- * @param {string} params.sourceType - the source kind, e.g. `topic`
+ * @param {string} params.entityType - the opportunity type stored on each row, one of
+ *   `OPPORTUNITY_SEMANTIC_ENTITY_TYPES`
+ * @param {string} params.sourceType - the source kind, one of `OPPORTUNITY_SEMANTIC_SOURCE_TYPES`
  * @param {Array<{text: string, vector: number[], model: string, dims: number, sourceId?: string}>}
  *   params.sources - one entry per source text (normalized + hashed here)
  * @returns {Promise<number>} size of the stored set for this (entity, sourceType) after sync
@@ -280,8 +339,8 @@ export async function syncOpportunitySemantic(postgrestClient, {
   assertClient(postgrestClient);
   assertId(siteId, 'siteId');
   assertId(entityId, 'entityId');
-  assertId(entityType, 'entityType');
-  assertId(sourceType, 'sourceType');
+  assertAllowed(entityType, 'entityType', OPPORTUNITY_SEMANTIC_ENTITY_TYPES);
+  assertAllowed(sourceType, 'sourceType', OPPORTUNITY_SEMANTIC_SOURCE_TYPES);
 
   const table = 'opportunity_semantic_embedding';
   const rows = toRows({
@@ -349,7 +408,10 @@ export async function copyEntityVectors(postgrestClient, {
  * @param {object} postgrestClient - `@supabase/postgrest-js` client
  * @param {object} params
  * @param {string} params.siteId - the site to scope the search to
- * @param {string} params.sourceType - the source kind, e.g. `topic`
+ * @param {string[]} params.sourceTypes - source kinds to search, from
+ *   `OPPORTUNITY_SEMANTIC_SOURCE_TYPES` (required, non-empty)
+ * @param {string[]} [params.entityTypes] - opportunity types to narrow to, from
+ *   `OPPORTUNITY_SEMANTIC_ENTITY_TYPES`; omitted or empty searches all
  * @param {number[][]} params.vectors - the query embeddings
  * @param {string} params.model - the model the queries were embedded with
  * @param {number} params.dims - the query embedding dimension
@@ -359,11 +421,12 @@ export async function copyEntityVectors(postgrestClient, {
  *   best-first list per input vector, in input order
  */
 export async function lookupOpportunitiesByVectors(postgrestClient, {
-  siteId, sourceType, vectors, model, dims, k = 10, minScore = 0,
+  siteId, sourceTypes, entityTypes, vectors, model, dims, k = 10, minScore = 0,
 } = {}) {
   assertClient(postgrestClient);
   assertId(siteId, 'siteId');
-  assertId(sourceType, 'sourceType');
+  const sourceTypeList = toAllowedList(sourceTypes, 'sourceTypes', OPPORTUNITY_SEMANTIC_SOURCE_TYPES, { required: true });
+  const entityTypeList = toAllowedList(entityTypes, 'entityTypes', OPPORTUNITY_SEMANTIC_ENTITY_TYPES, { required: false });
   assertModel(model);
   assertDims(dims);
   if (!Array.isArray(vectors)) {
@@ -384,23 +447,24 @@ export async function lookupOpportunitiesByVectors(postgrestClient, {
     // eslint-disable-next-line no-await-in-loop
     const { data, error } = await postgrestClient.rpc(SEMANTIC_SEARCH_RPC, {
       p_site_id: siteId,
-      p_source_type: sourceType,
+      p_source_types: sourceTypeList,
+      p_entity_types: entityTypeList,
       p_query_embeddings: group,
       p_model: model,
       p_dims: dims,
       p_limit: k,
       p_min_score: minScore,
     });
     if (error) {
-      throw new DataAccessError(`Failed semantic search for site ${siteId}`, { siteId, sourceType }, error);
+      throw new DataAccessError(`Failed semantic search for site ${siteId}`, { siteId, sourceTypes: sourceTypeList }, error);
     }
     for (const row of data ?? []) {
       // Checked against this group, not all results, so a bad index can't land in another group.
       const { query_index: queryIndex } = row;
       if (!Number.isInteger(queryIndex) || queryIndex < 0 || queryIndex >= group.length) {
         throw new DataAccessError(
           `Unexpected query_index ${queryIndex} from ${SEMANTIC_SEARCH_RPC}`,
-          { siteId, sourceType },
+          { siteId, sourceTypes: sourceTypeList },
         );
       }
       results[offset + queryIndex].push({