@cap-js/agents 0.9.6 → 0.9.8

package/lib/masking/index.js

@@ -0,0 +1,90 @@
+import cds from "@sap/cds"
+import { randomBytes } from "node:crypto"
+import { toolName as normaliseName } from "../utils/utils.js"
+import { PseudonymStore } from "./store.js"
+import { pseudonymizeToolResult } from "./structured/index.js"
+import anonymizeUnstructured from "./unstructured/index.js"
+
+export function resolvePseudonyms(text) {
+  if (typeof text !== "string") return text
+  return cds.context?.["agent.pseudonyms"]?.resolveText(text) ?? text
+}
+
+/**
+ * Input:  { data, type, seed?, metadata? }
+ * Output: { data, mappings?, metadata: { textAnalysisResults?, seed, type } }
+ */
+export async function pseudonymize({ data, type, seed, metadata }, srv) {
+  const effectiveSeed = seed ?? randomBytes(16).toString("hex")
+  const result = { metadata: { seed: effectiveSeed, type } }
+
+  if (type === "unstructured") {
+    const r = await anonymizeUnstructured(data, effectiveSeed)
+    result.data = r.text
+    if (r.mappings?.length) result.mappings = r.mappings
+    if (r.textAnalysisResults) result.metadata.textAnalysisResults = r.textAnalysisResults
+  } else {
+    // data is a decoded object (caller handles TOON/JSON decode+encode)
+    const toolName = metadata?.toolName
+    const srvName = metadata?.serviceName ?? srv?.name
+    const targetSrv = cds.services?.[srvName] ?? srv
+    const model = targetSrv?.model
+
+    const store = new PseudonymStore(effectiveSeed)
+
+    pseudonymizeToolResult({
+      decoded: data,
+      toolName,
+      cql: metadata?.cql,
+      strictMasking: metadata?.strictMasking ?? false,
+      session: store,
+      srv: targetSrv,
+      model,
+    })
+    result.data = data
+
+    if (store._hashToOriginal.size) result.mappings = [...store._hashToOriginal]
+  }
+
+  return result
+}
+
+export async function ensureSession(checkpointer, threadId) {
+  if (cds.context?.["agent.pseudonyms"]) return
+  const { seed, hashToOriginal } = await readMaskingState(checkpointer, threadId)
+  const session = new PseudonymStore(seed, hashToOriginal)
+  cds.context["agent.pseudonyms"] = session
+}
+
+// REVISIT: Should not read checkpointer, should move into a beforeAgent hook
+async function readMaskingState(checkpointer, thread_id) {
+  if (!checkpointer || !thread_id) return {}
+  try {
+    const tuple = await checkpointer.getTuple({ configurable: { thread_id } })
+    const values = tuple?.checkpoint?.channel_values
+    if (!values) return {}
+    return {
+      seed: values.seed,
+      hashToOriginal: values.hashToOriginal,
+    }
+  } catch {
+    return {}
+  }
+}
+
+// For a remote MCP tool name like "catalogservice_query", strip the service prefix
+// and return { bareName, remoteSrv }.  Returns null for local tools.
+export function resolveRemoteMcpTool(prefixedName) {
+  const cache = cds.context?.__mcpDynamicTools
+  if (!cache) return null
+  for (const { serviceName, tools } of Object.values(cache)) {
+    const prefix = normaliseName(`${serviceName}_`)
+    if (!tools?.some((t) => t.name === prefixedName)) continue
+    // If multiple CAP MCPs are included its possible that one of the CAP MCPs owns query if the agent itself does not expose any entities
+    return {
+      bareName: prefixedName.startsWith(prefix) ? prefixedName.slice(prefix.length) : prefixedName,
+      remoteSrv: cds.services?.[serviceName],
+    }
+  }
+  return null
+}

package/lib/masking/store.js

