@i4e/invest4edu-access-core 0.37.0 → 0.38.0

package/src/client-profile/field-policy.js

@@ -0,0 +1,184 @@
+/**
+ * Personal-details field policy — who may change which client field, per profile type.
+ *
+ * ── Data ─────────────────────────────────────────────────────────────────────────────────────
+ * One row per field in the `clientfieldpolicies` collection:
+ *
+ *   { collection: "distributorclients", field: "dob", section: "identity", class: "personal",
+ *     policy: { main:      { client: "edit", partner: "lock",   employee: "lock", ops: "edit" },
+ *               corporate: { client: "edit", partner: "verify", employee: "lock", ops: "edit" } },
+ *     open_during_onboarding: true, label: "Date of birth", is_active: true }
+ *
+ * `field` is a top-level path; a row covers everything beneath it (`bank` covers `bank.0.ifsc`).
+ * `field: "*"` covers a whole collection (the satellite tables).
+ *
+ * ── Decisions ────────────────────────────────────────────────────────────────────────────────
+ *   edit    — applies now
+ *   verify  — held; the client confirms before it applies (corporate partner edits)
+ *   lock    — refused
+ * A field with no row takes `field_lock.unclassified_field_action` for every caller, so a new
+ * schema field is safe by default. The client always edits their own PERSONAL fields; for
+ * relationship and system fields the row's `client` entry applies (lock when absent) — the app
+ * must never be able to change its own RM, distributor or KYC flags.
+ *
+ * Only CHANGED fields are judged: forms re-send whole records, and an unchanged value is never a
+ * violation. `changedFields` does that comparison.
+ */
+import { CALLER_CLASSES } from "./access.js";
+import { PROFILE_TYPES } from "./settings.js";
+
+export const FIELD_ACTIONS = Object.freeze({ EDIT: "edit", VERIFY: "verify", LOCK: "lock" });
+export const FIELD_CLASSES = Object.freeze({ PERSONAL: "personal", RELATIONSHIP: "relationship", SYSTEM: "system" });
+export const WHOLE_COLLECTION = "*";
+
+const ACTION_VALUES = new Set(Object.values(FIELD_ACTIONS));
+const CALLER_VALUES = Object.values(CALLER_CLASSES);
+const PROFILE_VALUES = Object.values(PROFILE_TYPES);
+
+/**
+ * Validate and index policy rows. Invalid rows are skipped and reported, never thrown.
+ *
+ * @returns {{ index: Map<string, object>, problems: string[] }}  keyed `collection|field`
+ */
+export function buildFieldPolicyIndex(rows = []) {
+  const index = new Map();
+  const problems = [];
+  for (const row of rows) {
+    if (!row || row.is_active === false) continue;
+    const where = `${row.collection}|${row.field}`;
+    if (!row.collection || !row.field) {
+      problems.push(`${where}: collection and field are required`);
+      continue;
+    }
+    if (!Object.values(FIELD_CLASSES).includes(row.class)) {
+      problems.push(`${where}: class must be one of ${Object.values(FIELD_CLASSES).join("|")}`);
+      continue;
+    }
+    const bad = policyProblems(row.policy);
+    if (bad.length) {
+      problems.push(`${where}: ${bad.join("; ")}`);
+      continue;
+    }
+    if (index.has(where)) problems.push(`${where}: duplicate row, the later one wins`);
+    index.set(where, row);
+  }
+  return { index, problems };
+}
+
+/** The row governing one field (exact, then its top-level parent, then the whole collection). */
+export function policyRowFor(index, collection, field) {
+  const top = String(field).split(".")[0];
+  return index.get(`${collection}|${field}`) ?? index.get(`${collection}|${top}`) ?? index.get(`${collection}|${WHOLE_COLLECTION}`) ?? null;
+}
+
+/**
+ * Judge a set of changed fields.
+ *
+ * @param {{ index: Map, collection: string, fields: string[], callerClass: string,
+ *           profileType: string, personalLocked: boolean, settings: object }} input
+ * @returns {{ edit: string[], verify: string[], lock: string[], unclassified: string[],
+ *             outcome: "edit"|"verify"|"lock" }}
+ *   `outcome` is the strictest action across the fields (lock > verify > edit).
+ */
+export function evaluateFieldChanges({ index, collection, fields = [], callerClass, profileType, personalLocked, settings }) {
+  const result = { edit: [], verify: [], lock: [], unclassified: [] };
+  for (const field of fields) {
+    const row = policyRowFor(index, collection, field);
+    let action;
+    if (!row) {
+      result.unclassified.push(field);
+      action = settings?.field_lock?.unclassified_field_action ?? FIELD_ACTIONS.LOCK;
+    } else action = actionFor(row, { callerClass, profileType, personalLocked });
+    result[action].push(field);
+  }
+  result.outcome = result.lock.length ? FIELD_ACTIONS.LOCK : result.verify.length ? FIELD_ACTIONS.VERIFY : FIELD_ACTIONS.EDIT;
+  return result;
+}
+
+/**
+ * Has the personal lock started for this profile? Stamped (`personal_locked_at`) once KYC and the
+ * UCC are complete, per settings; the stamp is the source of truth once present.
+ *
+ * @param {object} profile
+ * @param {{ kycVerified?: boolean, hasUcc?: boolean }} facts  what the backend knows today
+ */
+export function isPersonalLocked(profile, facts = {}, settings) {
+  if (profile?.personal_locked_at) return true;
+  const needKyc = settings?.field_lock?.lock_requires_kyc_verified ?? true;
+  const needUcc = settings?.field_lock?.lock_requires_ucc ?? true;
+  if (!needKyc && !needUcc) return true;
+  return (!needKyc || Boolean(facts.kycVerified)) && (!needUcc || Boolean(facts.hasUcc));
+}
+
+/**
+ * The effective action per policy row for one caller on one profile — what the UI renders.
+ * Keys are `field` for rows of `collection` (or `*` for a whole-collection row).
+ */
+export function effectivePolicyFor({ index, collection, callerClass, profileType, personalLocked }) {
+  const out = {};
+  for (const [key, row] of index) {
+    const [rowCollection, field] = key.split("|");
+    if (collection && rowCollection !== collection) continue;
+    const name = collection ? field : key;
+    out[name] = actionFor(row, { callerClass, profileType, personalLocked });
+  }
+  return out;
+}
+
+/**
+ * Top-level fields whose value changes when `incoming` is applied to `stored`. Only keys present in
+ * `incoming` are considered. Values are compared structurally, with ObjectIds and Dates compared
+ * by their string form so a re-sent id or date is not seen as a change.
+ */
+export function changedFields(stored = {}, incoming = {}, { ignore = [] } = {}) {
+  const skip = new Set(ignore);
+  const changed = [];
+  for (const key of Object.keys(incoming ?? {})) {
+    if (skip.has(key)) continue;
+    if (!sameValue(stored?.[key], incoming[key])) changed.push(key);
+  }
+  return changed;
+}
+
+// ── internals ─────────────────────────────────────────────────────────────────────────────────
+
+/** One row's action for one caller: the client owns personal fields; onboarding is open. */
+function actionFor(row, { callerClass, profileType, personalLocked }) {
+  if (callerClass === CALLER_CLASSES.CLIENT && row.class === FIELD_CLASSES.PERSONAL) return FIELD_ACTIONS.EDIT;
+  if (row.class === FIELD_CLASSES.PERSONAL && !personalLocked && row.open_during_onboarding) return FIELD_ACTIONS.EDIT;
+  return row.policy?.[profileType]?.[callerClass] ?? FIELD_ACTIONS.LOCK;
+}
+
+function policyProblems(policy) {
+  const problems = [];
+  if (!policy || typeof policy !== "object") return ["policy is required"];
+  for (const type of PROFILE_VALUES) {
+    const byCaller = policy[type];
+    if (!byCaller || typeof byCaller !== "object") {
+      problems.push(`policy.${type} is required`);
+      continue;
+    }
+    for (const caller of CALLER_VALUES) {
+      if (caller === CALLER_CLASSES.CLIENT && !(caller in byCaller)) continue;
+      if (!ACTION_VALUES.has(byCaller[caller])) problems.push(`policy.${type}.${caller} must be edit|verify|lock`);
+    }
+  }
+  return problems;
+}
+
+function normalise(v) {
+  if (v === undefined || v === "") return null;
+  if (v instanceof Date) return v.toISOString();
+  if (v && typeof v === "object" && typeof v.toHexString === "function") return v.toHexString();
+  if (Array.isArray(v)) return v.map(normalise);
+  if (v && typeof v === "object") {
+    const out = {};
+    for (const k of Object.keys(v).sort()) out[k] = normalise(v[k]);
+    return out;
+  }
+  return v;
+}
+
+function sameValue(a, b) {
+  return JSON.stringify(normalise(a)) === JSON.stringify(normalise(b));
+}

