/**
 * Illustrative query builder, not an authentication implementation.
 * POST /indexes/governed-chatbot-chunks/docs/search?api-version=2025-09-01
 *
 * Call only from a trusted backend after token validation, tenant checks,
 * and complete group resolution. Never populate access directly from
 * request JSON or model-generated tool arguments. Types are not proof
 * of authorization; the trusted backend must establish these values.
 */
export type TrustedAccessContext = {
  tenantId: string;
  userOid: string;
  groupOids: readonly string[] | null;
  groupsComplete: boolean;
  appRoles: readonly string[];
};

function normalizeId(value: string): string {
  const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
  if (typeof value !== "string" || !uuid.test(value)) {
    throw new Error("Expected a canonical UUID");
  }
  return value.toLowerCase();
}

export function buildQuery(
  question: string,
  vector: readonly number[],
  access: TrustedAccessContext,
) {
  if (!access || !Array.isArray(access.appRoles) ||
      !access.appRoles.includes("Knowledge.Reader")) {
    throw new Error("Knowledge retrieval is not permitted");
  }
  if (access.groupsComplete !== true || !Array.isArray(access.groupOids)) {
    throw new Error("Access scope could not be resolved");
  }
  const tenant = normalizeId(access.tenantId);
  const principals = ["u:" + normalizeId(access.userOid)];
  for (const group of access.groupOids) {
    principals.push("g:" + normalizeId(group));
  }
  if (typeof question !== "string" || !question.trim()) {
    throw new Error("A question is required");
  }
  if (!Array.isArray(vector) || vector.length !== 1536 ||
      !Array.from(vector).every(value => Number.isFinite(value))) {
    throw new Error("Expected 1536 finite embedding values");
  }

  // UUID validation excludes OData quotes and list delimiters.
  const allowed = [...new Set(principals)].sort().join(",");
  const securityFilter =
    "tenantId eq '" + tenant + "' and isActive eq true " +
    "and aclState eq 'ready' and " +
    "allowedPrincipals/any(p: search.in(p, '" + allowed + "', ','))";

  return {
    search: question,
    filter: securityFilter,
    vectorFilterMode: "preFilter",
    vectorQueries: [{
      kind: "vector", fields: "contentVector", vector: [...vector], k: 50,
    }],
    queryType: "semantic",
    semanticConfiguration: "content-semantic",
    select: "chunkId,documentId,title,content,sourcePath," +
      "sourceVersion,updatedAt,aclVersion",
    top: 5,
  };
}

// Not shown: token verification, authoritative group resolution,
// embedding generation, managed-identity Search authentication,
// current document authorization checks, or Foundry generation.
// Before retrieved text enters model context, recheck access and
// ACL freshness for its documentId. Fail closed on uncertainty.
// This example is for staff knowledge, not patient-record access.