@@ -0,0 +1,80 @@
+import { createHash, randomBytes } from "node:crypto"
+
+export function generatePseudonymTag(seed, value, category) {
+  const hash = createHash("sha256")
+    .update(seed + String(value))
+    .digest("hex")
+    .slice(0, 16)
+  return `${category}-${hash}`
+}
+
+export class PseudonymStore {
+  constructor(seed, existing = new Map()) {
+    this._seed = seed ?? randomBytes(16).toString("hex")
+    this._hashToOriginal = new Map(existing)
+    this._originalToHash = new Map()
+    // Sort by descending key length so tags ("name-abc12345") are processed
+    // before bare hashes ("abc12345") and win in _originalToHash.
+    for (const [hash, original] of [...existing].sort((a, b) => b[0].length - a[0].length)) {
+      const str = String(original)
+      if (!this._originalToHash.has(str)) this._originalToHash.set(str, hash)
+    }
+    this._sortedOriginalPairs = null
+    this._sortedHashPairs = null
+  }
+
+  pseudonymize(value, propertyName) {
+    const str = String(value)
+    if (this._originalToHash.has(str)) return this._originalToHash.get(str)
+    const tag = generatePseudonymTag(this._seed, str, propertyName)
+    const hash = tag.slice(propertyName.length + 1)
+    this._hashToOriginal.set(tag, str)
+    this._hashToOriginal.set(hash, str)
+    this._originalToHash.set(str, tag)
+    // Invalidate sorted cache; rebuilt lazily on next scrub.
+    this._sortedOriginalPairs = null
+    this._sortedHashPairs = null
+    return tag
+  }
+
+  addMappings(mappings) {
+    if (!mappings?.length) return
+    // Sort by descending key length so tags ("name-abc12345") win over bare hashes ("abc12345").
+    const sorted = [...mappings].sort((a, b) => b[0].length - a[0].length)
+    for (const [hash, original] of sorted) {
+      const str = String(original)
+      const key = String(hash)
+      if (!str || !key || str === key) continue
+      if (!this._hashToOriginal.has(key)) this._hashToOriginal.set(key, str)
+      if (!this._originalToHash.has(str)) this._originalToHash.set(str, key)
+    }
+    this._sortedOriginalPairs = null
+    this._sortedHashPairs = null
+  }
+
+  resolve(hash) {
+    return this._hashToOriginal.get(hash) ?? hash
+  }
+
+  resolveText(text) {
+    if (!text || !this._hashToOriginal.size) return text
+    // tag and ID are registered. First go for tags then ID, else artefacts are left in text
+    this._sortedHashPairs ??= [...this._hashToOriginal].sort((a, b) => b[0].length - a[0].length)
+    let result = String(text)
+    for (const [hash, original] of this._sortedHashPairs) result = result.replaceAll(hash, original)
+    return result
+  }
+
+  scrubText(text) {
+    if (!text || !this._originalToHash.size) return text
+    // Replace longest originals first so a shorter original that is a substring
+    // of a longer one (e.g. "Emily" vs "Emily Brontë") does not corrupt it.
+    this._sortedOriginalPairs ??= [...this._originalToHash].sort(
+      (a, b) => b[0].length - a[0].length,
+    )
+    let result = String(text)
+    for (const [original, hash] of this._sortedOriginalPairs)
+      result = result.replaceAll(original, hash)
+    return result
+  }
+}

package/lib/masking/structured/findElements.js

