@i4e/invest4edu-access-core 0.31.0 → 0.33.0

package/README.md

@@ -6,6 +6,39 @@ central, unforgettable `account_id` scoping.
 
 Both backends are ESM, so this package ships plain ESM source — no build step.
 
+## 0.32.0 — BREAKING, and it fails silently
+
+`resolveReporteeUserIds` **no longer reads `employees.reporting_manager` as a user id.** It
+reads it only as the manager's employee `_id`, which is the shape BRI-973 migrates the field
+to. This is a breaking change on a 0.x minor, so read the two notes below before upgrading a
+consumer.
+
+**1. Against un-migrated data it returns zero reportees, not an error.** The dual-shape
+widening that carried the rollout is gone. A manager whose rows have not been migrated
+resolves to a self-only scope, and because this function feeds record visibility in
+nfd-api-node and the lead access scope in nfd-api-node-v2, that reads as *"this manager has
+no reportees"* — nothing thrown, nothing logged, just a smaller answer.
+
+So the deploy order is **migrate → verify → bump**, not the other way round. Run
+nfd-api-node's `migrations/verify-reporting-manager-to-employee-id.js` and get a clean
+verdict before the first instance carrying 0.32.0 serves traffic. In a rolling deploy that
+window is real, so the migration must be complete rather than merely started.
+
+Under npm's 0.x caret rules `^0.31.0` will not resolve to 0.32.0, so no consumer is dragged
+across by an install — the ordering risk is entirely a human one.
+
+**2. Callers must pass the FULL employee list.** An `_id` reference only resolves if the row
+carrying it is present, so a pre-filtered list (`{ status: 1 }`, an account scope, anything)
+drops link rows — and what you lose is not the filtered person but everyone beneath them.
+Filter the result instead. `resolveReporteeUserIds` warns once when handed a list in which no
+row carries an `_id` at all, which is the one case where the answer is confidently wrong
+rather than merely narrow.
+
+0.32.0 also moves the entity/role vocabulary — `ENTITY`, `ENTITY_STATUS`,
+`isEntityLoginAllowed`, `conflictingEntityFor`, `ROLE_TYPE_PRIORITY`,
+`CLIENT_APP_ROLE_NAMES` — into this package. It was previously written out three times
+(nfd-api-node, nfd-api-node-v2, nfdui-nextjs) and held together by parity tests.
+
 ## Install
 
 ```
@@ -72,6 +105,15 @@ Model.find(q).setOptions({ skipTenant: true });          // one query
 - `tenantPlugin` (default of `/tenant-plugin`) — the Mongoose plugin
 - `setTenantMode(m)` / `getTenantMode()` — the read ladder
 - `setTenantWriteMode(m)` / `getTenantWriteMode()` — the write ladder
+- `resolveReporteeUserIds(roots, employees, opts)` (`/reportee-tree`) — self + all reportees
+- `ENTITY`, `ENTITY_STATUS`, `isEntityLoginAllowed`, `entityInactiveMessage`,
+  `checkPortalEntityAccess` (`/entity-status`) — which entities permit a login
+- `conflictingEntityFor`, `entityConflictMessage`, `CONFLICTING_ENTITIES`
+  (`/user-entity-link`) — which hats may coexist on one person
+- `ROLE_TYPE_PRIORITY`, `CLIENT_APP_ROLE_NAMES`, `pickPortalRoleName` (`/portal-roles`) —
+  which role names a portal session
+- `normalizeRoute(route)`, `screenForRoute(features, route)` (`/route-screen`) — the screen row
+  a route resolves to, so a `MODULE.SCREEN.ACTION` code is read off the registry, never spelled
 
 ## Not covered
 **Aggregation pipelines** — add an explicit `{ $match: { account_id } }` stage.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@i4e/invest4edu-access-core",
-  "version": "0.31.0",
-  "description": "Shared access-control primitives for NeoFindesk: tenant keystone, role capabilities, reportee tree, feature flags, and the unified access engine (registry schema, snapshot resolver, visibleWhen).",
+  "version": "0.33.0",
+  "description": "Shared access-control primitives for NeoFindesk: tenant keystone, role capabilities, reportee tree, entity/role vocabulary, feature flags, and the unified access engine (registry schema, snapshot resolver, visibleWhen).",
   "type": "module",
   "exports": {
     ".": "./src/index.js",
@@ -9,6 +9,9 @@
     "./tenant-plugin": "./src/tenant-plugin.js",
     "./role-capabilities": "./src/role-capabilities.js",
     "./reportee-tree": "./src/reportee-tree.js",
+    "./entity-status": "./src/entity-status.js",
+    "./user-entity-link": "./src/user-entity-link.js",
+    "./portal-roles": "./src/portal-roles.js",
     "./access-config": "./src/access-config.js",
     "./access-schema": "./src/access-schema.js",
     "./access-resolver": "./src/access-resolver.js",
@@ -17,6 +20,7 @@
     "./entitlement-schema": "./src/entitlement-schema.js",
     "./grid-schema": "./src/grid-schema.js",
     "./route-features": "./src/route-features.js",
+    "./route-screen": "./src/route-screen.js",
     "./subscription-lifecycle": "./src/subscription-lifecycle.js",
     "./entitlement-store": "./src/entitlement-store.js",
     "./proration": "./src/proration.js",

package/src/entity-status.js

@@ -0,0 +1,165 @@
+/**
+ * One definition of "may this entity be used to log in" — @i4e/invest4edu-access-core.
+ *
+ * A person is one `users` row that may link to several entities (partner, client,
+ * employee, manufacturer). Each entity carries its own activation, so switching one off
+ * must not disturb the others: a partner whose client record is disabled still logs into
+ * the portal, and a client whose partner record is disabled still uses the app.
+ * `users.status` stays what it always was — the platform-level block on the person.
+ *
+ * ── Why this lives in the package rather than in each backend ─────────────────────────
+ * It was written twice, in nfd-api-node/src/utils/entity-status.js and its
+ * nfd-api-node-v2 twin, and pinned together by a parity test. That test earned its keep:
+ * it caught two `adminRoles` lists that had already diverged, so the same person resolved
+ * to a different `role_type` depending on which backend served the login. A parity test
+ * fails AFTER someone edits one side and only if it runs, so the copies are the defect and
+ * the test was the symptom. Both backends and the frontend now import from here.
+ *
+ * ── Why the entities disagree with each other ─────────────────────────────────────────
+ * Each collection grew its own convention and none can be normalised without rewriting
+ * live rows:
+ *
+ *   distributors        1 active · 2 inactive · 3 not-yet-verified · 4 rejected
+ *   distributorclients  1 active · 0 inactive, and legacy rows hold the boolean `true`
+ *                       because the schema defaults a Number field to it
+ *   employees           1 active · 2 inactive, no default — legacy rows are undefined
+ *   manufacturers       1 active · 2 inactive, no default, never written after create
+ *
+ * So the vocabulary is per-entity by necessity. What this module guarantees is that every
+ * caller asks the question the same way.
+ */
+
+/** The entity kinds one person can be linked to. These are wire codes. */
+export const ENTITY = {
+  DISTRIBUTOR: 'distributor',
+  CLIENT: 'client',
+  EMPLOYEE: 'employee',
+  MANUFACTURER: 'manufacturer',
+};
+
+/**
+ * The numbers each collection actually stores — see the table above for why they differ.
+ *
+ * `MAPPING` is the odd one out in kind rather than in value: it is a `userentitymappings`
+ * row's own status, saying whether this PERSON may still act through that entity. The
+ * entity statuses say whether the business record is live; `USER` says whether the person
+ * is. Three different questions, and conflating any two of them switches off more than
+ * the caller meant to.
+ */
+export const ENTITY_STATUS = {
+  USER: { ACTIVE: 1, INACTIVE: 2 },
+  DISTRIBUTOR: { ACTIVE: 1, INACTIVE: 2, NOT_YET_VERIFIED: 3, REJECTED: 4 },
+  CLIENT: { ACTIVE: 1, INACTIVE: 0 },
+  EMPLOYEE: { ACTIVE: 1, INACTIVE: 2 },
+  MANUFACTURER: { ACTIVE: 1, INACTIVE: 2 },
+  MAPPING: { ACTIVE: 1, INACTIVE: 2 },
+};
+
+/**
+ * Statuses that still permit a partner login.
+ *
+ * `not_yet_verified` is deliberately included: a self-signed-up partner sits at 3 for the
+ * whole of onboarding and has to reach the complete-profile screens. Treating 3 as "cannot
+ * log in" would lock every draft partner out of the flow they just started. `rejected` is
+ * excluded — before this, rejected partners were stopped only because rejection also
+ * flipped their user row inactive, and that side effect is gone, so the gate states it
+ * directly.
+ */
+const DISTRIBUTOR_LOGIN_STATUSES = [
+  ENTITY_STATUS.DISTRIBUTOR.ACTIVE,
+  ENTITY_STATUS.DISTRIBUTOR.NOT_YET_VERIFIED,
+];
+
+/**
+ * @param {string} entityType one of ENTITY
+ * @param {Object|null} doc   the entity document (needs `status` projected)
+ * @returns {boolean} false only when the entity is explicitly switched off
+ */
+export function isEntityLoginAllowed(entityType, doc) {
+  if (!doc) return false;
+  const { status } = doc;
+
+  switch (entityType) {
+    case ENTITY.DISTRIBUTOR:
+      return DISTRIBUTOR_LOGIN_STATUSES.includes(Number(status));
+
+    case ENTITY.CLIENT:
+      // `true` is not a stand-in for "unknown" here — it is the literal default the
+      // schema wrote onto real rows, and it means active.
+      return status === true || Number(status) === ENTITY_STATUS.CLIENT.ACTIVE;
+
+    case ENTITY.EMPLOYEE:
+      // No schema default, so undefined is the normal shape of an older row rather than
+      // a signal. Only an explicit inactive blocks the login; reading undefined as "off"
+      // would shut out every employee predating the field.
+      return status === undefined || status === null
+        ? true
+        : Number(status) !== ENTITY_STATUS.EMPLOYEE.INACTIVE;
+
+    case ENTITY.MANUFACTURER:
+      return status === undefined || status === null
+        ? true
+        : Number(status) !== ENTITY_STATUS.MANUFACTURER.INACTIVE;
+
+    default:
+      return false;
+  }
+}
+
+/** Message shown when an entity is switched off. Entity-specific so support can tell them apart. */
+export function entityInactiveMessage(entityType) {
+  switch (entityType) {
+    case ENTITY.DISTRIBUTOR:
+      return 'Associated Partnership account is not active. Please contact support for assistance.';
+    case ENTITY.CLIENT:
+      return 'Your client account is inactive. Please contact support.';
+    case ENTITY.EMPLOYEE:
+      return 'Your employee account is inactive. Please contact support for assistance.';
+    case ENTITY.MANUFACTURER:
+      return 'Your manufacturer account is inactive. Please contact support for assistance.';
+    default:
+      return 'Your account is inactive. Please contact support for assistance.';
+  }
+}
+
+/**
+ * Whether a portal session's entities all permit the login, and which one refuses.
+ *
+ * The portal is every hat except client — the client app is a separate surface with its
+ * own gate. A user holding none of them (an admin, a plain business user) has nothing
+ * entity-level to fail on and passes.
+ *
+ * EVERY hat present is examined, not just the first. Partner and employee cannot coexist
+ * on one person, so that pair is safe either way — but manufacturer conflicts with
+ * neither, so a person holding an active partner hat and a switched-off manufacturer hat
+ * would pass a first-hat-only check without the manufacturer ever being looked at.
+ *
+ * Order still matters for the ANSWER rather than for the verdict: partner is reported
+ * ahead of employee and manufacturer, so the message names the hat the person is most
+ * likely on the portal for.
+ *
+ * @param {Object} p
+ * @param {*} [p.distributorId]     the partner this user IS, from ownDistributorIdOf
+ * @param {Object} [p.distributor]  partner doc, `status` projected
+ * @param {Object} [p.employee]     employee doc, `status` projected
+ * @param {Object} [p.manufacturer] manufacturer doc, `status` projected
+ * @returns {{allowed: boolean, entityType?: string, message?: string}}
+ */
+export function checkPortalEntityAccess({ distributorId, distributor, employee, manufacturer }) {
+  const hats = [
+    distributorId ? [ENTITY.DISTRIBUTOR, distributor] : null,
+    employee ? [ENTITY.EMPLOYEE, employee] : null,
+    manufacturer ? [ENTITY.MANUFACTURER, manufacturer] : null,
+  ].filter(Boolean);
+
+  if (!hats.length) return { allowed: true };
+
+  const refused = hats.find(([entityType, doc]) => !isEntityLoginAllowed(entityType, doc));
+  if (refused) {
+    const [entityType] = refused;
+    return { allowed: false, entityType, message: entityInactiveMessage(entityType) };
+  }
+
+  // The hat this session is best described by — the same precedence the list is built in.
+  return { allowed: true, entityType: hats[0][0] };
+}

package/src/index.js

@@ -18,6 +18,23 @@ export {
   resolveCapabilities,
 } from "./role-capabilities.js";
 export { resolveReporteeUserIds } from "./reportee-tree.js";
+export {
+  ENTITY,
+  ENTITY_STATUS,
+  isEntityLoginAllowed,
+  entityInactiveMessage,
+  checkPortalEntityAccess,
+} from "./entity-status.js";
+export {
+  CONFLICTING_ENTITIES,
+  conflictingEntityFor,
+  entityConflictMessage,
+} from "./user-entity-link.js";
+export {
+  CLIENT_APP_ROLE_NAMES,
+  ROLE_TYPE_PRIORITY,
+  pickPortalRoleName,
+} from "./portal-roles.js";
 export {
   DEFAULT_ACCESS_FLAGS,
   ACCESS_FLAG_ENV_NAMES,
@@ -41,6 +58,7 @@ export {
   ACCESS_FEATURE_DEF,
   ACCESS_GRANT_DEF,
 } from "./access-schema.js";
+export { normalizeRoute, screenForRoute } from "./route-screen.js";
 export {
   resolveAccessSnapshot,
   mergeGrants,

package/src/portal-roles.js

@@ -0,0 +1,66 @@
+/**
+ * Which roles belong to which surface, and which one names a portal session.
+ *
+ * One person is one `users` row that may hold a partner role and a client role at the
+ * same time. Permissions resolve as a union across roles, and the frontend collapses the
+ * array to a single `role_type` string — so both "which roles apply here" and "which one
+ * wins" have to be answered deliberately rather than by array order.
+ *
+ * Lives here because it was written three times: nfd-api-node, nfd-api-node-v2 and the
+ * frontend each held the same sixteen names in the same order. The frontend's copy was the
+ * one nothing pinned, and it is also the one where drift is quietest — a wrong `role_type`
+ * renders as missing screens, not as an error.
+ */
+
+/** Roles that exist only for the client app. A portal session never carries these. */
+export const CLIENT_APP_ROLE_NAMES = ['CLIENT_USER'];
+
+/**
+ * Priority order for resolving the single `role_type` a portal session reports.
+ *
+ * Most-privileged first, so a person wearing several hats is described by the strongest.
+ * Partner roles sit ahead of CLIENT_ADMIN deliberately: on the portal, someone who is
+ * both a partner and a client-facing admin is there as the partner.
+ *
+ * Adding a role here is what makes it visible to the frontend's role predicates — a role
+ * missing from this list resolves to an empty `role_type`.
+ */
+export const ROLE_TYPE_PRIORITY = [
+  'SUPER_ADMIN',
+  'BROKER_ADMIN',
+  'MANUFACTURER_ADMIN',
+  'DISTRIBUTOR_ADMIN',
+  'PARTNER_ADMIN',
+  'BASIC_PLAN_PARTNERS',
+  // The default role of every self-signed-up partner. Its absence from the old list is
+  // why they resolved to an empty role_type and the client had to guess positionally.
+  'DRAFT_DISTRIBUTOR_USER',
+  'INTERN_USER',
+  'DISTRIBUTOR_TRIAL',
+  'BROKER_PRODUCT_ADMINS',
+  'BACKOFFICE_USER',
+  'HR_USER',
+  'HR',
+  'PAT_SALES',
+  'SALES_USER',
+  'CLIENT_ADMIN',
+];
+
+/**
+ * The role that names a session, out of every role name held.
+ *
+ * Client-app roles are dropped first: they match no portal predicate, so landing on one
+ * reads as "neither partner nor client" and hides every partner screen. A role outside
+ * the priority list is still better than nothing — it simply cannot be ranked, so the
+ * first remaining one wins.
+ *
+ * @param {string[]} roleNames
+ * @returns {string} the winning role name, or '' when none applies to a portal session
+ */
+export function pickPortalRoleName(roleNames) {
+  const portalNames = (roleNames || [])
+    .filter(Boolean)
+    .filter((name) => !CLIENT_APP_ROLE_NAMES.includes(name));
+
+  return ROLE_TYPE_PRIORITY.find((r) => portalNames.includes(r)) || portalNames[0] || '';
+}

package/src/reportee-tree.js

@@ -3,20 +3,114 @@
  *
  * The one canonical "self + all reportees" traversal, shared by both backends so v1 and v2
  * compose the SAME hierarchy scope. Pure + data-source agnostic: the caller passes a flat
- * employees list `[{ user_id, reporting_manager }]` (v1 feeds the Redis snapshot, v2 the
+ * employees list `[{ _id, user_id, reporting_manager }]` (v1 feeds the Redis snapshot, v2 the
  * `employees` collection) and one-or-more root user ids (delegation passes `[self, ...givers]`).
  *
+ * ── `reporting_manager` is an employee `_id` (BRI-973) ────────────────────────────────
+ * It used to hold the manager's **user id**. It now holds the manager's **employee `_id`**,
+ * so the hierarchy no longer depends on `employees.user_id` and that field can be dropped.
+ *
+ * Through the rollout this accepted both shapes; that widening is gone. Only an `_id` that is
+ * present in the list resolves — an unrecognised reference detaches that manager's downline
+ * rather than being read as a user id, which is the correct reading now that no row should
+ * hold one.
+ *
+ * ── DEPLOY ORDER: migration first, then this version ──────────────────────────────────
+ * This is a BREAKING change to the data this function can read, on a 0.x minor. Against
+ * un-migrated rows it returns ZERO reportees — and since it feeds record visibility and the
+ * lead access scope, that is a silent narrowing of what people can see rather than an error
+ * anyone would notice.
+ *
+ * So: run nfd-api-node's migrations/verify-reporting-manager-to-employee-id.js and get a
+ * clean verdict FIRST, then ship this version. The window that matters is a rolling deploy,
+ * where an upgraded instance and un-migrated rows can coexist for real minutes — the
+ * migration has to be complete before the first instance carrying this code serves traffic,
+ * not merely started.
+ *
+ * Roots and the returned set stay **user ids** throughout, because that is what the callers
+ * compare against (`assigned_rm_id`, `rm_id`). Only the manager reference is translated.
+ *
+ * ── CALLER CONTRACT: pass the manager's own row ───────────────────────────────────────
+ * An employee-id reference can only be resolved if the row carrying that `_id` is in the
+ * list. A user-id reference never needed a lookup, so under the old shape an absent manager
+ * row cost nothing — under the new shape it silently detaches that manager's entire
+ * downline.
+ *
+ * So a caller must feed EVERY employee for linking, and filter unwanted people out of the
+ * RESULT. Feeding a pre-filtered list (`{ status: 1 }`, an account scope, anything) drops
+ * link rows, and what you lose is not the filtered person but everyone beneath them.
+ *
+ * The caller this bites is nfd-api-node's `src/cache/employeeCache.js`, which builds the
+ * hierarchy snapshot. It filtered `{ status: 1 }` and argued the filter was safe because it
+ * "already breaks the chain at a deactivated manager" — true under the old shape, where the
+ * manager's user id was the map key whether or not their row was present, and false under
+ * this one. It now selects every employee and filters the RESULT instead. Any new caller
+ * has to do the same.
+ *
  * @param {string|string[]} roots  root user id(s)
- * @param {Array<{user_id:*, reporting_manager:*}>} employees  flat employee list
+ * @param {Array<{_id?:*, user_id:*, reporting_manager:*}>} employees  flat employee list
+ * @param {Object} [options]
+ * @param {Function} [options.onUnresolvable]  called once when the list carries no `_id` at
+ *   all — see below. Defaults to `console.warn`; pass the app logger to route it properly.
  * @returns {string[]}  de-duplicated reachable set (roots + all reportees) as STRING ids
  */
-export function resolveReporteeUserIds(roots, employees) {
+export function resolveReporteeUserIds(roots, employees, options = {}) {
   const rootIds = (Array.isArray(roots) ? roots : [roots]).filter((id) => id != null).map(String);
 
+  /**
+   * employee `_id` -> that employee's user id.
+   *
+   * Built first and over the whole list, because a manager may appear anywhere in it — a
+   * single pass that resolved as it went would miss any manager listed after their reportee.
+   *
+   * Employees with no `user_id` are still indexed: such a row cannot be a REPORTEE (nothing
+   * to return for them) but it can perfectly well be a MANAGER, and dropping it here would
+   * silently orphan their whole downline. `null` marks "known employee, no portal user".
+   */
+  const userIdByEmployeeId = new Map();
+  for (const emp of employees || []) {
+    if (!emp || emp._id == null) continue;
+    userIdByEmployeeId.set(String(emp._id), emp.user_id == null ? null : String(emp.user_id));
+  }
+
+  /**
+   * A list with no `_id` on any row is the pre-BRI-973 shape, and nothing in it can ever
+   * resolve — every caller gets `[roots]` back, which reads as "this manager has no
+   * reportees" rather than as "this list cannot be understood".
+   *
+   * That is the one failure this cannot leave silent. It is not a degraded answer, it is a
+   * confident wrong one, and it is cheap to tell apart: an employee list of any size with
+   * an empty index means the caller passed the old shape or dropped `_id` from a projection.
+   * A warn here costs nothing on a correct call and turns the worst failure mode into an
+   * obvious one. It does not throw — this sits on the login path, and refusing to resolve a
+   * scope is a harder failure than reporting one.
+   */
+  if ((employees?.length || 0) > 0 && userIdByEmployeeId.size === 0) {
+    const warn = options.onUnresolvable || ((message) => console.warn(message));
+    warn(
+      `[reportee-tree] ${employees.length} employees but not one carries an \`_id\`, so no `
+      + 'reporting_manager reference can resolve and every caller sees zero reportees. The list '
+      + 'is in the pre-BRI-973 shape, or `_id` was dropped from the projection.',
+    );
+  }
+
   const byManager = new Map();
   for (const emp of employees || []) {
     if (!emp || !emp.user_id) continue;
-    const managerId = String(emp.reporting_manager);
+    if (emp.reporting_manager == null) continue;
+
+    const raw = String(emp.reporting_manager);
+    /**
+     * The reference is an employee `_id`; it is translated to that manager's user id.
+     *
+     * `get` rather than the old "fall back to reading it as a user id": an unknown `_id` now
+     * means either a dangling reference or a row the caller filtered out of the list, and
+     * both are conditions to drop the edge on, not to guess about. See the caller contract.
+     */
+    const managerId = userIdByEmployeeId.get(raw);
+    // Unknown reference, or a manager with no portal user — no key to hang reportees on.
+    if (managerId == null) continue;
+
     if (!byManager.has(managerId)) byManager.set(managerId, []);
     byManager.get(managerId).push(String(emp.user_id));
   }

