@i4e/invest4edu-access-core 0.32.0 → 0.33.0

package/src/proration.js

@@ -1,155 +1,155 @@
-/**
- * Proration — what the unused part of a running term is worth when someone upgrades.
- *
- * Without it, an upgrade STACKS: the new term is appended to the current end date, so the days
- * already paid for on the smaller plan sit behind the new one, unusable at the new tier. The
- * customer quietly loses that value and nothing on screen says so.
- *
- * The POLICY is configuration, not code — mode, basis, rounding, cap and scope all arrive from
- * the caller (platform default < plan < service), so changing how proration works is an edit
- * rather than a deploy. This module is only the arithmetic, kept pure so it can be tested
- * without a database, a clock or a subscription.
- *
- * ── The rules that are NOT configurable, because getting them wrong invents money ────────────
- *   · credit can never exceed what was actually paid for the current term
- *   · credit can never exceed the new plan's price (a purchase must not become negative)
- *   · rounding is toward the CUSTOMER paying more, never less — we do not credit value that was
- *     not paid for
- *   · a term that has not started, or has already ended, is worth nothing
- */
-
-/** Every knob, with the conservative answer as the default. */
-export const PRORATION_DEFAULTS = {
-  /**
-   *   none    — today's behaviour: no credit, the new term stacks on the old end date
-   *   daily   — unused days ÷ total days
-   *   monthly — whole unused months only; a part-month counts for nothing
-   *   points  — no cash credit; the unused value is returned as reward points instead
-   */
-  mode: "none",
-  /** Ceiling on the credit as a percentage of the new plan's price. 100 = up to the full price. */
-  cap_percent: 100,
-  /** Apply when the PLAN changes, and/or when only the billing cycle changes. */
-  on_plan_change: true,
-  on_cycle_change: false,
-};
-
-const MS_PER_DAY = 24 * 60 * 60 * 1000;
-
-/** Whole days between two instants, never negative. */
-function daysBetween(from, to) {
-  const ms = new Date(to).getTime() - new Date(from).getTime();
-  return ms <= 0 ? 0 : Math.floor(ms / MS_PER_DAY);
-}
-
-/** Whole months remaining — a part-month is worth nothing under `monthly`. */
-function wholeMonthsBetween(from, to) {
-  const a = new Date(from);
-  const b = new Date(to);
-  if (b <= a) return 0;
-  let months = (b.getFullYear() - a.getFullYear()) * 12 + (b.getMonth() - a.getMonth());
-  if (b.getDate() < a.getDate()) months -= 1;
-  return months > 0 ? months : 0;
-}
-
-/**
- * Merge policy layers. Later wins, and only for keys it actually specifies — a plan that sets
- * only `mode` must not silently reset the cap someone configured globally.
- */
-export function resolveProrationPolicy(...layers) {
-  const out = { ...PRORATION_DEFAULTS };
-  for (const layer of layers) {
-    if (!layer || typeof layer !== "object") continue;
-    for (const k of Object.keys(PRORATION_DEFAULTS)) {
-      if (layer[k] !== undefined && layer[k] !== null) out[k] = layer[k];
-    }
-  }
-  return out;
-}
-
-/**
- * What the unused remainder of the current term is worth, in PAISE.
- *
- * @param {object}  a
- * @param {number}  a.paidAmount    what was paid for the CURRENT term (paise, ex-tax)
- * @param {Date}    a.periodStart   when the current term began
- * @param {Date}    a.periodEnd     when it ends (null/absent ⇒ open-ended ⇒ nothing to prorate)
- * @param {Date}    a.now           the moment of the change
- * @param {number}  a.newPlanPrice  price of what they are moving to (paise, ex-tax) — the cap
- * @param {boolean} a.isCycleChange true when the plan is unchanged and only the cycle differs
- * @param {object}  a.policy        resolved policy (see resolveProrationPolicy)
- * @returns {{credit:number, as_points:boolean, reason:string, days_remaining:number,
- *            days_total:number, mode:string}}
- */
-export function prorate({
-  paidAmount = 0,
-  periodStart,
-  periodEnd,
-  now = new Date(),
-  newPlanPrice = 0,
-  isCycleChange = false,
-  policy = PRORATION_DEFAULTS,
-} = {}) {
-  const p = resolveProrationPolicy(policy);
-  const nil = (reason) => ({
-    credit: 0, as_points: false, reason, mode: p.mode, days_remaining: 0, days_total: 0,
-  });
-
-  if (p.mode === "none") return nil("proration is off");
-  if (isCycleChange && !p.on_cycle_change) return nil("cycle changes are not prorated");
-  if (!isCycleChange && !p.on_plan_change) return nil("plan changes are not prorated");
-
-  // An open-ended term (the provisioned default) has no remainder to value: nothing was paid for
-  // a period that does not end.
-  if (!periodEnd) return nil("term has no end date");
-  if (!(paidAmount > 0)) return nil("nothing was paid for the current term");
-
-  const daysTotal = daysBetween(periodStart, periodEnd);
-  const daysRemaining = daysBetween(now, periodEnd);
-  if (daysTotal <= 0) return nil("term length is zero");
-  if (daysRemaining <= 0) return nil("term has already ended");
-
-  let credit;
-  if (p.mode === "monthly") {
-    const monthsRemaining = wholeMonthsBetween(now, periodEnd);
-    const monthsTotal = wholeMonthsBetween(periodStart, periodEnd);
-    if (monthsTotal <= 0 || monthsRemaining <= 0) {
-      return { ...nil("less than a whole month remains"), days_remaining: daysRemaining, days_total: daysTotal };
-    }
-    credit = Math.floor((paidAmount * monthsRemaining) / monthsTotal);
-  } else {
-    // daily, and the basis for `points` too — the difference is only in how it is returned.
-    credit = Math.floor((paidAmount * daysRemaining) / daysTotal);
-  }
-
-  // Never more than was paid. Floating-point and clock skew both make this reachable.
-  credit = Math.min(credit, paidAmount);
-
-  /**
-   * The cap. Without it, a long unused term can exceed the new plan's price and the purchase
-   * goes to zero or negative — the customer upgrades for free, or we owe them money for taking
-   * a bigger plan. Applies to the cash credit only; points are a separate liability that does
-   * not have to fit inside this purchase.
-   */
-  if (p.mode !== "points") {
-    const ceiling = Math.floor((newPlanPrice * Math.max(0, Math.min(100, p.cap_percent))) / 100);
-    if (credit > ceiling) {
-      credit = ceiling;
-    }
-  }
-
-  if (credit <= 0) return { ...nil("nothing to credit"), days_remaining: daysRemaining, days_total: daysTotal };
-
-  return {
-    credit,
-    as_points: p.mode === "points",
-    reason: p.mode === "points"
-      ? `${daysRemaining} unused day(s) returned as points`
-      : `${daysRemaining} of ${daysTotal} day(s) unused`,
-    mode: p.mode,
-    days_remaining: daysRemaining,
-    days_total: daysTotal,
-  };
-}
-
-export default { prorate, resolveProrationPolicy, PRORATION_DEFAULTS };
+/**
+ * Proration — what the unused part of a running term is worth when someone upgrades.
+ *
+ * Without it, an upgrade STACKS: the new term is appended to the current end date, so the days
+ * already paid for on the smaller plan sit behind the new one, unusable at the new tier. The
+ * customer quietly loses that value and nothing on screen says so.
+ *
+ * The POLICY is configuration, not code — mode, basis, rounding, cap and scope all arrive from
+ * the caller (platform default < plan < service), so changing how proration works is an edit
+ * rather than a deploy. This module is only the arithmetic, kept pure so it can be tested
+ * without a database, a clock or a subscription.
+ *
+ * ── The rules that are NOT configurable, because getting them wrong invents money ────────────
+ *   · credit can never exceed what was actually paid for the current term
+ *   · credit can never exceed the new plan's price (a purchase must not become negative)
+ *   · rounding is toward the CUSTOMER paying more, never less — we do not credit value that was
+ *     not paid for
+ *   · a term that has not started, or has already ended, is worth nothing
+ */
+
+/** Every knob, with the conservative answer as the default. */
+export const PRORATION_DEFAULTS = {
+  /**
+   *   none    — today's behaviour: no credit, the new term stacks on the old end date
+   *   daily   — unused days ÷ total days
+   *   monthly — whole unused months only; a part-month counts for nothing
+   *   points  — no cash credit; the unused value is returned as reward points instead
+   */
+  mode: "none",
+  /** Ceiling on the credit as a percentage of the new plan's price. 100 = up to the full price. */
+  cap_percent: 100,
+  /** Apply when the PLAN changes, and/or when only the billing cycle changes. */
+  on_plan_change: true,
+  on_cycle_change: false,
+};
+
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+
+/** Whole days between two instants, never negative. */
+function daysBetween(from, to) {
+  const ms = new Date(to).getTime() - new Date(from).getTime();
+  return ms <= 0 ? 0 : Math.floor(ms / MS_PER_DAY);
+}
+
+/** Whole months remaining — a part-month is worth nothing under `monthly`. */
+function wholeMonthsBetween(from, to) {
+  const a = new Date(from);
+  const b = new Date(to);
+  if (b <= a) return 0;
+  let months = (b.getFullYear() - a.getFullYear()) * 12 + (b.getMonth() - a.getMonth());
+  if (b.getDate() < a.getDate()) months -= 1;
+  return months > 0 ? months : 0;
+}
+
+/**
+ * Merge policy layers. Later wins, and only for keys it actually specifies — a plan that sets
+ * only `mode` must not silently reset the cap someone configured globally.
+ */
+export function resolveProrationPolicy(...layers) {
+  const out = { ...PRORATION_DEFAULTS };
+  for (const layer of layers) {
+    if (!layer || typeof layer !== "object") continue;
+    for (const k of Object.keys(PRORATION_DEFAULTS)) {
+      if (layer[k] !== undefined && layer[k] !== null) out[k] = layer[k];
+    }
+  }
+  return out;
+}
+
+/**
+ * What the unused remainder of the current term is worth, in PAISE.
+ *
+ * @param {object}  a
+ * @param {number}  a.paidAmount    what was paid for the CURRENT term (paise, ex-tax)
+ * @param {Date}    a.periodStart   when the current term began
+ * @param {Date}    a.periodEnd     when it ends (null/absent ⇒ open-ended ⇒ nothing to prorate)
+ * @param {Date}    a.now           the moment of the change
+ * @param {number}  a.newPlanPrice  price of what they are moving to (paise, ex-tax) — the cap
+ * @param {boolean} a.isCycleChange true when the plan is unchanged and only the cycle differs
+ * @param {object}  a.policy        resolved policy (see resolveProrationPolicy)
+ * @returns {{credit:number, as_points:boolean, reason:string, days_remaining:number,
+ *            days_total:number, mode:string}}
+ */
+export function prorate({
+  paidAmount = 0,
+  periodStart,
+  periodEnd,
+  now = new Date(),
+  newPlanPrice = 0,
+  isCycleChange = false,
+  policy = PRORATION_DEFAULTS,
+} = {}) {
+  const p = resolveProrationPolicy(policy);
+  const nil = (reason) => ({
+    credit: 0, as_points: false, reason, mode: p.mode, days_remaining: 0, days_total: 0,
+  });
+
+  if (p.mode === "none") return nil("proration is off");
+  if (isCycleChange && !p.on_cycle_change) return nil("cycle changes are not prorated");
+  if (!isCycleChange && !p.on_plan_change) return nil("plan changes are not prorated");
+
+  // An open-ended term (the provisioned default) has no remainder to value: nothing was paid for
+  // a period that does not end.
+  if (!periodEnd) return nil("term has no end date");
+  if (!(paidAmount > 0)) return nil("nothing was paid for the current term");
+
+  const daysTotal = daysBetween(periodStart, periodEnd);
+  const daysRemaining = daysBetween(now, periodEnd);
+  if (daysTotal <= 0) return nil("term length is zero");
+  if (daysRemaining <= 0) return nil("term has already ended");
+
+  let credit;
+  if (p.mode === "monthly") {
+    const monthsRemaining = wholeMonthsBetween(now, periodEnd);
+    const monthsTotal = wholeMonthsBetween(periodStart, periodEnd);
+    if (monthsTotal <= 0 || monthsRemaining <= 0) {
+      return { ...nil("less than a whole month remains"), days_remaining: daysRemaining, days_total: daysTotal };
+    }
+    credit = Math.floor((paidAmount * monthsRemaining) / monthsTotal);
+  } else {
+    // daily, and the basis for `points` too — the difference is only in how it is returned.
+    credit = Math.floor((paidAmount * daysRemaining) / daysTotal);
+  }
+
+  // Never more than was paid. Floating-point and clock skew both make this reachable.
+  credit = Math.min(credit, paidAmount);
+
+  /**
+   * The cap. Without it, a long unused term can exceed the new plan's price and the purchase
+   * goes to zero or negative — the customer upgrades for free, or we owe them money for taking
+   * a bigger plan. Applies to the cash credit only; points are a separate liability that does
+   * not have to fit inside this purchase.
+   */
+  if (p.mode !== "points") {
+    const ceiling = Math.floor((newPlanPrice * Math.max(0, Math.min(100, p.cap_percent))) / 100);
+    if (credit > ceiling) {
+      credit = ceiling;
+    }
+  }
+
+  if (credit <= 0) return { ...nil("nothing to credit"), days_remaining: daysRemaining, days_total: daysTotal };
+
+  return {
+    credit,
+    as_points: p.mode === "points",
+    reason: p.mode === "points"
+      ? `${daysRemaining} unused day(s) returned as points`
+      : `${daysRemaining} of ${daysTotal} day(s) unused`,
+    mode: p.mode,
+    days_remaining: daysRemaining,
+    days_total: daysTotal,
+  };
+}
+
+export default { prorate, resolveProrationPolicy, PRORATION_DEFAULTS };

package/src/reportee-tree.js

@@ -1,129 +1,129 @@
-/**
- * Reportee-tree DFS — @i4e/invest4edu-access-core (Track 3 G3 shared primitive).
- *
- * 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 `[{ _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<{_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, 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;
-    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));
-  }
-
-  const visited = new Set();
-  const result = new Set();
-  const stack = [...rootIds];
-  while (stack.length) {
-    const id = stack.pop();
-    if (!id || visited.has(id)) continue;
-    visited.add(id);
-    result.add(id);
-    for (const rep of byManager.get(id) || []) stack.push(rep);
-  }
-  return [...result];
-}
+/**
+ * Reportee-tree DFS — @i4e/invest4edu-access-core (Track 3 G3 shared primitive).
+ *
+ * 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 `[{ _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<{_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, 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;
+    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));
+  }
+
+  const visited = new Set();
+  const result = new Set();
+  const stack = [...rootIds];
+  while (stack.length) {
+    const id = stack.pop();
+    if (!id || visited.has(id)) continue;
+    visited.add(id);
+    result.add(id);
+    for (const rep of byManager.get(id) || []) stack.push(rep);
+  }
+  return [...result];
+}