@@ -0,0 +1,459 @@
+import cds from "@sap/cds"
+
+const PERSONAL_DATA_CACHE = Symbol.for("@cap-js/agents:personalDataPaths")
+
+const STRING_TYPES = new Set(["cds.String", "cds.UUID", "cds.LargeString"])
+const NUMERIC_TYPES = new Set(["cds.Integer", "cds.Integer64", "cds.Decimal", "cds.Double"])
+
+const PD_TAGS = [
+  "@PersonalData.IsPotentiallyPersonal",
+  "@PersonalData.IsPotentiallySensitive",
+  "@Common.Masked",
+]
+
+export function hasPersonalDataAnnotation(element) {
+  return (
+    PD_TAGS.some((a) => element[a] != null && element[a] !== false) ||
+    element["@PersonalData.FieldSemantics"] === "DataSubjectID" ||
+    element["@PersonalData.FieldSemantics"] === "UserID"
+  )
+}
+
+export function shouldHash(el) {
+  if (STRING_TYPES.has(el.type)) return true
+  if (NUMERIC_TYPES.has(el.type)) return !!(el.key || el._foreignKey4)
+  return false
+}
+
+// Returns the set of hashable @PersonalData element names for an entity.
+// strictMasking=true: also includes @Common.Masked:false fields (traces must not expose them).
+//
+// Without a `model`, only top-level scalar/scalar-array elements are returned as plain
+// names (used by join/nav/expand resolution helpers that key on single element names).
+//
+// With a `model`, complex-type elements are resolved recursively and their nested PII is
+// returned as PATH ARRAYS (e.g. ["address","street"], ["address","geo","lat"]), and
+// arrayed structs likewise (["contacts","email"]). Scalar-array PII (annotation on the
+// arrayed element itself, e.g. `nicknames : many String`) is returned as a plain name.
+// pseudonymizeData traverses path arrays and hashes scalar-array elements.
+export function personalDataElements(entityDef, strictMasking = false, model = null) {
+  if (!entityDef?.elements) return new Set()
+  const result = new Set()
+  _collectPaths(entityDef, strictMasking, model, [], result, 0)
+  return result
+}
+
+function _collectPaths(entityDef, strictMasking, model, prefix, out, depth) {
+  if (!entityDef?.elements || depth > 20) return
+  for (const [name, el] of Object.entries(entityDef.elements)) {
+    if (!strictMasking && el["@Common.Masked"] === false) continue
+    const path = [...prefix, name]
+
+    // Scalar (String/UUID or numeric key/FK): hash when annotated PII.
+    if (shouldHash(el)) {
+      if (hasPersonalDataAnnotation(el)) out.add(path.length === 1 ? name : path)
+      continue
+    }
+
+    if (!model) continue // flat mode: only top-level scalars
+
+    // Resolve the element's structural type (named type, inline struct, or arrayed).
+    const resolved = _structOf(el, model)
+    if (resolved?.elements) {
+      _collectPaths(resolved, strictMasking, model, path, out, depth + 1)
+    } else if (resolved?.items) {
+      // Arrayed: struct items recurse; scalar items annotated on the arrayed element → plain path.
+      const itemStruct = _structOf(resolved.items, model)
+      if (itemStruct?.elements) {
+        _collectPaths(itemStruct, strictMasking, model, path, out, depth + 1)
+      } else if (hasPersonalDataAnnotation(el) && shouldHash(resolved.items)) {
+        out.add(path.length === 1 ? name : path)
+      }
+    }
+  }
+}
+
+// Resolve an element/type node to its structural definition:
+// named type reference → model definition; inline struct/array → itself.
+function _structOf(node, model) {
+  if (!node) return null
+  if (node.elements || node.items) return node
+  if (node.type) return model?.definitions?.[node.type] ?? null
+  return null
+}
+
+// Model-level memoization; invalidates automatically when the model object changes.
+function cache(model, key, compute) {
+  model[PERSONAL_DATA_CACHE] ??= {}
+  if (model[PERSONAL_DATA_CACHE][key] !== undefined) return model[PERSONAL_DATA_CACHE][key]
+  return (model[PERSONAL_DATA_CACHE][key] = compute())
+}
+
+// Returns the `returns` type node of an action/function.
+// Case-insensitive fallback handles tool names normalised by toolName() (lowercased).
+export function actionReturnType(model, srv, actionName) {
+  const exact = model.definitions?.[`${srv.name}.${actionName}`]
+  if (exact) return exact.returns ?? null
+  const lower = `${srv.name}.${actionName}`.toLowerCase()
+  const key = Object.keys(model.definitions ?? {}).find((k) => k.toLowerCase() === lower)
+  return key ? (model.definitions[key].returns ?? null) : null
+}
+
+export function hasPersonalDataAnnotations(model, serviceName) {
+  return cache(model, `hasAny:${serviceName}`, () =>
+    Object.entries(model.definitions ?? {}).some(([name, def]) => {
+      if (!name.startsWith(serviceName + ".") && name !== serviceName) return false
+      if (!def.elements) return false
+      return Object.values(def.elements).some((el) => hasPersonalDataAnnotation(el))
+    }),
+  )
+}
+
+export function discoverElementsToBeMasked(model, srv, cql, strictMasking) {
+  if (!cql) return new Set()
+  return cache(model, `query:${srv.name}:${cql}:${strictMasking}`, () => {
+    let cqn
+    try {
+      cqn = cds.parse.cql(cql)
+    } catch {
+      return new Set()
+    }
+    return _discoverFromCqn(model, srv, cqn, strictMasking)
+  })
+}
+
+// Resolve { ref, as? } to its entity def + alias. Returns null when unresolvable.
+function _resolveSource(model, srv, node) {
+  const ref = node?.ref
+  const raw = typeof ref?.[0] === "string" ? ref[0] : ref?.[0]?.id
+  if (!raw) return null
+  const localName = raw.includes(".") ? raw : `${srv.name}.${raw}`
+  const entityDef = model.definitions?.[localName] ?? model.definitions?.[raw]
+  if (!entityDef) return null
+  const alias = node.as ?? raw.split(".").pop()
+  return { alias, entityDef }
+}
+
+// Collect all source entities from a FROM clause into a Map keyed by alias.
+// Handles: plain ref, JOIN ({ join, args }), subquery ({ SELECT }), union-in-FROM ({ SET }).
+// The primary (leading) source is additionally registered under the key `null`, so
+// callers can resolve unqualified refs and unqualified expand roots without knowing
+// the alias — even in joins where the primary source carries an alias.
+function _collectSources(model, srv, from, out = new Map()) {
+  if (!from) return out
+  if (Array.isArray(from.args)) {
+    for (const arg of from.args) _collectSources(model, srv, arg, out)
+    return out
+  }
+  if (from.SELECT) return _collectSources(model, srv, from.SELECT.from, out)
+  if (from.SET) {
+    for (const branch of from.SET.args ?? [])
+      if (branch.SELECT) _collectSources(model, srv, branch.SELECT.from, out)
+    return out
+  }
+  const src = _resolveSource(model, srv, from)
+  if (src) {
+    out.set(src.alias, src)
+    if (!out.has(null)) out.set(null, src) // first resolved source is the primary
+  }
+  return out
+}
+
+// Extract all ref arrays from xpr/func.args nodes (not into SELECT — see _extractSubselects).
+function _extractRefs(node) {
+  if (!node) return []
+  if (Array.isArray(node)) return node.flatMap(_extractRefs)
+  if (typeof node !== "object") return []
+  if (node.SELECT) return []
+  if (node.ref) return [node.ref]
+  if (node.xpr) return _extractRefs(node.xpr)
+  if (node.args) return _extractRefs(node.args)
+  return []
+}
+
+// Extract all scalar subselect nodes ({ SELECT }) from xpr/func.args.
+function _extractSubselects(node) {
+  if (!node) return []
+  if (Array.isArray(node)) return node.flatMap(_extractSubselects)
+  if (typeof node !== "object") return []
+  if (node.SELECT) return [node]
+  const found = []
+  if (node.xpr) found.push(..._extractSubselects(node.xpr))
+  if (node.args) found.push(..._extractSubselects(node.args))
+  return found
+}
+
+// True when a ref resolves to a PII element via annotatedByAlias or nav-path traversal.
+function _isRefPii(ref, annotatedByAlias, primaryEntity, model) {
+  if (!ref?.length) return false
+  const element = ref[ref.length - 1]
+
+  // Unqualified: binds to whichever source has the element.
+  if (ref.length === 1) {
+    for (const annotated of annotatedByAlias.values()) if (annotated.has(element)) return true
+    return false
+  }
+
+  // Qualified: ref[0] is a table alias, or an association path on the primary source.
+  let annotated = annotatedByAlias.get(ref[0])
+  if (!annotated && primaryEntity) {
+    let entityDef = primaryEntity
+    for (let i = 0; i < ref.length - 1 && entityDef; i++) {
+      const assocEl = entityDef.elements?.[ref[i]]
+      entityDef = assocEl?.target ? model.definitions?.[assocEl.target] : undefined
+    }
+    if (entityDef) annotated = personalDataElements(entityDef)
+  }
+  return annotated?.has(element) ?? false
+}
+
+// Recursively walk expand columns under `expandCols` rooted at `entityDef`.
+// Emits path arrays like ["author","contact","email"] into `out` for every PII leaf.
+// assocPath: path segments accumulated so far (e.g. ["author","contact"]).
+function _expandPiiPaths(model, srv, entityDef, expandCols, assocPath, strictMasking, out) {
+  if (!entityDef || !expandCols) return
+  const annotated = personalDataElements(entityDef, strictMasking)
+  for (const expandCol of expandCols) {
+    if (expandCol.SELECT && expandCol.as) {
+      if (_discoverFromCqn(model, srv, expandCol, strictMasking).size > 0)
+        out.add([...assocPath, expandCol.as])
+      continue
+    }
+    const colName = expandCol.ref?.[expandCol.ref.length - 1]
+    if (!colName) continue
+    if (expandCol.expand) {
+      const assocEl = entityDef.elements?.[colName]
+      const targetDef = assocEl?.target ? model.definitions?.[assocEl.target] : undefined
+      _expandPiiPaths(
+        model,
+        srv,
+        targetDef,
+        expandCol.expand,
+        [...assocPath, expandCol.as ?? colName],
+        strictMasking,
+        out,
+      )
+    } else if (annotated.has(colName)) {
+      out.add([...assocPath, expandCol.as ?? colName])
+    }
+  }
+}
+
+// Map a set of inner PII field names through the outer SELECT's columns.
+// `byInnerName`: true → look up col.ref[last] (subquery rename), result key = col.as ?? innerName.
+//                false → look up col.as ?? col.ref[last] directly (union, no rename).
+// SELECT * (or no columns) passes the inner set through unchanged.
+function _mapThroughColumns(columns, innerPii, byInnerName) {
+  if (!columns || columns.some((c) => c === "*")) return innerPii
+  const result = new Set()
+  for (const col of columns) {
+    const lastRef = col.ref?.[col.ref.length - 1]
+    if (byInnerName) {
+      if (lastRef && innerPii.has(lastRef)) result.add(col.as ?? lastRef)
+    } else {
+      const name = col.as ?? lastRef
+      if (name && innerPii.has(name)) result.add(name)
+    }
+  }
+  return result
+}
+
+// Resolve a plain ref column to the PII result keys it contributes.
+// Returns an array: [] none, [name] a scalar/scalar-array PII column, or one-or-more
+// path arrays when the column is a complex/arrayed type carrying nested PII
+// (e.g. SELECT address → [["address","street"], ["address","geo","lat"], ...]).
+// `ctx` carries the per-query lookup state.
+function _resolvePlainRef(col, ctx) {
+  const { model, sources, primaryEntity, strictMasking } = ctx
+  const ref = col.ref
+  const element = ref[ref.length - 1]
+
+  // Find the source entity the column binds to.
+  let entityDef
+  if (ref.length === 1) {
+    // Unqualified: binds to whichever source has the element.
+    for (const [alias, src] of sources) {
+      if (alias === null) continue
+      if (src.entityDef.elements?.[element]) {
+        entityDef = src.entityDef
+        break
+      }
+    }
+  } else {
+    // Qualified: ref[0] is a table alias, or an association path on the primary source.
+    entityDef = sources.get(ref[0])?.entityDef
+    if (!entityDef && primaryEntity) {
+      let walk = primaryEntity
+      for (let i = 0; i < ref.length - 1 && walk; i++) {
+        const assocEl = walk.elements?.[ref[i]]
+        walk = assocEl?.target ? model.definitions?.[assocEl.target] : undefined
+      }
+      entityDef = walk
+    }
+  }
+  const elDef = entityDef?.elements?.[element]
+  if (!elDef) return []
+  if (!strictMasking && elDef["@Common.Masked"] === false) return []
+
+  const outKey = col.as ?? element
+
+  // Scalar (incl. scalar array annotated on the element): single result key.
+  if (shouldHash(elDef)) {
+    return hasPersonalDataAnnotation(elDef) ? [outKey] : []
+  }
+
+  // Complex / arrayed type: collect nested PII as paths under the column's output key.
+  const nested = new Set()
+  _collectComplexPaths(elDef, strictMasking, model, [outKey], nested, 0)
+  return [...nested]
+}
+
+// Walk a single complex/arrayed element's type, emitting path arrays for nested PII.
+function _collectComplexPaths(elDef, strictMasking, model, prefix, out, depth) {
+  if (depth > 20) return
+  const resolved = _structOf(elDef, model)
+  if (resolved?.elements) {
+    for (const [name, child] of Object.entries(resolved.elements)) {
+      if (!strictMasking && child["@Common.Masked"] === false) continue
+      const path = [...prefix, name]
+      if (shouldHash(child)) {
+        if (hasPersonalDataAnnotation(child)) out.add(path)
+      } else {
+        _collectComplexPaths(child, strictMasking, model, path, out, depth + 1)
+      }
+    }
+  } else if (resolved?.items) {
+    const itemStruct = _structOf(resolved.items, model)
+    if (itemStruct?.elements) {
+      _collectComplexPaths(
+        { elements: itemStruct.elements },
+        strictMasking,
+        model,
+        prefix,
+        out,
+        depth + 1,
+      )
+    } else if (hasPersonalDataAnnotation(elDef) && shouldHash(resolved.items)) {
+      out.add(prefix)
+    }
+  }
+}
+
+// Resolve the target entity def reached by walking a ref path from the sources.
+// Unqualified expand root (author { ... }) binds to the primary source.
+function _resolveExpandTarget(col, ctx) {
+  const { model, sources, primaryEntity } = ctx
+  const firstSeg = col.ref.length > 1 ? col.ref[0] : null
+  let targetDef =
+    firstSeg !== null ? (sources.get(firstSeg)?.entityDef ?? primaryEntity) : primaryEntity
+  for (const seg of col.ref) {
+    const assocEl = targetDef?.elements?.[seg]
+    targetDef = assocEl?.target ? model.definitions?.[assocEl.target] : undefined
+  }
+  return targetDef
+}
+
+function _discoverFromCqn(model, srv, cqn, strictMasking) {
+  // Top-level SET: union results from every branch.
+  if (cqn.SET) {
+    const all = new Set()
+    for (const branch of cqn.SET.args ?? [])
+      for (const f of _discoverFromCqn(model, srv, branch, strictMasking)) all.add(f)
+    return all
+  }
+
+  const from = cqn.SELECT?.from
+  const columns = cqn.SELECT?.columns
+
+  // SET in FROM (SELECT name FROM (Books UNION Authors)): union branch results,
+  // then map through outer columns by their output name (no rename at union level).
+  if (from?.SET) {
+    const innerPii = new Set()
+    for (const branch of from.SET.args ?? [])
+      for (const f of _discoverFromCqn(model, srv, branch, strictMasking)) innerPii.add(f)
+    return _mapThroughColumns(columns, innerPii, false)
+  }
+
+  // Subquery FROM: recurse into the inner SELECT, then map through outer columns
+  // by the inner (renamed) field name.
+  if (from?.SELECT) {
+    const innerPii = _discoverFromCqn(model, srv, from, strictMasking)
+    if (innerPii.size) return _mapThroughColumns(columns, innerPii, true)
+  }
+
+  const sources = _collectSources(model, srv, from)
+  const primaryEntity = sources.get(null)?.entityDef
+  // Flat sets (top-level scalar names) for join/nav column resolution.
+  const annotatedByAlias = new Map()
+  for (const [alias, { entityDef }] of sources) {
+    if (alias === null) continue // primary is also stored under its real alias
+    annotatedByAlias.set(alias, personalDataElements(entityDef, strictMasking))
+  }
+
+  const anyAnnotated = [...annotatedByAlias.values()].some((s) => s.size)
+  const hasNavigationOrExpr =
+    columns &&
+    columns.some((c) => {
+      if (!c || typeof c !== "object") return false
+      return (
+        (Array.isArray(c?.ref) && (c.ref.length > 1 || c.expand)) || c.xpr || c.func || c.SELECT
+      )
+    })
+  // A source may have PII only inside complex/arrayed elements (not caught by the flat
+  // set above) — recompute with the model to detect those before bailing out.
+  const anyDeepAnnotated =
+    anyAnnotated ||
+    [...sources].some(
+      ([alias, { entityDef }]) =>
+        alias !== null && personalDataElements(entityDef, strictMasking, model).size,
+    )
+  if (!anyDeepAnnotated && !hasNavigationOrExpr) return new Set()
+
+  // SELECT * — every source's annotated elements, resolving complex/arrayed types
+  // into path arrays so nested PII is masked too.
+  if (!columns || columns.some((c) => c === "*")) {
+    const all = new Set()
+    for (const [alias, { entityDef }] of sources) {
+      if (alias === null) continue
+      for (const n of personalDataElements(entityDef, strictMasking, model)) all.add(n)
+    }
+    return all
+  }
+
+  const ctx = { model, srv, strictMasking, sources, annotatedByAlias, primaryEntity }
+
+  const resultNames = new Set()
+  for (const col of columns) {
+    if (col.expand && col.ref?.length) {
+      // Expand: SELECT author { name } — emits path arrays e.g. ["author","name"]
+      const assocPath = col.as ? [col.as] : [...col.ref]
+      _expandPiiPaths(
+        model,
+        srv,
+        _resolveExpandTarget(col, ctx),
+        col.expand,
+        assocPath,
+        strictMasking,
+        resultNames,
+      )
+    } else if (col.ref?.length) {
+      // Plain ref: scalar → name; complex/arrayed → one or more path arrays.
+      for (const key of _resolvePlainRef(col, ctx)) resultNames.add(key)
+    } else if (col.SELECT && col.as) {
+      // Scalar subselect as column
+      if (_discoverFromCqn(model, srv, col, strictMasking).size > 0) resultNames.add(col.as)
+    } else if ((col.xpr || col.func) && col.as) {
+      // Expression / function: check extracted refs, then nested subselects
+      const byRef = _extractRefs(col).some((ref) =>
+        _isRefPii(ref, annotatedByAlias, primaryEntity, model),
+      )
+      const bySub =
+        !byRef &&
+        _extractSubselects(col).some(
+          (sub) => _discoverFromCqn(model, srv, sub, strictMasking).size > 0,
+        )
+      if (byRef || bySub) resultNames.add(col.as)
+    }
+  }
+  return resultNames
+}