@i4e/invest4edu-access-core 0.30.0 → 0.32.0

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/grid-schema.js

@@ -1,231 +1,231 @@
-/**
- * DataGrid v2 config — @i4e/invest4edu-access-core (P4). Definitions + validator. No React, no DB.
- *
- * ONE config defines a listing end to end: where the rows come from, which columns exist and who
- * sees each, the filters, the row/bulk actions, the export, and the summary cards. It lives in the
- * shared package because three consumers must agree on it exactly — the UI renders it, v1 serves
- * and re-evaluates it, and the admin screen edits it.
- *
- * ── Why it is strictly serialisable ──────────────────────────────────────────────────────────
- * No functions anywhere. A column says `type: "currency"`, never `cell: (row) => …`. That is the
- * single property that makes a grid storable, diffable, admin-editable and server-re-evaluable.
- * The moment one config carries a callback, it can no longer be saved — and the whole model
- * collapses back into per-screen code.
- *
- * ── Why access binding lives IN the config ───────────────────────────────────────────────────
- * `feature_code` gates the grid, every action carries an `action_code`, and `visibleWhen` gates
- * columns/filters/metrics. So "who may see this column" and "who may press this button" are
- * answered by the same engine that answers "who may open this screen" — not by a second, parallel
- * set of role checks inside a component.
- *
- * `source.collection` is what lets the SERVER apply tenant + product + record scope to the query
- * (scopedMatch). Without it a grid could be pointed at a collection nobody has scoped.
- *
- * Design: nfd-ui-nextjs/IV-CodingAgent/specs/access-management/TDD-unified-access-and-subscription.md §8
- */
-
-export const COLUMN_TYPES = Object.freeze([
-  "text", "number", "currency", "percent", "date", "datetime",
-  "boolean", "status-pill", "link", "actions", "inline-edit",
-]);
-
-export const FILTER_TYPES = Object.freeze([
-  "text", "select", "multiselect", "reference", "boolean", "exists", "daterange", "numberrange",
-]);
-
-export const AGGREGATIONS = Object.freeze(["sum", "avg", "count", "countWhere", "distinct", "raw"]);
-
-export const GRID_SCOPES = Object.freeze(["global", "account"]);
-
-/** The filter payload dialect the table and its summary endpoint MUST both speak. */
-export const FILTER_DIALECT = "grid-ast-v1";
-
-export const GRID_CONFIG_DEF = Object.freeze({
-  collection: "grid_configs",
-  fields: Object.freeze({
-    grid_code: { type: "String", required: true, index: true },
-    // Binds the whole grid to the access engine — no grid without a feature.
-    feature_code: { type: "String", required: true, index: true },
-    name: { type: "String" },
-    scope: { type: "String", enum: GRID_SCOPES, default: "global" },
-    // Set only on scope:'account' rows; the per-tenant override of a global config.
-    account_id: { type: "ObjectId", default: null, index: true },
-    config: { type: "Mixed", required: true },
-    // Bumped on every save. A saved user layout records the version it was made against, so the
-    // renderer can reconcile rather than break.
-    version: { type: "Number", default: 1 },
-    status: { type: "String", enum: ["active", "draft", "retired"], default: "draft" },
-    updated_by: { type: "ObjectId" },
-    updated_at: { type: "Date" },
-  }),
-  indexes: Object.freeze([
-    { keys: { grid_code: 1, scope: 1, account_id: 1 }, options: { unique: true } },
-  ]),
-});
-
-const isObj = (v) => !!v && typeof v === "object" && !Array.isArray(v);
-const FEATURE_CODE = /^[A-Z][A-Z0-9_]*(\.[A-Z][A-Z0-9_]*){1,2}$/;
-
-/**
- * Validate a grid config. Returns `{ valid, errors[], warnings[] }`.
- *
- * Errors are things that would render a broken or unsafe grid; warnings are things that are legal
- * but almost certainly a mistake. The admin screen must block on errors and show warnings — a
- * config is edited by a human and saved straight into what everyone sees, so "it saved fine and
- * then the screen was empty" is the failure mode this exists to prevent.
- */
-export function validateGridConfig(config) {
-  const errors = [];
-  const warnings = [];
-  const err = (m) => errors.push(m);
-  const warn = (m) => warnings.push(m);
-
-  if (!isObj(config)) return { valid: false, errors: ["config must be an object"], warnings };
-
-  if (!config.grid_code) err("grid_code is required");
-  if (!config.feature_code) err("feature_code is required — a grid must bind to the access engine");
-  else if (!FEATURE_CODE.test(config.feature_code)) err(`feature_code "${config.feature_code}" must be MODULE.SCREEN[.ACTION]`);
-
-  // ── source ──────────────────────────────────────────────────────────────────────────────────
-  const src = config.source;
-  if (!isObj(src)) err("source is required");
-  else {
-    if (!src.endpoint) err("source.endpoint is required");
-    // Without a collection the server cannot apply tenant/product/record scope to this grid.
-    if (!src.collection) err("source.collection is required — the server needs it to scope the query");
-    if (src.filter_dialect && src.filter_dialect !== FILTER_DIALECT) {
-      err(`source.filter_dialect must be "${FILTER_DIALECT}"`);
-    }
-    if (!src.id_field) warn("source.id_field not set — defaulting to _id");
-  }
-
-  // ── columns ─────────────────────────────────────────────────────────────────────────────────
-  const cols = Array.isArray(config.columns) ? config.columns : [];
-  if (!cols.length) err("at least one column is required");
-  const seen = new Set();
-  cols.forEach((c, i) => {
-    const at = `columns[${i}]`;
-    if (!isObj(c)) return err(`${at} must be an object`);
-    if (!c.key) err(`${at}.key is required`);
-    else if (seen.has(c.key)) err(`${at}.key "${c.key}" is duplicated — keys address saved layouts`);
-    else seen.add(c.key);
-    if (!c.header) warn(`${at} ("${c.key}") has no header`);
-    if (!c.path && c.type !== "actions") err(`${at} ("${c.key}") needs a path`);
-    if (c.type && !COLUMN_TYPES.includes(c.type)) err(`${at}.type "${c.type}" is not a known type`);
-    // A callback here is the one thing that would make the config unstorable.
-    for (const k of Object.keys(c)) {
-      if (typeof c[k] === "function") err(`${at}.${k} is a function — configs must be serialisable`);
-    }
-  });
-  if (cols.length && !cols.some((c) => c.defaultVisible !== false)) {
-    err("every column is hidden by default — the grid would render empty");
-  }
-
-  // ── filters ─────────────────────────────────────────────────────────────────────────────────
-  (config.filters || []).forEach((f, i) => {
-    const at = `filters[${i}]`;
-    if (!f?.key) err(`${at}.key is required`);
-    if (f?.type && !FILTER_TYPES.includes(f.type)) err(`${at}.type "${f.type}" is not a known type`);
-    if (f?.type === "select" && !f.options && !f.ref) {
-      warn(`${at} ("${f.key}") is a select with neither options nor ref — it will render empty`);
-    }
-  });
-
-  // ── actions: each is a FEATURE, so it must carry a code ─────────────────────────────────────
-  const checkActions = (list, label) => (list || []).forEach((a, i) => {
-    const at = `${label}[${i}]`;
-    if (!a?.action_code) {
-      err(`${at} has no action_code — actions are gated features, an ungated action is a hole`);
-    } else if (!FEATURE_CODE.test(a.action_code)) {
-      err(`${at}.action_code "${a.action_code}" must be MODULE.SCREEN.ACTION`);
-    }
-    if (!a?.label) warn(`${at} has no label`);
-    // Destructive things must ask. Cheap to require, expensive to forget.
-    if (a?.kind === "mutation" && /delete|cancel|remove|revoke/i.test(a.action_code || "") && !a.confirm) {
-      warn(`${at} ("${a.action_code}") looks destructive but has no confirm`);
-    }
-  });
-  checkActions(config.rowActions, "rowActions");
-  checkActions(config.bulkActions, "bulkActions");
-
-  if (config.export && !config.export.action_code) {
-    err("export needs an action_code — exports are gated and meterable like any other action");
-  }
-
-  // ── summary ─────────────────────────────────────────────────────────────────────────────────
-  if (config.summary) {
-    const s = config.summary;
-    if (!Array.isArray(s.metrics) || !s.metrics.length) warn("summary has no metrics");
-    // The rule the MIS rollups taught us: cards and the table must answer the same question.
-    if (s.source === "endpoint" && !s.endpoint) {
-      err("summary.source is 'endpoint' but no summary.endpoint is set");
-    }
-    (s.metrics || []).forEach((m, i) => {
-      const at = `summary.metrics[${i}]`;
-      if (!m?.key) err(`${at}.key is required`);
-      if (m?.agg && !AGGREGATIONS.includes(m.agg)) err(`${at}.agg "${m.agg}" is not a known aggregation`);
-      if (m?.agg && m.agg !== "count" && !m.path) err(`${at} ("${m.key}") needs a path for agg "${m.agg}"`);
-      if (m?.agg === "countWhere" && !m.where) err(`${at} ("${m.key}") is countWhere with no where clause`);
-    });
-  }
-
-  // ── pagination / sort ───────────────────────────────────────────────────────────────────────
-  if (config.pagination) {
-    const p = config.pagination;
-    if (p.defaultSize && Array.isArray(p.pageSizes) && !p.pageSizes.includes(p.defaultSize)) {
-      err(`pagination.defaultSize ${p.defaultSize} is not one of pageSizes`);
-    }
-  }
-  if (config.defaultSort?.key && !seen.has(config.defaultSort.key)) {
-    err(`defaultSort.key "${config.defaultSort.key}" is not a column key`);
-  }
-  if (config.totalsRow?.perColumn) {
-    config.totalsRow.perColumn.forEach((t, i) => {
-      if (!seen.has(t.key)) err(`totalsRow.perColumn[${i}].key "${t.key}" is not a column key`);
-    });
-  }
-
-  return { valid: errors.length === 0, errors, warnings };
-}
-
-/**
- * Reconcile a user's saved layout against the current config.
- *
- * A layout is preference, never permission — so this drops anything the user may no longer see and
- * fills gaps from the config. It cannot fail: the worst case is that the layout contributes nothing
- * and the user gets the default grid.
- *
- * @param {Object} config              the grid config
- * @param {Object|null} layout         the user's saved layout
- * @param {string[]|null} permittedKeys column keys the access engine allows (null = all)
- */
-export function applyLayout(config, layout, permittedKeys = null) {
-  const cols = Array.isArray(config?.columns) ? config.columns : [];
-  const allowed = permittedKeys ? new Set(permittedKeys) : null;
-  // Permission first, preference second. Reversing these would let a stale layout pin access.
-  const visible = cols.filter((c) => !allowed || allowed.has(c.key));
-
-  const saved = Array.isArray(layout?.columns) ? layout.columns.filter((k) => visible.some((c) => c.key === k)) : null;
-  const ordered = saved && saved.length
-    ? [
-      ...saved.map((k) => visible.find((c) => c.key === k)),
-      // Columns added to the config since the layout was saved stay available, just not pinned.
-      ...visible.filter((c) => !saved.includes(c.key)).map((c) => ({ ...c, defaultVisible: false })),
-    ]
-    : visible;
-
-  return {
-    columns: ordered.filter(Boolean),
-    filters: layout?.filters ?? {},
-    sort: layout?.sort ?? config?.defaultSort ?? null,
-    pageSize: layout?.pageSize ?? config?.pagination?.defaultSize ?? 25,
-    // True when the layout referenced something that no longer exists — the UI can offer a reset
-    // instead of leaving someone confused by a view that silently lost columns.
-    stale: !!(layout?.columns && saved && saved.length !== layout.columns.length),
-  };
-}
-
-export default {
-  COLUMN_TYPES, FILTER_TYPES, AGGREGATIONS, GRID_SCOPES, FILTER_DIALECT,
-  GRID_CONFIG_DEF, validateGridConfig, applyLayout,
-};
+/**
+ * DataGrid v2 config — @i4e/invest4edu-access-core (P4). Definitions + validator. No React, no DB.
+ *
+ * ONE config defines a listing end to end: where the rows come from, which columns exist and who
+ * sees each, the filters, the row/bulk actions, the export, and the summary cards. It lives in the
+ * shared package because three consumers must agree on it exactly — the UI renders it, v1 serves
+ * and re-evaluates it, and the admin screen edits it.
+ *
+ * ── Why it is strictly serialisable ──────────────────────────────────────────────────────────
+ * No functions anywhere. A column says `type: "currency"`, never `cell: (row) => …`. That is the
+ * single property that makes a grid storable, diffable, admin-editable and server-re-evaluable.
+ * The moment one config carries a callback, it can no longer be saved — and the whole model
+ * collapses back into per-screen code.
+ *
+ * ── Why access binding lives IN the config ───────────────────────────────────────────────────
+ * `feature_code` gates the grid, every action carries an `action_code`, and `visibleWhen` gates
+ * columns/filters/metrics. So "who may see this column" and "who may press this button" are
+ * answered by the same engine that answers "who may open this screen" — not by a second, parallel
+ * set of role checks inside a component.
+ *
+ * `source.collection` is what lets the SERVER apply tenant + product + record scope to the query
+ * (scopedMatch). Without it a grid could be pointed at a collection nobody has scoped.
+ *
+ * Design: nfd-ui-nextjs/IV-CodingAgent/specs/access-management/TDD-unified-access-and-subscription.md §8
+ */
+
+export const COLUMN_TYPES = Object.freeze([
+  "text", "number", "currency", "percent", "date", "datetime",
+  "boolean", "status-pill", "link", "actions", "inline-edit",
+]);
+
+export const FILTER_TYPES = Object.freeze([
+  "text", "select", "multiselect", "reference", "boolean", "exists", "daterange", "numberrange",
+]);
+
+export const AGGREGATIONS = Object.freeze(["sum", "avg", "count", "countWhere", "distinct", "raw"]);
+
+export const GRID_SCOPES = Object.freeze(["global", "account"]);
+
+/** The filter payload dialect the table and its summary endpoint MUST both speak. */
+export const FILTER_DIALECT = "grid-ast-v1";
+
+export const GRID_CONFIG_DEF = Object.freeze({
+  collection: "grid_configs",
+  fields: Object.freeze({
+    grid_code: { type: "String", required: true, index: true },
+    // Binds the whole grid to the access engine — no grid without a feature.
+    feature_code: { type: "String", required: true, index: true },
+    name: { type: "String" },
+    scope: { type: "String", enum: GRID_SCOPES, default: "global" },
+    // Set only on scope:'account' rows; the per-tenant override of a global config.
+    account_id: { type: "ObjectId", default: null, index: true },
+    config: { type: "Mixed", required: true },
+    // Bumped on every save. A saved user layout records the version it was made against, so the
+    // renderer can reconcile rather than break.
+    version: { type: "Number", default: 1 },
+    status: { type: "String", enum: ["active", "draft", "retired"], default: "draft" },
+    updated_by: { type: "ObjectId" },
+    updated_at: { type: "Date" },
+  }),
+  indexes: Object.freeze([
+    { keys: { grid_code: 1, scope: 1, account_id: 1 }, options: { unique: true } },
+  ]),
+});
+
+const isObj = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+const FEATURE_CODE = /^[A-Z][A-Z0-9_]*(\.[A-Z][A-Z0-9_]*){1,2}$/;
+
+/**
+ * Validate a grid config. Returns `{ valid, errors[], warnings[] }`.
+ *
+ * Errors are things that would render a broken or unsafe grid; warnings are things that are legal
+ * but almost certainly a mistake. The admin screen must block on errors and show warnings — a
+ * config is edited by a human and saved straight into what everyone sees, so "it saved fine and
+ * then the screen was empty" is the failure mode this exists to prevent.
+ */
+export function validateGridConfig(config) {
+  const errors = [];
+  const warnings = [];
+  const err = (m) => errors.push(m);
+  const warn = (m) => warnings.push(m);
+
+  if (!isObj(config)) return { valid: false, errors: ["config must be an object"], warnings };
+
+  if (!config.grid_code) err("grid_code is required");
+  if (!config.feature_code) err("feature_code is required — a grid must bind to the access engine");
+  else if (!FEATURE_CODE.test(config.feature_code)) err(`feature_code "${config.feature_code}" must be MODULE.SCREEN[.ACTION]`);
+
+  // ── source ──────────────────────────────────────────────────────────────────────────────────
+  const src = config.source;
+  if (!isObj(src)) err("source is required");
+  else {
+    if (!src.endpoint) err("source.endpoint is required");
+    // Without a collection the server cannot apply tenant/product/record scope to this grid.
+    if (!src.collection) err("source.collection is required — the server needs it to scope the query");
+    if (src.filter_dialect && src.filter_dialect !== FILTER_DIALECT) {
+      err(`source.filter_dialect must be "${FILTER_DIALECT}"`);
+    }
+    if (!src.id_field) warn("source.id_field not set — defaulting to _id");
+  }
+
+  // ── columns ─────────────────────────────────────────────────────────────────────────────────
+  const cols = Array.isArray(config.columns) ? config.columns : [];
+  if (!cols.length) err("at least one column is required");
+  const seen = new Set();
+  cols.forEach((c, i) => {
+    const at = `columns[${i}]`;
+    if (!isObj(c)) return err(`${at} must be an object`);
+    if (!c.key) err(`${at}.key is required`);
+    else if (seen.has(c.key)) err(`${at}.key "${c.key}" is duplicated — keys address saved layouts`);
+    else seen.add(c.key);
+    if (!c.header) warn(`${at} ("${c.key}") has no header`);
+    if (!c.path && c.type !== "actions") err(`${at} ("${c.key}") needs a path`);
+    if (c.type && !COLUMN_TYPES.includes(c.type)) err(`${at}.type "${c.type}" is not a known type`);
+    // A callback here is the one thing that would make the config unstorable.
+    for (const k of Object.keys(c)) {
+      if (typeof c[k] === "function") err(`${at}.${k} is a function — configs must be serialisable`);
+    }
+  });
+  if (cols.length && !cols.some((c) => c.defaultVisible !== false)) {
+    err("every column is hidden by default — the grid would render empty");
+  }
+
+  // ── filters ─────────────────────────────────────────────────────────────────────────────────
+  (config.filters || []).forEach((f, i) => {
+    const at = `filters[${i}]`;
+    if (!f?.key) err(`${at}.key is required`);
+    if (f?.type && !FILTER_TYPES.includes(f.type)) err(`${at}.type "${f.type}" is not a known type`);
+    if (f?.type === "select" && !f.options && !f.ref) {
+      warn(`${at} ("${f.key}") is a select with neither options nor ref — it will render empty`);
+    }
+  });
+
+  // ── actions: each is a FEATURE, so it must carry a code ─────────────────────────────────────
+  const checkActions = (list, label) => (list || []).forEach((a, i) => {
+    const at = `${label}[${i}]`;
+    if (!a?.action_code) {
+      err(`${at} has no action_code — actions are gated features, an ungated action is a hole`);
+    } else if (!FEATURE_CODE.test(a.action_code)) {
+      err(`${at}.action_code "${a.action_code}" must be MODULE.SCREEN.ACTION`);
+    }
+    if (!a?.label) warn(`${at} has no label`);
+    // Destructive things must ask. Cheap to require, expensive to forget.
+    if (a?.kind === "mutation" && /delete|cancel|remove|revoke/i.test(a.action_code || "") && !a.confirm) {
+      warn(`${at} ("${a.action_code}") looks destructive but has no confirm`);
+    }
+  });
+  checkActions(config.rowActions, "rowActions");
+  checkActions(config.bulkActions, "bulkActions");
+
+  if (config.export && !config.export.action_code) {
+    err("export needs an action_code — exports are gated and meterable like any other action");
+  }
+
+  // ── summary ─────────────────────────────────────────────────────────────────────────────────
+  if (config.summary) {
+    const s = config.summary;
+    if (!Array.isArray(s.metrics) || !s.metrics.length) warn("summary has no metrics");
+    // The rule the MIS rollups taught us: cards and the table must answer the same question.
+    if (s.source === "endpoint" && !s.endpoint) {
+      err("summary.source is 'endpoint' but no summary.endpoint is set");
+    }
+    (s.metrics || []).forEach((m, i) => {
+      const at = `summary.metrics[${i}]`;
+      if (!m?.key) err(`${at}.key is required`);
+      if (m?.agg && !AGGREGATIONS.includes(m.agg)) err(`${at}.agg "${m.agg}" is not a known aggregation`);
+      if (m?.agg && m.agg !== "count" && !m.path) err(`${at} ("${m.key}") needs a path for agg "${m.agg}"`);
+      if (m?.agg === "countWhere" && !m.where) err(`${at} ("${m.key}") is countWhere with no where clause`);
+    });
+  }
+
+  // ── pagination / sort ───────────────────────────────────────────────────────────────────────
+  if (config.pagination) {
+    const p = config.pagination;
+    if (p.defaultSize && Array.isArray(p.pageSizes) && !p.pageSizes.includes(p.defaultSize)) {
+      err(`pagination.defaultSize ${p.defaultSize} is not one of pageSizes`);
+    }
+  }
+  if (config.defaultSort?.key && !seen.has(config.defaultSort.key)) {
+    err(`defaultSort.key "${config.defaultSort.key}" is not a column key`);
+  }
+  if (config.totalsRow?.perColumn) {
+    config.totalsRow.perColumn.forEach((t, i) => {
+      if (!seen.has(t.key)) err(`totalsRow.perColumn[${i}].key "${t.key}" is not a column key`);
+    });
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}
+
+/**
+ * Reconcile a user's saved layout against the current config.
+ *
+ * A layout is preference, never permission — so this drops anything the user may no longer see and
+ * fills gaps from the config. It cannot fail: the worst case is that the layout contributes nothing
+ * and the user gets the default grid.
+ *
+ * @param {Object} config              the grid config
+ * @param {Object|null} layout         the user's saved layout
+ * @param {string[]|null} permittedKeys column keys the access engine allows (null = all)
+ */
+export function applyLayout(config, layout, permittedKeys = null) {
+  const cols = Array.isArray(config?.columns) ? config.columns : [];
+  const allowed = permittedKeys ? new Set(permittedKeys) : null;
+  // Permission first, preference second. Reversing these would let a stale layout pin access.
+  const visible = cols.filter((c) => !allowed || allowed.has(c.key));
+
+  const saved = Array.isArray(layout?.columns) ? layout.columns.filter((k) => visible.some((c) => c.key === k)) : null;
+  const ordered = saved && saved.length
+    ? [
+      ...saved.map((k) => visible.find((c) => c.key === k)),
+      // Columns added to the config since the layout was saved stay available, just not pinned.
+      ...visible.filter((c) => !saved.includes(c.key)).map((c) => ({ ...c, defaultVisible: false })),
+    ]
+    : visible;
+
+  return {
+    columns: ordered.filter(Boolean),
+    filters: layout?.filters ?? {},
+    sort: layout?.sort ?? config?.defaultSort ?? null,
+    pageSize: layout?.pageSize ?? config?.pagination?.defaultSize ?? 25,
+    // True when the layout referenced something that no longer exists — the UI can offer a reset
+    // instead of leaving someone confused by a view that silently lost columns.
+    stale: !!(layout?.columns && saved && saved.length !== layout.columns.length),
+  };
+}
+
+export default {
+  COLUMN_TYPES, FILTER_TYPES, AGGREGATIONS, GRID_SCOPES, FILTER_DIALECT,
+  GRID_CONFIG_DEF, validateGridConfig, applyLayout,
+};