package/src/client-profile/goals.js

@@ -0,0 +1,76 @@
+/**
+ * Goals on the two-profile model (D6) — who a goal belongs to, who sees it, and what counts.
+ *
+ *   - A goal the CLIENT creates is theirs and approved at once.
+ *   - A goal a PARTNER or EMPLOYEE adds waits for the client (`pending_client`) — visible only to
+ *     its creator and the client, and excluded from totals, projections and prefill until approved.
+ *   - Goals on a CORPORATE profile stay with that profile's corporate distributor(s); corporate
+ *     clients have no app, so nothing waits for approval there.
+ *   - Another distributor sees a goal only once the client shares it (`shared_with`).
+ *
+ * Pure: the backend supplies the caller (class, firm ids, own user ids) and applies the filters.
+ */
+import { CALLER_CLASSES, ACCESS_LEVELS } from "./access.js";
+import { PROFILE_TYPES, isEnforced, isEvaluated } from "./settings.js";
+
+export const GOAL_APPROVAL = Object.freeze({ PENDING: "pending_client", APPROVED: "approved", REJECTED: "rejected" });
+export const GOAL_SHARE = Object.freeze({ REQUESTED: "requested", APPROVED: "approved", REVOKED: "revoked" });
+
+/** Statuses that must never count toward totals, projections or a calculator prefill. */
+export const GOAL_STATUSES_EXCLUDED_FROM_TOTALS = Object.freeze([GOAL_APPROVAL.PENDING, GOAL_APPROVAL.REJECTED]);
+
+/** A query fragment keeping only goals that count (missing status = an older, approved goal). */
+export function countingGoalsFilter() {
+  return { approval_status: { $nin: [...GOAL_STATUSES_EXCLUDED_FROM_TOTALS] } };
+}
+
+/**
+ * The fields a NEW goal is stamped with.
+ * @param {{ actor: { callerClass: string, distributorId?: * }, profileType: string, settings: object }} input
+ * @returns {{ distributor_id: *, approval_status: string }}
+ */
+export function goalCreationStamp({ actor, profileType, settings }) {
+  const distributorId = actor?.callerClass === CALLER_CLASSES.PARTNER ? actor.distributorId ?? null : null;
+  const needsApproval = isEnforced(settings, "goal_approval")
+    && settings?.goals?.partner_goal_requires_approval
+    && actor?.callerClass !== CALLER_CLASSES.CLIENT
+    && !(profileType === PROFILE_TYPES.CORPORATE && settings?.goals?.corporate_goals_stay_with_corporate);
+  return { distributor_id: distributorId, approval_status: needsApproval ? GOAL_APPROVAL.PENDING : GOAL_APPROVAL.APPROVED };
+}
+
+/**
+ * Which of a client's goals this caller may see. `{}` = all (mode off, or the client).
+ *
+ * @param {{ callerClass: string, accessLevel: string, firmDistributorIds?: Array, userIds?: Array,
+ *           profileType?: string, settings: object }} input
+ */
+export function goalVisibilityFilter({ callerClass, accessLevel, firmDistributorIds = [], userIds = [], profileType, settings }) {
+  if (!isEvaluated(settings, "goal_approval")) return {};
+  const notRejected = { approval_status: { $ne: GOAL_APPROVAL.REJECTED } };
+  if (callerClass === CALLER_CLASSES.CLIENT) return notRejected;
+  const ownPending = { approval_status: GOAL_APPROVAL.PENDING, created_by: { $in: [...userIds] } };
+  const approved = { approval_status: { $nin: [...GOAL_STATUSES_EXCLUDED_FROM_TOTALS] } };
+
+  if (callerClass === CALLER_CLASSES.PARTNER) {
+    const firm = [...firmDistributorIds];
+    const arms = [
+      { ...approved, distributor_id: { $in: firm } },
+      { shared_with: { $elemMatch: { distributor_id: { $in: firm }, status: GOAL_SHARE.APPROVED } } },
+      ownPending,
+    ];
+    // Corporate goals stay with the corporate distributor(s) mapped to that profile: the firm arm
+    // above already limits them; nothing else is added for a corporate profile.
+    if (accessLevel === ACCESS_LEVELS.LINKED) return { $or: arms.slice(1).concat({ ...approved, created_by: { $in: [...userIds] } }) };
+    return { $or: arms };
+  }
+
+  // Internal staff: owners see every approved goal plus what they themselves added; a linked
+  // employee sees only what they added.
+  if (accessLevel === ACCESS_LEVELS.FULL) return { $or: [approved, ownPending] };
+  return { created_by: { $in: [...userIds] }, ...notRejected };
+}
+
+/** A share entry the client grants (or a partner requests). */
+export function goalShareEntry({ distributorId, status, by = null, at = new Date() }) {
+  return { distributor_id: distributorId, status, requested_by: by, decided_at: status === GOAL_SHARE.REQUESTED ? null : at };
+}