package/src/route-screen.js

@@ -0,0 +1,45 @@
+/**
+ * Route → screen: the join both backends and the action seeder make.
+ *
+ * A screen's `feature_code` is a property of its `access_features` row, and the row is found by
+ * the screen's route. Anything composing `MODULE.SCREEN.ACTION` for a screen must therefore start
+ * from the route and READ the prefix, never spell it. The activity log learned this the hard way:
+ * a prefix guessed as `DISTRIBUTOR_LEADS.DISTRIBUTOR_LEAD` matched no row, and because an unknown
+ * code resolves to rollout "off", every gate composed from it silently never fired.
+ *
+ * Pure, like the rest of this package: the caller hands in the feature rows it already holds
+ * (each backend's in-memory registry, or a raw collection scan in a script) and gets the matching
+ * screen back. One normaliser serves seeding and runtime, so the two cannot disagree on what "the
+ * same route" means.
+ */
+
+/**
+ * Canonical form of a route for comparison: no leading or trailing slashes, lowercase.
+ * `/home/customer/leads/` and `home/Customer/Leads` name the same screen.
+ */
+export function normalizeRoute(route) {
+  return String(route || "")
+    .replace(/^\/+|\/+$/g, "")
+    .toLowerCase();
+}
+
+/**
+ * The `feature_type: 'screen'` row whose route equals `route`, or null.
+ *
+ * Null, never a fabricated code: a route with no screen row means the screen is not registered in
+ * this environment, and the caller must treat that as "no gate can be composed" rather than compose
+ * one no grant will ever match. An empty `features` list (a registry not yet loaded) answers null
+ * too — a caller that must tell "not loaded" from "not registered" checks the registry itself.
+ *
+ * @param {Array<{feature_type?: string, route?: string|null, feature_code: string}>} features
+ * @param {string} route
+ */
+export function screenForRoute(features, route) {
+  const wanted = normalizeRoute(route);
+  if (!wanted || !Array.isArray(features)) return null;
+  return (
+    features.find(
+      (f) => f && f.feature_type === "screen" && f.route && normalizeRoute(f.route) === wanted,
+    ) || null
+  );
+}

