@i4e/invest4edu-access-core 0.4.1 → 0.5.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@i4e/invest4edu-access-core",
-  "version": "0.4.1",
-  "description": "Shared access-control primitives (Track 3: tenant keystone, role capabilities, reportee tree, feature flags) for NeoFindesk backends.",
+  "version": "0.5.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).",
   "type": "module",
   "exports": {
     ".": "./src/index.js",
@@ -9,7 +9,13 @@
     "./tenant-plugin": "./src/tenant-plugin.js",
     "./role-capabilities": "./src/role-capabilities.js",
     "./reportee-tree": "./src/reportee-tree.js",
-    "./access-config": "./src/access-config.js"
+    "./access-config": "./src/access-config.js",
+    "./access-schema": "./src/access-schema.js",
+    "./access-resolver": "./src/access-resolver.js",
+    "./visible-when": "./src/visible-when.js"
+  },
+  "scripts": {
+    "test": "node --test test/"
   },
   "files": [
     "src",

package/src/access-resolver.js

@@ -0,0 +1,256 @@
+/**
+ * Access snapshot resolver — @i4e/invest4edu-access-core (unified access framework, P1).
+ *
+ * ONE resolver produces the "access snapshot" for a request: the nav tree, the per-feature
+ * allow/actions/entitlement/tracking map, and the product scope. Everything downstream — nav,
+ * `hasFeature`, `requireFeature`, grid `visibleWhen`, entitlement, metering — reads this one
+ * object, so there is a single place where access is decided.
+ *
+ * PURE by design: callers inject already-loaded data (`registry`, `grants`, `mappedProducts`, …).
+ * No Mongoose, no I/O, no ALS — which is what makes allow/deny matrices testable without a DB.
+ *
+ * Design: TDD-unified-access-and-subscription.md §4
+ */
+
+import { parentCodeOf } from "./access-schema.js";
+
+/** Reasons a feature can be locked, surfaced so the UI can distinguish upsell from hard-deny. */
+export const ENTITLEMENT_REASONS = Object.freeze({
+  OK: "ok",
+  ADMIN_BYPASS: "admin_bypass",
+  NO_SUBSCRIPTION: "no_subscription",
+  TRIAL_ACTIVE: "trial_active",
+  TRIAL_EXPIRED: "trial_expired",
+  LOCKED: "locked",
+  QUOTA_EXCEEDED: "quota_exceeded",
+  PAYMENT_OVERDUE: "payment_overdue",
+  SUBSCRIPTION_EXPIRED: "subscription_expired",
+});
+
+const isLive = (f) =>
+  !!f && f.status === "active" && f.kill_switch !== "on";
+
+/**
+ * Merge grants into an effective allow-set per feature.
+ *
+ * Rules (design §3.3): union(role allows) − union(user denies) + union(user allows).
+ * Deny beats allow at the same subject level; the user level beats the role level.
+ *
+ * Product dimension: a grant with `product_code: null` is UNSCOPED and contributes the caller's
+ * whole product set (legacy-equivalent). A scoped grant contributes only that product, and only
+ * when the caller actually has it mapped (default-deny).
+ *
+ * @returns {Map<string, {products: Set<string>|null}>} null products = unscoped/all
+ */
+export function mergeGrants(grants = [], { mappedProducts = [], now = new Date() } = {}) {
+  const mapped = new Set(mappedProducts.map(String));
+
+  const roleAllow = new Map(); // code → Set|null
+  const userAllow = new Map();
+  const userDeny = new Set();
+  const roleDeny = new Set();
+
+  const addTo = (map, code, product) => {
+    if (!map.has(code)) map.set(code, { products: null, anyUnscoped: false });
+    const e = map.get(code);
+    if (product == null) {
+      e.anyUnscoped = true; // unscoped grant wins — covers everything the user has
+      e.products = null;
+    } else if (!e.anyUnscoped) {
+      if (!e.products) e.products = new Set();
+      e.products.add(String(product));
+    }
+  };
+
+  for (const g of grants) {
+    if (!g || !g.feature_code) continue;
+    if (g.expires_at && new Date(g.expires_at) <= now) continue; // expired grants are inert
+
+    // A product-scoped grant only counts when the caller actually has that product mapped.
+    if (g.product_code != null && !mapped.has(String(g.product_code))) continue;
+
+    const isUser = g.subject_type === "user";
+    if (g.effect === "deny") {
+      (isUser ? userDeny : roleDeny).add(g.feature_code);
+    } else {
+      addTo(isUser ? userAllow : roleAllow, g.feature_code, g.product_code ?? null);
+    }
+  }
+
+  const out = new Map();
+  const put = (code, entry) => {
+    const prev = out.get(code);
+    if (!prev) {
+      out.set(code, { products: entry.anyUnscoped ? null : new Set(entry.products || []) });
+      return;
+    }
+    if (prev.products === null || entry.anyUnscoped) prev.products = null;
+    else for (const p of entry.products || []) prev.products.add(p);
+  };
+
+  for (const [code, entry] of roleAllow) {
+    if (roleDeny.has(code)) continue; // deny beats allow at the same level
+    put(code, entry);
+  }
+  for (const code of userDeny) out.delete(code); // user deny beats role allow
+  for (const [code, entry] of userAllow) put(code, entry); // user allow beats role deny
+
+  return out;
+}
+
+/**
+ * Build the nav tree from the features the caller holds.
+ * Screens only, `nav.show_in_nav`, grouped by module and ordered by position.
+ *
+ * The nav IS the access model projected — not a parallel copy (requirement 2).
+ */
+export function buildNav(allowedScreenFeatures = [], modules = []) {
+  const modByCode = new Map(
+    modules.filter((m) => m && m.status !== "retired").map((m) => [m.module_code, m]),
+  );
+
+  const groups = new Map();
+  for (const f of allowedScreenFeatures) {
+    if (!f?.nav?.show_in_nav) continue;
+    const code = f.module_code;
+    const mod = modByCode.get(code);
+    if (!mod) continue; // a feature whose module is missing/retired is simply not navigable
+    if (!groups.has(code)) {
+      groups.set(code, {
+        module_code: code,
+        name: mod.name,
+        icon: mod.icon || null,
+        position: mod.position ?? 0,
+        items: [],
+      });
+    }
+    groups.get(code).items.push({
+      feature_code: f.feature_code,
+      name: f.name,
+      route: f.route || null,
+      position: f.nav.position ?? 0,
+      is_external_url: !!f.nav.is_external_url,
+      external_url: f.nav.external_url || null,
+    });
+  }
+
+  const nav = [...groups.values()].sort((a, b) => a.position - b.position);
+  for (const g of nav) g.items.sort((a, b) => a.position - b.position);
+  return nav;
+}
+
+/**
+ * Resolve the access snapshot.
+ *
+ * @param {Object} p
+ * @param {Object} p.identity         { account_id, userId, roles[], actingAs? }
+ * @param {Object} p.registry         { features: [], modules: [] }  (already filtered to live rows)
+ * @param {Array}  p.grants           access_grants rows for {account, roles ∪ userId}
+ * @param {Array}  p.mappedProducts   the caller's product codes
+ * @param {Object} p.capabilities     capsFor(roles) — reads `bypassAllGates` (D27)
+ * @param {Function} [p.entitlementFor] (feature) → entitlement block | null
+ */
+export function resolveAccessSnapshot({
+  identity = {},
+  registry = {},
+  grants = [],
+  mappedProducts = [],
+  capabilities = {},
+  entitlementFor = null,
+  now = new Date(),
+} = {}) {
+  const features = (registry.features || []).filter(isLive);
+  const modules = registry.modules || [];
+
+  // ── D27: system-admin break-glass ───────────────────────────────────────────────────────────
+  // Resolved ONCE, here — never re-checked per gate, so no gate can forget to honour it. Opens
+  // every gate WITHIN the caller's own account. Deliberately NOT cross-tenant: crossing accounts
+  // is the separate, stricter canCrossAccount path (D3/BRI-582). bypassAllGates ≠ canCrossAccount.
+  const bypass = !!capabilities.bypassAllGates;
+
+  const allowedByCode = bypass
+    ? new Map(features.map((f) => [f.feature_code, { products: null }]))
+    : mergeGrants(grants, { mappedProducts, now });
+
+  const byCode = new Map(features.map((f) => [f.feature_code, f]));
+  const productScope = bypass
+    ? [...new Set(features.flatMap((f) => f.products || []))]
+    : [...new Set(mappedProducts.map(String))];
+
+  const featureMap = {};
+  const allowedScreens = [];
+
+  for (const f of features) {
+    const grant = allowedByCode.get(f.feature_code);
+    if (!grant) continue;
+
+    // Platform-level product constraint on the feature itself, intersected with the grant's.
+    let products = grant.products ? [...grant.products] : [...productScope];
+    if (Array.isArray(f.products) && f.products.length) {
+      const allowedForFeature = new Set(f.products.map(String));
+      products = products.filter((p) => allowedForFeature.has(p));
+      // A product-constrained feature with no overlap is not reachable at all.
+      if (products.length === 0 && !bypass) continue;
+    }
+
+    const entitlement = bypass
+      ? {
+          unlocked: true,
+          quota: null,
+          used: 0,
+          remaining: null,
+          overage_policy: "unlimited",
+          reason: ENTITLEMENT_REASONS.ADMIN_BYPASS,
+        }
+      : entitlementFor
+        ? entitlementFor(f)
+        : null;
+
+    featureMap[f.feature_code] = {
+      allowed: true,
+      products: grant.products === null && !Array.isArray(f.products) ? "*" : products,
+      actions: [],
+      entitlement,
+      tracking: !!f.tracking_enabled,
+    };
+
+    if (f.feature_type === "screen") allowedScreens.push(f);
+  }
+
+  // Attach each allowed action to its parent screen (actions are features, design §2).
+  for (const code of Object.keys(featureMap)) {
+    const f = byCode.get(code);
+    if (f?.feature_type !== "action") continue;
+    const parent = f.parent_feature_code || parentCodeOf(code);
+    if (parent && featureMap[parent]) featureMap[parent].actions.push(code);
+  }
+
+  return {
+    version: 1,
+    resolved_at: now.toISOString(),
+    resolved_for: {
+      userId: identity.userId ? String(identity.userId) : null,
+      account_id: identity.account_id ? String(identity.account_id) : null,
+      actingAs: identity.actingAs?.giver_id || null,
+      real_userId: identity.actingAs?.delegate_id || (identity.userId ? String(identity.userId) : null),
+      admin_bypass: bypass,
+    },
+    nav: buildNav(allowedScreens, modules),
+    features: featureMap,
+    productScope,
+  };
+}
+
+/** Snapshot-based `hasFeature` (the server-side twin of the client helper). */
+export function hasFeature(snapshot, featureCode) {
+  return !!snapshot?.features?.[featureCode]?.allowed;
+}
+
+/** True when the feature is allowed AND (no entitlement gate OR it is unlocked). */
+export function isUsable(snapshot, featureCode) {
+  const f = snapshot?.features?.[featureCode];
+  if (!f?.allowed) return false;
+  return !f.entitlement || f.entitlement.unlocked !== false;
+}
+
+export default { resolveAccessSnapshot, mergeGrants, buildNav, hasFeature, isUsable, ENTITLEMENT_REASONS };

package/src/access-schema.js

@@ -0,0 +1,151 @@
+/**
+ * Access-model schema DEFINITIONS — @i4e/invest4edu-access-core (unified access framework, P1).
+ *
+ * These are PLAIN OBJECTS, not Mongoose schemas (D4: no models in the package). Each backend
+ * registers its own models from these definitions, so there is one source of truth for field
+ * names without dragging a second Mongoose instance into the package.
+ *
+ * Design: nfd-ui-nextjs/IV-CodingAgent/specs/access-management/TDD-unified-access-and-subscription.md
+ * Status: nfd-ui-nextjs/IV-CodingAgent/specs/access-management/TRACKER-unified-access.md
+ *
+ * Taxonomy:  Module → Feature → Action
+ *   - a PAGE is a feature (feature_type: 'screen')       — retires Page + page_features CSV
+ *   - an ACTION is a feature (parent_feature_code)       — so a plan can entitle an action
+ *   One `feature_code` namespace serves RBAC, nav, grids, metering and entitlement.
+ */
+
+/** Feature types. A page is a `screen`; an action is an `action` with a parent. */
+export const FEATURE_TYPES = Object.freeze(["screen", "action", "data", "service", "tool"]);
+
+/** Lifecycle status shared by registry collections. */
+export const REGISTRY_STATUSES = Object.freeze(["active", "dormant", "retired"]);
+
+/** Per-feature enforcement ladder (mirrors the platform's off→warn→enforce doctrine). */
+export const ROLLOUT_MODES = Object.freeze(["off", "warn", "enforce"]);
+
+/** Grant effect. `deny` at the user level replaces the old `revoked_pages`. */
+export const GRANT_EFFECTS = Object.freeze(["allow", "deny"]);
+
+/** Subject a grant is attached to. */
+export const GRANT_SUBJECTS = Object.freeze(["role", "user"]);
+
+/**
+ * `feature_code` convention: MODULE.SCREEN or MODULE.SCREEN.ACTION.
+ * Uppercase segments, `_` within a segment, `.` between. Codes are IMMUTABLE once created —
+ * they appear in grants, plan entitlements, usage events and grid configs.
+ */
+export const FEATURE_CODE_PATTERN = /^[A-Z][A-Z0-9_]*(\.[A-Z][A-Z0-9_]*){1,2}$/;
+
+export function isValidFeatureCode(code) {
+  return typeof code === "string" && FEATURE_CODE_PATTERN.test(code);
+}
+
+/** Derive a screen's code from an action code (`A.B.C` → `A.B`); null if not an action. */
+export function parentCodeOf(featureCode) {
+  if (!isValidFeatureCode(featureCode)) return null;
+  const parts = featureCode.split(".");
+  return parts.length === 3 ? `${parts[0]}.${parts[1]}` : null;
+}
+
+/** Module code of any feature code (`A.B[.C]` → `A`). */
+export function moduleCodeOf(featureCode) {
+  if (!isValidFeatureCode(featureCode)) return null;
+  return featureCode.split(".")[0];
+}
+
+// ── Collection definitions ────────────────────────────────────────────────────────────────────
+// `collection` is the Mongo collection name each backend must use, so v1 and v2 agree.
+
+/** Global: nav grouping + reporting dimension. Carries no grants. */
+export const ACCESS_MODULE_DEF = Object.freeze({
+  collection: "access_modules",
+  fields: Object.freeze({
+    module_code: { type: "String", required: true, unique: true, index: true },
+    name: { type: "String", required: true },
+    icon: { type: "String" },
+    position: { type: "Number", default: 0 },
+    status: { type: "String", enum: REGISTRY_STATUSES, default: "active" },
+  }),
+});
+
+/**
+ * Global: THE feature registry. Absorbs Page, Page.page_features, the flat Feature model, and
+ * the subscription feature registry (BRI-674/707 — one vocabulary, structurally).
+ */
+export const ACCESS_FEATURE_DEF = Object.freeze({
+  collection: "access_features",
+  fields: Object.freeze({
+    feature_code: { type: "String", required: true, unique: true, index: true, immutable: true },
+    name: { type: "String", required: true },
+    description: { type: "String" },
+    feature_type: { type: "String", enum: FEATURE_TYPES, required: true, index: true },
+    module_code: { type: "String", index: true },
+    parent_feature_code: { type: "String", default: null, index: true }, // set for actions
+
+    route: { type: "String", default: null }, // screens only (absorbs page_route_for_web)
+    nav: {
+      show_in_nav: { type: "Boolean", default: false },
+      position: { type: "Number", default: 0 },
+      icon: { type: "String" },
+      is_external_url: { type: "Boolean", default: false },
+      external_url: { type: "String" },
+    },
+
+    products: { type: "[String]", default: [] }, // empty = product-agnostic
+
+    status: { type: "String", enum: REGISTRY_STATUSES, default: "active", index: true },
+    kill_switch: { type: "String", enum: ["on", "off"], default: "off" },
+    rollout_mode: { type: "String", enum: ROLLOUT_MODES, default: "off" },
+
+    // Survives an entitlement block (login, billing/checkout, profile) — see design §7.4.
+    always_available: { type: "Boolean", default: false },
+
+    tracking_enabled: { type: "Boolean", default: false }, // analytics (side DB)
+    is_meterable: { type: "Boolean", default: false }, // quota (app DB counters)
+    single_usage_purchasable: { type: "Boolean", default: false },
+    single_usage_price: { type: "Number", default: null },
+
+    legacy_page_id: { type: "ObjectId", default: null }, // migration traceability
+    created_by: { type: "ObjectId" },
+  }),
+});
+
+/**
+ * Tenant: one row per grant. Replaces RolePrivileges.accessible_pages, UserPrivileges and
+ * revoked_pages. Rows (not embedded arrays) so grants are indexable, diffable and expirable.
+ */
+export const ACCESS_GRANT_DEF = Object.freeze({
+  collection: "access_grants",
+  fields: Object.freeze({
+    account_id: { type: "ObjectId", required: true, index: true },
+    subject_type: { type: "String", enum: GRANT_SUBJECTS, required: true },
+    subject_id: { type: "String", required: true }, // role_code | userId
+    feature_code: { type: "String", required: true, index: true },
+    // null = unscoped (applies across the user's mapped_products) — the legacy-equivalent default.
+    // set  = applies only when that product is in the user's mapped_products (default-deny).
+    product_code: { type: "String", default: null },
+    effect: { type: "String", enum: GRANT_EFFECTS, default: "allow" },
+    conditions: { type: "Mixed", default: null },
+    expires_at: { type: "Date", default: null },
+    granted_by: { type: "ObjectId" },
+  }),
+  indexes: Object.freeze([
+    { keys: { account_id: 1, subject_type: 1, subject_id: 1 } },
+    { keys: { account_id: 1, feature_code: 1 } },
+  ]),
+});
+
+export default {
+  FEATURE_TYPES,
+  REGISTRY_STATUSES,
+  ROLLOUT_MODES,
+  GRANT_EFFECTS,
+  GRANT_SUBJECTS,
+  FEATURE_CODE_PATTERN,
+  isValidFeatureCode,
+  parentCodeOf,
+  moduleCodeOf,
+  ACCESS_MODULE_DEF,
+  ACCESS_FEATURE_DEF,
+  ACCESS_GRANT_DEF,
+};

package/src/index.js

@@ -3,7 +3,7 @@
  * Tenant isolation (D1 keystone) + role capabilities (G7).
  */
 export { default as als, runWithTenant, runAsSystem, getTenantStore } from "./tenant-context.js";
-export { default as tenantPlugin } from "./tenant-plugin.js";
+export { default as tenantPlugin, setTenantMode, getTenantMode } from "./tenant-plugin.js";
 export {
   CAPABILITY_FLAGS,
   DEFAULT_ROLE_CAPABILITIES,
@@ -18,3 +18,33 @@ export {
   readEnvFlags,
   resolveFlags,
 } from "./access-config.js";
+
+// ── Unified access framework (P1) ─────────────────────────────────────────────────────────────
+export {
+  FEATURE_TYPES,
+  REGISTRY_STATUSES,
+  ROLLOUT_MODES,
+  GRANT_EFFECTS,
+  GRANT_SUBJECTS,
+  FEATURE_CODE_PATTERN,
+  isValidFeatureCode,
+  parentCodeOf,
+  moduleCodeOf,
+  ACCESS_MODULE_DEF,
+  ACCESS_FEATURE_DEF,
+  ACCESS_GRANT_DEF,
+} from "./access-schema.js";
+export {
+  resolveAccessSnapshot,
+  mergeGrants,
+  buildNav,
+  hasFeature,
+  isUsable,
+  ENTITLEMENT_REASONS,
+} from "./access-resolver.js";
+export {
+  evaluateVisibleWhen,
+  filterVisible,
+  applyRelabel,
+  resolveColumns,
+} from "./visible-when.js";

package/src/role-capabilities.js

@@ -13,6 +13,13 @@
  *   canCorrectE1        — may run the audited E1 correction
  *   canCrossAccount     — audited sysadmin cross-account path (default: none)
  *   productScoped       — pages + records restricted to the user's mapped products
+ *   bypassAllGates      — system-admin break-glass (D27): opens EVERY gate WITHIN the caller's
+ *                         own account (RBAC, nav, entitlement, product scope, grid visibleWhen,
+ *                         kill switches). Deliberately NOT cross-tenant — crossing accounts is
+ *                         the separate, stricter `canCrossAccount` path (D3/BRI-582: config data
+ *                         only, header-driven, logged before bypass). bypassAllGates ≠
+ *                         canCrossAccount. Exists so a broken access config can never lock
+ *                         everyone out of the screens needed to repair it.
  */
 
 export const CAPABILITY_FLAGS = Object.freeze([
@@ -22,6 +29,7 @@ export const CAPABILITY_FLAGS = Object.freeze([
   "canCorrectE1",
   "canCrossAccount",
   "productScoped",
+  "bypassAllGates",
 ]);
 
 /**
@@ -32,8 +40,10 @@ export const CAPABILITY_FLAGS = Object.freeze([
  *   ALLOWED_ROLES (e1) = SUPER_ADMIN, SYSTEM_ADMIN, BROKER_ADMIN, BACKOFFICE_USER
  */
 export const DEFAULT_ROLE_CAPABILITIES = Object.freeze({
-  SUPER_ADMIN: { isFullAccess: true, canGovernDelegation: true, canCorrectE1: true },
-  SYSTEM_ADMIN: { isFullAccess: true, canGovernDelegation: true, canCorrectE1: true },
+  // bypassAllGates (D27) defaults to the two platform-admin roles. Inert until the access
+  // engine reads it, and revocable from the `rolecapabilities` collection with no deploy.
+  SUPER_ADMIN: { isFullAccess: true, canGovernDelegation: true, canCorrectE1: true, bypassAllGates: true },
+  SYSTEM_ADMIN: { isFullAccess: true, canGovernDelegation: true, canCorrectE1: true, bypassAllGates: true },
   BROKER_ADMIN: { isFullAccess: true, canGovernDelegation: true, canCorrectE1: true },
   BACKOFFICE_USER: { isFullAccess: true, canCorrectE1: true },
   HR_USER: { isFullAccess: true },

package/src/tenant-plugin.js

@@ -20,7 +20,27 @@
 import als from "./tenant-context.js";
 
 const READ_OPS = ["find", "findOne", "countDocuments"];
-const mode = () => (process.env.TENANT_ENFORCEMENT || "off").toLowerCase();
+const VALID = new Set(["off", "warn", "enforce"]);
+
+// Enforcement mode is resolvable from TWO places, so it can be flipped from the admin UI
+// (DB) WITHOUT a restart, while the env var stays the infra-level emergency override.
+//   Precedence:  env TENANT_ENFORCEMENT (if valid)  >  DB value (setTenantMode)  >  "off"
+let dbMode = null;
+
+/** Called by the backend from the `accessconfig` DB doc so a UI toggle takes effect (~refresh). */
+export function setTenantMode(m) {
+  const v = m ? String(m).toLowerCase() : "";
+  dbMode = VALID.has(v) ? v : null;
+}
+
+/** Effective mode. */
+export function getTenantMode() {
+  const env = (process.env.TENANT_ENFORCEMENT || "").toLowerCase();
+  if (VALID.has(env)) return env; // explicit env wins (emergency / infra)
+  return dbMode || "off";
+}
+
+const mode = getTenantMode;
 
 function tenantHook() {
   if (mode() === "off") return; // literal no-op — identical to pre-Track-3

package/src/visible-when.js

@@ -0,0 +1,108 @@
+/**
+ * `visibleWhen` — ONE predicate language, ONE evaluator.
+ * @i4e/invest4edu-access-core (unified access framework, P1)
+ *
+ * The same function gates nav items, screen actions, grid columns, filters, row/bulk actions,
+ * exports and summary metrics. That is what makes "driven by product and roles" true across the
+ * whole app instead of per-screen — and it means a rule is written once, in data, not in 139
+ * hardcoded predicates.
+ *
+ * Client-side evaluation is UX ONLY. Servers MUST re-evaluate before returning data, projecting
+ * columns, or building an export/summary — never trust a client-supplied column list.
+ *
+ * Design: TDD-unified-access-and-subscription.md §8.3
+ */
+
+import { hasFeature, isUsable } from "./access-resolver.js";
+
+/**
+ * Shape (every key optional; all present keys must pass — AND):
+ * {
+ *   features:         ["ORDERS.LIST"]          // caller must hold all of these
+ *   actions:          ["ORDERS.LIST.CANCEL"]   // alias of features, reads better on actions
+ *   entitled:         "TOOLS.AI_REPORT"        // must be allowed AND entitlement-unlocked
+ *   products:         ["IVP003"]               // caller's product scope must intersect
+ *   distributorLevel: ["D1","D2"]
+ *   screenType:       "openorders" | ["a","b"]
+ *   roles:            ["BROKER_ADMIN"]         // LEGACY escape hatch — lint-flagged, being removed
+ *   anyOf:            [ {...}, {...} ]         // OR of nested predicates
+ *   not:              { ... }                  // negation
+ * }
+ *
+ * @param {Object|null|undefined} rule   absent/empty ⇒ visible (opt-in gating, not opt-out)
+ * @param {Object} ctx { snapshot, productScope?, distributorLevel?, screenType?, roles? }
+ */
+export function evaluateVisibleWhen(rule, ctx = {}) {
+  if (!rule || typeof rule !== "object") return true;
+
+  const snapshot = ctx.snapshot || null;
+  // A system admin (D27) resolves a fully-open snapshot, so feature/entitlement checks below
+  // pass naturally. Product/level predicates still evaluate — an admin seeing a D1-only column
+  // labelled for D1 would be misleading, not permissive.
+  const productScope = new Set(
+    (ctx.productScope || snapshot?.productScope || []).map(String),
+  );
+
+  const asArray = (v) => (v == null ? [] : Array.isArray(v) ? v : [v]);
+
+  if (rule.features && !asArray(rule.features).every((c) => hasFeature(snapshot, c))) return false;
+  if (rule.actions && !asArray(rule.actions).every((c) => hasFeature(snapshot, c))) return false;
+  if (rule.entitled && !asArray(rule.entitled).every((c) => isUsable(snapshot, c))) return false;
+
+  if (rule.products) {
+    const want = asArray(rule.products).map(String);
+    if (want.length && !want.some((p) => productScope.has(p))) return false;
+  }
+
+  if (rule.distributorLevel) {
+    const lvl = ctx.distributorLevel ? String(ctx.distributorLevel) : null;
+    if (!lvl || !asArray(rule.distributorLevel).map(String).includes(lvl)) return false;
+  }
+
+  if (rule.screenType) {
+    const st = ctx.screenType ? String(ctx.screenType) : null;
+    if (!st || !asArray(rule.screenType).map(String).includes(st)) return false;
+  }
+
+  // LEGACY: kept only so migration can proceed screen-by-screen. New configs must not use it.
+  if (rule.roles) {
+    const held = new Set(asArray(ctx.roles || snapshot?.resolved_for?.roles).map(String));
+    if (!asArray(rule.roles).map(String).some((r) => held.has(r))) return false;
+  }
+
+  if (rule.anyOf) {
+    const branches = asArray(rule.anyOf);
+    if (branches.length && !branches.some((b) => evaluateVisibleWhen(b, ctx))) return false;
+  }
+
+  if (rule.not && evaluateVisibleWhen(rule.not, ctx)) return false;
+
+  return true;
+}
+
+/** Filter a list of `{visibleWhen}`-bearing config items (columns, metrics, actions, filters). */
+export function filterVisible(items = [], ctx = {}) {
+  return items.filter((i) => evaluateVisibleWhen(i?.visibleWhen, ctx));
+}
+
+/**
+ * Apply `relabelWhen` overrides to a grid column — absorbs the imperative relabelling in
+ * order-constants (e.g. d1/d2/d3_payout → "Net Income" for the matching distributor level).
+ * First matching rule wins; the column is returned unchanged when nothing matches.
+ */
+export function applyRelabel(column, ctx = {}) {
+  if (!column?.relabelWhen?.length) return column;
+  for (const r of column.relabelWhen) {
+    if (evaluateVisibleWhen(r?.when, ctx)) {
+      return { ...column, header: r.header ?? column.header, label: r.label ?? column.label };
+    }
+  }
+  return column;
+}
+
+/** Resolve a full column list: drop hidden ones, apply relabelling, preserve order. */
+export function resolveColumns(columns = [], ctx = {}) {
+  return filterVisible(columns, ctx).map((c) => applyRelabel(c, ctx));
+}
+
+export default { evaluateVisibleWhen, filterVisible, applyRelabel, resolveColumns };