package/src/client-profile/index.js

@@ -0,0 +1,81 @@
+/**
+ * Client-profile rules — the two-profile model shared by v1 and v2.
+ *
+ * Design and tracker: https://claude.ai/artifact/JrCTutgQkp32r3NeU2uvmk
+ */
+export { CLIENT_PROFILE_ERRORS, CLIENT_PROFILE_ERROR_CODES } from "./errors.js";
+export {
+  CLIENT_PROFILE_COLLECTIONS,
+  CLIENT_PROFILE_SETTINGS_DOC_ID,
+  MODES,
+  PROFILE_TYPES,
+  ATTACH_TRIGGERS,
+  DEFAULT_CLIENT_PROFILE_SETTINGS,
+  CLIENT_PROFILE_SETTING_DESCRIPTIONS,
+  resolveClientProfileSettings,
+  describeClientProfileSettings,
+  modeOf,
+  isEvaluated,
+  isEnforced,
+  messageFor,
+  clientEventSubject,
+} from "./settings.js";
+export {
+  DIRECT_SIDE,
+  TAG_REASONS,
+  sideKeyOf,
+  profileTypeFor,
+  primaryMappingOf,
+  primarySideOf,
+  sidesOf,
+  mappingForSide,
+  isMfProduct,
+  orderSideFor,
+  primaryLockFor,
+  primaryFromLead,
+  withPrimaryLocked,
+} from "./sides.js";
+export {
+  ACCESS_LEVELS,
+  CALLER_CLASSES,
+  MATCH_REASONS,
+  callerClassOf,
+  matchReasonsFor,
+  accessLevelFor,
+  clientAccessFor,
+  linkedViewOf,
+  maskValue,
+} from "./access.js";
+export { MATCH_NOTHING, buildSideFilter, recordMatchesFilter } from "./side-filter.js";
+export { CLIENT_PROFILE_KILL_SWITCH_ENV, createClientProfileConfigStore } from "./config-store.js";
+export {
+  normalisePan,
+  panMatchFilter,
+  newProfileFields,
+  profileTypeForCaller,
+  pickProfileOfType,
+  attachDecision,
+} from "./profiles.js";
+export { createClientProfileService } from "./profile-service.js";
+export { createAttachPlugin } from "./attach-plugin.js";
+export { CHANGE_REQUEST_STATUS, CHANGE_REQUEST_FAILURES, createChangeRequestService } from "./change-requests.js";
+export {
+  GOAL_APPROVAL,
+  GOAL_SHARE,
+  GOAL_STATUSES_EXCLUDED_FROM_TOTALS,
+  countingGoalsFilter,
+  goalCreationStamp,
+  goalVisibilityFilter,
+  goalShareEntry,
+} from "./goals.js";
+export {
+  FIELD_ACTIONS,
+  FIELD_CLASSES,
+  WHOLE_COLLECTION,
+  buildFieldPolicyIndex,
+  policyRowFor,
+  evaluateFieldChanges,
+  isPersonalLocked,
+  effectivePolicyFor,
+  changedFields,
+} from "./field-policy.js";