package/src/user-entity-link.js

@@ -0,0 +1,58 @@
+/**
+ * Which hats may coexist on one person — @i4e/invest4edu-access-core.
+ *
+ * Historically every entity flow minted its own `users` row, so the same person signing
+ * up as a partner after already being a client was refused outright. One person is now
+ * one row carrying a link per entity, which makes "may this person also be X" a real
+ * question with a real answer — and it has to be the SAME answer in every flow, or the
+ * employee path enforces something the partner path does not.
+ *
+ * Only the rule table lives here. Resolving which hats a person currently wears is each
+ * backend's job: v1 reads `users` columns plus `userentitymappings`, v2 reads its own
+ * narrower projection, and neither shape belongs in a pure package. What must not differ
+ * is the verdict, so the verdict is what is shared.
+ */
+import { ENTITY } from './entity-status.js';
+
+/**
+ * Entities that may not coexist on one person.
+ *
+ * Deliberately minimal: it states the one prohibition the business asked for rather than
+ * enumerating every pair. Employee and partner are mutually exclusive; everything else
+ * that already happens keeps happening — a client links onto an employee today, and
+ * refusing that here would break a live flow.
+ *
+ * Extending this is a line in the table, not a new check somewhere else.
+ */
+export const CONFLICTING_ENTITIES = {
+  [ENTITY.DISTRIBUTOR]: [ENTITY.EMPLOYEE],
+  [ENTITY.EMPLOYEE]: [ENTITY.DISTRIBUTOR],
+  [ENTITY.CLIENT]: [],
+  [ENTITY.MANUFACTURER]: [],
+};
+
+/**
+ * Which already-worn hat, if any, forbids adding this one.
+ *
+ * Takes a plain set of entity types so it stays independent of how they were discovered —
+ * the mapping collection, the legacy columns, or a mix of both all reach the same table.
+ *
+ * @param {string} targetEntity        the hat being added, one of ENTITY
+ * @param {Set<string>|Array} existing the hats already worn
+ * @returns {string|null} the conflicting entity type, or null when the pairing is allowed
+ */
+export function conflictingEntityFor(targetEntity, existing) {
+  const worn = existing instanceof Set ? existing : new Set(existing || []);
+  return (CONFLICTING_ENTITIES[targetEntity] || []).find((e) => worn.has(e)) || null;
+}
+
+/** The refusal message for a pairing the table forbids. Shared so both backends say the same thing. */
+export function entityConflictMessage(targetEntity, conflictingEntity) {
+  if (targetEntity === ENTITY.DISTRIBUTOR && conflictingEntity === ENTITY.EMPLOYEE) {
+    return 'These contact details belong to an employee. An employee cannot also be registered as a partner.';
+  }
+  if (targetEntity === ENTITY.EMPLOYEE && conflictingEntity === ENTITY.DISTRIBUTOR) {
+    return 'These contact details belong to a partner. A partner cannot also be registered as an employee.';
+  }
+  return `These contact details are already registered as a ${conflictingEntity}, which cannot be combined with a ${targetEntity}.`;
+}