package/src/client-profile/profile-service.js

@@ -0,0 +1,306 @@
+/**
+ * Profile service — the I/O half of the attach flow, shared by v1 and v2.
+ *
+ * Like the config store, it owns no connection and imports no driver: each backend passes a
+ * `getDb()` returning its native `Db`, plus its config getters. Every write is a single atomic
+ * `updateOne` guarded so that two concurrent actions by the same side or person can never add
+ * the same mapping or link twice.
+ *
+ * Modes (`modes.attach`, `modes.resolve_by_pan`):
+ *   off     — `attach` does nothing; `findExisting` returns null
+ *   audit   — decisions are computed and reported through `onAudit`, nothing is written or changed
+ *   enforce — decisions are applied
+ */
+import { clientEventSubject, isEnforced, isEvaluated } from "./settings.js";
+import { attachDecision, panMatchFilter, pickProfileOfType } from "./profiles.js";
+import { ACCESS_LEVELS, CALLER_CLASSES, callerClassOf, clientAccessFor } from "./access.js";
+import { buildSideFilter } from "./side-filter.js";
+import { FIELD_ACTIONS, evaluateFieldChanges, isPersonalLocked } from "./field-policy.js";
+import { PROFILE_TYPES } from "./settings.js";
+import { goalCreationStamp, goalVisibilityFilter } from "./goals.js";
+import { buildCapabilityMap, resolveCapabilities } from "../role-capabilities.js";
+import { CLIENT_APP_ROLE_NAMES } from "../portal-roles.js";
+
+const CLIENTS = "distributorclients";
+
+/**
+ * @param {{ getDb: Function, getSettings: Function, getSideContext?: Function,
+ *           getVisibilitySets?: (userId) => Promise<{ userIds: Array, sourceDistributorIds: Array }>,
+ *           toId?: (value) => *, onAudit?: (event: object) => void, now?: () => Date }} deps
+ *   `getVisibilitySets` is the backend's own visibility code (self + reportees, source
+ *   distributors); without it an employee is never treated as already seeing a client.
+ *   `toId` converts ids to the stored type (ObjectId); identity by default.
+ */
+export function createClientProfileService({ getDb, getSettings, getSideContext = () => ({}), getVisibilitySets = null, getFieldPolicyIndex = () => new Map(), toId = (v) => v, onAudit = () => {}, emit = null, now = () => new Date() }) {
+  const db = () => {
+    const handle = getDb?.();
+    if (!handle) throw new Error("client-profile service: no database handle");
+    return handle;
+  };
+
+  /** Every ACTIVE profile of a person, by PAN (global: the whole book is one person space). */
+  async function findActiveProfilesByPan(pan, { session, projection } = {}) {
+    const filter = panMatchFilter(pan);
+    if (!filter) return [];
+    return db().collection(CLIENTS).find({ ...filter, status: 1 }, { session, projection }).toArray();
+  }
+
+  /**
+   * The person's existing profile of the type the caller would create, or null.
+   * `mode` tells the caller whether to act on it: "enforce" → show the existing client instead
+   * of creating; "audit" → carry on as before, the match was only reported.
+   */
+  async function findExisting({ pan, profileType, session }) {
+    const settings = getSettings();
+    if (!isEvaluated(settings, "resolve_by_pan")) return { profile: null, mode: "off" };
+    const profile = pickProfileOfType(await findActiveProfilesByPan(pan, { session }), profileType);
+    const mode = isEnforced(settings, "resolve_by_pan") ? "enforce" : "audit";
+    if (profile && mode === "audit") onAudit({ kind: "resolve_by_pan", client_id: profile._id, profile_type: profileType });
+    return { profile, mode };
+  }
+
+  /**
+   * Record the actor on the client after a saved action. Never throws for business reasons —
+   * an attach failure must not fail the order, proposal or upload that triggered it.
+   *
+   * @returns {{ attached: boolean, kind: string, reason: string }}
+   */
+  async function attach({ clientId, actor, via, stamps, session }) {
+    const settings = getSettings();
+    if (!isEvaluated(settings, "attach")) return { attached: false, kind: "none", reason: "mode_off" };
+    const profile = await db().collection(CLIENTS).findOne(
+      { _id: clientId },
+      { session, projection: { distributor_id: 1, distributor_mappings: 1, linked_users: 1 } },
+    );
+    const decision = attachDecision({ profile, actor, via, at: now(), settings, ctx: getSideContext(), stamps });
+    if (decision.kind === "none") return { attached: false, ...decision };
+    if (!isEnforced(settings, "attach")) {
+      onAudit({ kind: "attach", client_id: clientId, decision: decision.kind, reason: decision.reason, via });
+      return { attached: false, kind: decision.kind, reason: "audit" };
+    }
+    const update = decision.kind === "mapping"
+      ? { filter: { _id: clientId, "distributor_mappings.distributor_id": { $ne: decision.entry.distributor_id } }, $push: { distributor_mappings: decision.entry } }
+      : { filter: { _id: clientId, "linked_users.user_id": { $ne: decision.entry.user_id } }, $push: { linked_users: decision.entry } };
+    const res = await db().collection(CLIENTS).updateOne(update.filter, { $push: update.$push }, { session });
+    const attached = res.modifiedCount === 1;
+    if (attached) announceAttach({ clientId, decision, via, settings });
+    return { attached, kind: decision.kind, reason: attached ? decision.reason : "raced" };
+  }
+
+  /**
+   * "A new adviser is linked to you" — to the client, and the primary's side. Fire and forget:
+   * a notification must never fail the order that caused the link.
+   */
+  function announceAttach({ clientId, decision, via, settings }) {
+    if (!emit) return;
+    const entry = decision.entry ?? {};
+    const payload = {
+      client_id: String(clientId),
+      kind: decision.kind,
+      via: via ?? null,
+      distributor_id: entry.distributor_id != null ? String(entry.distributor_id) : null,
+      user_id: entry.user_id != null ? String(entry.user_id) : null,
+    };
+    Promise.resolve()
+      .then(() => emit(settings.events.relationship_attached, payload, clientEventSubject(settings, clientId)))
+      .catch((err) => onAudit({ kind: "attach_event_error", client_id: clientId, message: err?.message }));
+  }
+
+  /**
+   * A partner's firm ids: their own distributor, always, plus whatever the backend's visibility
+   * sets add (its sub-distributors). A backend whose sets omit the caller's own firm must not
+   * leave a partner seeing nothing of their own clients.
+   */
+  function firmIdsOf(actor, sourceDistributorIds = []) {
+    if (!actor?.distributorId) return [];
+    const ids = [actor.distributorId, ...sourceDistributorIds];
+    const seen = new Set();
+    return ids.filter((id) => id !== null && id !== undefined && !seen.has(String(id)) && seen.add(String(id)));
+  }
+
+  /** Role names for a user: userentitymappings.role_id → roles.role_name (users carry none). */
+  async function roleNamesOf(userId, session) {
+    const maps = await db().collection("userentitymappings").find({ user_id: userId, status: { $ne: 0 }, role_id: { $ne: null } }, { session, projection: { role_id: 1 } }).toArray();
+    if (!maps.length) return [];
+    const roles = await db().collection("roles").find({ _id: { $in: maps.map((m) => m.role_id) } }, { session, projection: { role_name: 1 } }).toArray();
+    return roles.map((r) => r.role_name).filter(Boolean);
+  }
+
+  /**
+   * Who is behind a user id, as the rules need it: class (client / partner / ops / employee),
+   * firm, and whether their roles or flag give whole-book access.
+   */
+  async function resolveActor(userId, { session } = {}) {
+    const id = toId(userId);
+    if (!id) return null;
+    const user = await db().collection("users").findOne({ _id: id }, { session, projection: { distributor_id: 1, client_id: 1, employee_id: 1, full_record_access: 1 } });
+    if (!user) return null;
+    const roles = await roleNamesOf(id, session);
+    const capabilityMap = buildCapabilityMap(await db().collection("rolecapabilities").find({}, { session }).toArray());
+    const isClientApp = Boolean(user.client_id) && roles.length > 0 && roles.every((r) => CLIENT_APP_ROLE_NAMES.includes(r));
+    return {
+      userId: id,
+      employeeId: user.employee_id ?? null,
+      distributorId: user.distributor_id ?? null,
+      roles,
+      fullRecordAccess: Boolean(user.full_record_access) || resolveCapabilities(roles, capabilityMap).isFullAccess,
+      callerClass: callerClassOf({ roles, distributorId: user.distributor_id, isClientApp }, getSettings()),
+    };
+  }
+
+  /** Can this internal actor already see the client with FULL access? */
+  async function isAlreadyVisible(actor, clientId, session) {
+    if (actor.fullRecordAccess) return true;
+    if (!getVisibilitySets) return false;
+    const client = await db().collection(CLIENTS).findOne({ _id: clientId }, { session });
+    if (!client) return false;
+    const { userIds = [], sourceDistributorIds = [] } = (await getVisibilitySets(actor.userId)) ?? {};
+    const { level } = clientAccessFor(client, { userIds, sourceDistributorIds, houseDistributorIds: getSideContext().houseDistributorIds }, getSettings());
+    return level === ACCESS_LEVELS.FULL;
+  }
+
+  /**
+   * Record the person behind `userId` on the client after a saved action. Resolves the actor,
+   * checks existing visibility for employees, then `attach`. Never throws.
+   */
+  async function attachUser({ clientId, userId, via, stamps, session } = {}) {
+    try {
+      if (!isEvaluated(getSettings(), "attach")) return { attached: false, kind: "none", reason: "mode_off" };
+      const cid = toId(clientId);
+      if (!cid || !userId) return { attached: false, kind: "none", reason: "missing_ids" };
+      const actor = await resolveActor(userId, { session });
+      if (!actor) return { attached: false, kind: "none", reason: "unknown_user" };
+      if (actor.callerClass !== CALLER_CLASSES.PARTNER && actor.callerClass !== CALLER_CLASSES.CLIENT) {
+        actor.alreadyVisible = await isAlreadyVisible(actor, cid, session);
+      }
+      return await attach({ clientId: cid, actor, via, stamps, session });
+    } catch (err) {
+      onAudit({ kind: "attach_error", client_id: clientId, message: err.message });
+      return { attached: false, kind: "none", reason: "error" };
+    }
+  }
+
+  /**
+   * What this caller may see of the records filed on one client: the side filter for their access
+   * to it (`{}` for owners, whole-book staff and the client; the firm's side for a partner; only
+   * their own placements for a linked user). `{}` when the mode is off or on any failure (today's
+   * behaviour); in audit, `{}` plus the decision reported through onAudit.
+   *
+   * @returns {Promise<{ filter: object, applied: boolean, level: string|null }>}
+   */
+  async function sideFilterFor({ userId, clientId, fields } = {}) {
+    const none = { filter: {}, applied: false, level: null };
+    try {
+      const settings = getSettings();
+      if (!isEvaluated(settings, "side_filter")) return none;
+      const cid = toId(clientId);
+      if (!userId || !cid) return none;
+      const client = await db().collection(CLIENTS).findOne({ _id: cid });
+      const actor = await resolveActor(userId);
+      if (!client || !actor) return none;
+      const { userIds = [], sourceDistributorIds = [] } = (getVisibilitySets ? await getVisibilitySets(actor.userId) : null) ?? {};
+      const firm = firmIdsOf(actor, sourceDistributorIds);
+      const { level } = clientAccessFor(client, {
+        userIds,
+        sourceDistributorIds,
+        firmDistributorIds: firm,
+        fullRecordAccess: actor.fullRecordAccess,
+        houseDistributorIds: getSideContext().houseDistributorIds,
+      }, settings);
+      const result = buildSideFilter({ callerClass: actor.callerClass, accessLevel: level, firmDistributorIds: firm.length ? firm : sourceDistributorIds, userIds, fields, settings });
+      if (!result.applied && Object.keys(result.decided).length) onAudit({ kind: "side_filter", client_id: clientId, decided: result.decided });
+      return { filter: result.filter, applied: result.applied, level };
+    } catch (err) {
+      onAudit({ kind: "side_filter_error", client_id: clientId, message: err.message });
+      return none;
+    }
+  }
+
+  /**
+   * Personal-details lock (D5): may this caller change these fields of this client?
+   *
+   *   outcome "edit"   — go ahead
+   *   outcome "verify" — the `verify` fields must be confirmed by the client (corporate partner);
+   *                      any `edit` fields may still be applied now
+   *   outcome "lock"   — refuse; `lock` names the fields
+   *
+   * `modes.field_lock` off → always edit. audit → the real decision is reported through onAudit
+   * and the outcome returned is edit. The lock starts at `personal_locked_at`, or — before the
+   * stamp — once KYC and a UCC exist on the client or its active investor profiles.
+   *
+   * @returns {Promise<{ outcome: string, edit: string[], verify: string[], lock: string[],
+   *                     unclassified: string[], applied: boolean, actor: object|null,
+   *                     profile: object|null }>}
+   */
+  async function evaluatePersonalEdit({ userId, clientId, collection = CLIENTS, fields = [], session } = {}) {
+    const allowAll = (extra = {}) => ({ outcome: FIELD_ACTIONS.EDIT, edit: fields, verify: [], lock: [], unclassified: [], applied: false, actor: null, profile: null, ...extra });
+    const settings = getSettings();
+    if (!isEvaluated(settings, "field_lock") || !fields.length) return allowAll();
+    const cid = toId(clientId);
+    const profile = cid ? await db().collection(CLIENTS).findOne({ _id: cid }, { session, projection: { profile_type: 1, personal_locked_at: 1, is_kyc_verified: 1, mf_ucc_code: 1, distributor_id: 1 } }) : null;
+    const actor = userId ? await resolveActor(userId, { session }) : null;
+    if (!profile || !actor) return allowAll({ actor, profile });
+    let personalLocked = Boolean(profile.personal_locked_at);
+    if (!personalLocked) {
+      const investor = await db().collection("clientinvestorprofiles").findOne(
+        { client_id: cid, is_active: { $ne: false }, is_read_only_copy: { $ne: true }, "mf_details.ucc_code": { $nin: [null, ""] } },
+        { session, projection: { "mf_details.mf_kyced": 1 } },
+      );
+      personalLocked = isPersonalLocked(profile, {
+        kycVerified: Boolean(profile.is_kyc_verified) || investor?.mf_details?.mf_kyced === true,
+        hasUcc: Boolean(profile.mf_ucc_code) || Boolean(investor),
+      }, settings);
+    }
+    const result = evaluateFieldChanges({
+      index: getFieldPolicyIndex(),
+      collection,
+      fields,
+      callerClass: actor.callerClass,
+      profileType: profile.profile_type ?? PROFILE_TYPES.MAIN,
+      personalLocked,
+      settings,
+    });
+    if (!isEnforced(settings, "field_lock")) {
+      if (result.outcome !== FIELD_ACTIONS.EDIT || result.unclassified.length) {
+        onAudit({ kind: "field_lock", client_id: clientId, caller: actor.callerClass, outcome: result.outcome, lock: result.lock, verify: result.verify, unclassified: result.unclassified });
+      }
+      return allowAll({ actor, profile });
+    }
+    return { ...result, applied: true, actor, profile };
+  }
+
+  /**
+   * Goals (D6): for this caller on this client, the filter over the client's goals they may see
+   * and the stamp a goal they create gets. Mode off → `{}` and an approved, untagged stamp.
+   */
+  async function goalContextFor({ userId, clientId } = {}) {
+    const settings = getSettings();
+    const open = { visibility: {}, stamp: { distributor_id: null, approval_status: "approved" }, actor: null };
+    try {
+      const actor = userId ? await resolveActor(userId) : null;
+      const cid = toId(clientId);
+      const client = cid ? await db().collection(CLIENTS).findOne({ _id: cid }) : null;
+      if (!actor || !client) return open;
+      const profileType = client.profile_type ?? PROFILE_TYPES.MAIN;
+      const { userIds = [], sourceDistributorIds = [] } = (getVisibilitySets ? await getVisibilitySets(actor.userId) : null) ?? {};
+      const firm = firmIdsOf(actor, sourceDistributorIds);
+      const { level } = clientAccessFor(client, {
+        userIds,
+        sourceDistributorIds,
+        firmDistributorIds: firm,
+        fullRecordAccess: actor.fullRecordAccess,
+        houseDistributorIds: getSideContext().houseDistributorIds,
+      }, settings);
+      return {
+        actor,
+        visibility: goalVisibilityFilter({ callerClass: actor.callerClass, accessLevel: level, firmDistributorIds: firm.length ? firm : sourceDistributorIds, userIds: [...userIds, actor.userId], profileType, settings }),
+        stamp: goalCreationStamp({ actor, profileType, settings }),
+      };
+    } catch (err) {
+      onAudit({ kind: "goal_context_error", client_id: clientId, message: err.message });
+      return open;
+    }
+  }
+
+  return Object.freeze({ findActiveProfilesByPan, findExisting, attach, attachUser, resolveActor, sideFilterFor, evaluatePersonalEdit, goalContextFor });
+}