@i4e/invest4edu-access-core 0.6.1 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@i4e/invest4edu-access-core",
-  "version": "0.6.1",
+  "version": "0.8.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": {
@@ -12,7 +12,10 @@
     "./access-config": "./src/access-config.js",
     "./access-schema": "./src/access-schema.js",
     "./access-resolver": "./src/access-resolver.js",
-    "./visible-when": "./src/visible-when.js"
+    "./visible-when": "./src/visible-when.js",
+    "./entitlement": "./src/entitlement.js",
+    "./entitlement-schema": "./src/entitlement-schema.js",
+    "./grid-schema": "./src/grid-schema.js"
   },
   "scripts": {
     "test": "node --test test/"

package/src/entitlement-schema.js

@@ -0,0 +1,183 @@
+/**
+ * Entitlement / subscription schema DEFINITIONS — @i4e/invest4edu-access-core (P6).
+ *
+ * Plain objects like access-schema.js (D4: no Mongoose in the package). Each backend registers its
+ * own models from these, so field names cannot drift between v1 and v2.
+ *
+ * RBAC answers "may they?"; entitlement answers "is it unlocked, and are they in quota?". Both must
+ * pass. See TDD §6, and §6.2a for the 2026-07-29 amendment that generalised quota period + subject
+ * and added the service-facing meter.
+ *
+ * Design: nfd-ui-nextjs/IV-CodingAgent/specs/access-management/TDD-unified-access-and-subscription.md
+ */
+
+/** How often a quota allowance resets. Carried in the period key, so no cron is needed. */
+export const PERIOD_GRANULARITIES = Object.freeze(["day", "month", "year", "term", "lifetime"]);
+
+/** Whose allowance is being spent. `account` = per firm (the legacy assumption); `user` = per seat. */
+export const QUOTA_SCOPES = Object.freeze(["account", "user"]);
+
+/** What happens when the allowance runs out. */
+export const OVERAGE_POLICIES = Object.freeze(["block", "single_usage", "unlimited"]);
+
+export const SUBSCRIPTION_STATUSES = Object.freeze([
+  "trialing", "active", "past_due", "blocked", "cancelled", "expired",
+]);
+
+/**
+ * The timezone every calendar boundary is evaluated in.
+ *
+ * A daily quota is meaningless without one: in UTC an Indian partner's "10 a day" would reset at
+ * 05:30 local, so they would lose the tail of every working day. Matches the `tz` the MIS pipelines
+ * already use.
+ */
+export const QUOTA_TIMEZONE = "Asia/Kolkata";
+
+/** Reasons an entitlement decision can carry. Stable strings — they surface in APIs and logs. */
+export const ENTITLEMENT_REASONS = Object.freeze({
+  OK: "ok",
+  NO_SUBSCRIPTION: "no_subscription",
+  NOT_IN_PLAN: "not_in_plan",
+  LOCKED: "locked",
+  QUOTA_EXCEEDED: "quota_exceeded",
+  SUBSCRIPTION_BLOCKED: "subscription_blocked",
+  ADMIN_BYPASS: "admin_bypass",
+  NOT_METERED: "not_metered",
+  ENGINE_OFF: "engine_off",
+  RESOLVE_FAILED: "resolve_failed",
+});
+
+/** Global: the plans on sale. */
+export const PLAN_CATALOG_DEF = Object.freeze({
+  collection: "plan_catalog",
+  fields: Object.freeze({
+    plan_code: { type: "String", required: true, unique: true, index: true, immutable: true },
+    name: { type: "String", required: true },
+    description: { type: "String" },
+    billing_cycle: { type: "String", enum: ["monthly", "quarterly", "annual"], default: "annual" },
+    price: { type: "Number", default: 0 },
+    currency: { type: "String", default: "INR" },
+    position: { type: "Number", default: 0 },
+    status: { type: "String", enum: ["active", "dormant", "retired"], default: "active" },
+  }),
+});
+
+/**
+ * Global: `(plan, cycle, feature)` → what that plan grants for that feature.
+ *
+ * VERSIONED by `effective_date`: resolve the row with the greatest `effective_date <= now`. Prices
+ * and quotas change, and a past invoice must remain explicable — so rows are superseded, never
+ * edited in place.
+ */
+export const PLAN_ENTITLEMENT_DEF = Object.freeze({
+  collection: "plan_entitlements",
+  fields: Object.freeze({
+    plan_code: { type: "String", required: true, index: true },
+    billing_cycle: { type: "String", required: true },
+    feature_code: { type: "String", required: true, index: true },
+
+    unlocked: { type: "Boolean", default: true },
+    // null = unlimited. 0 is a real value: "in the plan, but no allowance".
+    quota: { type: "Number", default: null },
+    period_granularity: { type: "String", enum: PERIOD_GRANULARITIES, default: "month" },
+    quota_scope: { type: "String", enum: QUOTA_SCOPES, default: "account" },
+    overage_policy: { type: "String", enum: OVERAGE_POLICIES, default: "block" },
+    single_usage_price: { type: "Number", default: null },
+
+    effective_date: { type: "Date", required: true, index: true },
+    superseded_date: { type: "Date", default: null },
+  }),
+  indexes: Object.freeze([
+    { keys: { plan_code: 1, billing_cycle: 1, feature_code: 1, effective_date: -1 } },
+  ]),
+});
+
+/** Tenant: one subscription per firm. Replaces AccountPlan + distributor.selected_plan. */
+export const ACCOUNT_SUBSCRIPTION_DEF = Object.freeze({
+  collection: "account_subscriptions",
+  fields: Object.freeze({
+    account_id: { type: "ObjectId", required: true, index: true },
+    plan_code: { type: "String", required: true },
+    billing_cycle: { type: "String", required: true },
+    status: { type: "String", enum: SUBSCRIPTION_STATUSES, default: "trialing", index: true },
+    start_date: { type: "Date", required: true },
+    end_date: { type: "Date", default: null },
+    is_trial: { type: "Boolean", default: false },
+    trial_ends_at: { type: "Date", default: null },
+    // Per-firm overrides of the plan row: [{ feature_code, quota, unlocked, … }]. Sales concessions
+    // belong here, NOT as an edit to the shared plan row.
+    entitlement_overrides: { type: "[Mixed]", default: [] },
+  }),
+});
+
+/**
+ * Tenant: the quota counters. MUST live in the app DB — `consume` has to be atomic with the read,
+ * so this cannot be a side/analytics store.
+ *
+ * `subject_key` is the account id or the user id depending on `quota_scope`, so one collection
+ * serves both without a second shape.
+ */
+export const SUBSCRIPTION_USAGE_DEF = Object.freeze({
+  collection: "subscription_usage",
+  fields: Object.freeze({
+    subscription_id: { type: "ObjectId", required: true, index: true },
+    subject_key: { type: "String", required: true },
+    feature_code: { type: "String", required: true },
+    period: { type: "String", required: true },
+    used: { type: "Number", default: 0 },
+    last_consumed_at: { type: "Date", default: null },
+  }),
+  indexes: Object.freeze([
+    { keys: { subscription_id: 1, subject_key: 1, feature_code: 1, period: 1 }, options: { unique: true } },
+  ]),
+});
+
+/**
+ * Tenant: the exactly-once ledger for `consume`.
+ *
+ * A tool that times out and retries must not charge the partner twice, so every consume carries an
+ * idempotency key and the unique index — not application logic — is what enforces it.
+ */
+export const USAGE_IDEMPOTENCY_DEF = Object.freeze({
+  collection: "usage_idempotency",
+  fields: Object.freeze({
+    idempotency_key: { type: "String", required: true, unique: true, index: true },
+    account_id: { type: "ObjectId", index: true },
+    feature_code: { type: "String", required: true },
+    subject_key: { type: "String" },
+    period: { type: "String" },
+    n: { type: "Number", default: 1 },
+    // The decision returned the first time, replayed verbatim on a duplicate key.
+    result: { type: "Mixed", default: null },
+    created_date: { type: "Date", default: "now" },
+  }),
+});
+
+/** Global: the service callers allowed to meter, and which features each may meter. */
+export const METER_CLIENT_DEF = Object.freeze({
+  collection: "meter_clients",
+  fields: Object.freeze({
+    client_code: { type: "String", required: true, unique: true, index: true },
+    name: { type: "String", required: true },
+    // Key Vault SECRET NAME, never the secret. An admin API must never be able to read it back.
+    key_vault_ref: { type: "String", required: true },
+    // A tool may only meter what it is registered for — a leaked NFD-AI key cannot spend PFA quota.
+    allowed_features: { type: "[String]", default: [] },
+    status: { type: "String", enum: ["active", "disabled"], default: "active" },
+  }),
+});
+
+export default {
+  PERIOD_GRANULARITIES,
+  QUOTA_SCOPES,
+  OVERAGE_POLICIES,
+  SUBSCRIPTION_STATUSES,
+  QUOTA_TIMEZONE,
+  ENTITLEMENT_REASONS,
+  PLAN_CATALOG_DEF,
+  PLAN_ENTITLEMENT_DEF,
+  ACCOUNT_SUBSCRIPTION_DEF,
+  SUBSCRIPTION_USAGE_DEF,
+  USAGE_IDEMPOTENCY_DEF,
+  METER_CLIENT_DEF,
+};

package/src/entitlement.js

@@ -0,0 +1,166 @@
+/**
+ * Entitlement resolution — @i4e/invest4edu-access-core (P6). Pure: no DB, no Mongoose.
+ *
+ * RBAC says whether a user MAY do a thing. This says whether the FIRM's plan has it unlocked and
+ * whether the allowance is spent. Both must pass (TDD §4.2).
+ *
+ * The one hard rule (§4.3): entitlement **fails open**. An outage in the entitlement path must
+ * never block a feature a customer has paid for — the worst acceptable outcome is that we
+ * occasionally fail to charge. `overage_policy: 'block'` is the only branch that denies, and only
+ * on a definite quota-exceeded answer.
+ */
+import {
+  ENTITLEMENT_REASONS as R,
+  QUOTA_TIMEZONE,
+  PERIOD_GRANULARITIES,
+} from "./entitlement-schema.js";
+
+export { ENTITLEMENT_REASONS } from "./entitlement-schema.js";
+
+/**
+ * Calendar parts of `date` in QUOTA_TIMEZONE.
+ *
+ * Deliberately via Intl rather than date arithmetic: an offset constant would be wrong the moment
+ * anything changes, and a naive `toISOString()` would put an Indian partner's daily reset at 05:30
+ * local — silently costing them the tail of every working day.
+ */
+function partsInZone(date, timeZone = QUOTA_TIMEZONE) {
+  const fmt = new Intl.DateTimeFormat("en-CA", {
+    timeZone, year: "numeric", month: "2-digit", day: "2-digit",
+  });
+  const [{ value: y }, , { value: m }, , { value: d }] = fmt.formatToParts(date);
+  return { y, m, d };
+}
+
+/**
+ * The bucket key an allowance is counted in. The granularity lives IN the key, so a reset needs no
+ * cron: at midnight the key simply changes and the new bucket starts at zero.
+ *
+ * @param {string} granularity   day | month | year | term | lifetime
+ * @param {Object} [opts]
+ * @param {Date}   [opts.now]
+ * @param {string} [opts.subscriptionId]  required for `term`
+ * @param {string} [opts.timeZone]
+ */
+export function periodKey(granularity, { now = new Date(), subscriptionId = null, timeZone } = {}) {
+  const g = PERIOD_GRANULARITIES.includes(granularity) ? granularity : "month";
+  if (g === "lifetime") return "lifetime";
+  // A term quota with no subscription would silently collapse every firm into one shared bucket.
+  if (g === "term") return subscriptionId ? `term:${String(subscriptionId)}` : "lifetime";
+
+  const { y, m, d } = partsInZone(now, timeZone);
+  if (g === "year") return y;
+  if (g === "month") return `${y}-${m}`;
+  return `${y}-${m}-${d}`;
+}
+
+/** Whose allowance this is: the firm, or the individual seat. */
+export function subjectKeyFor(quotaScope, { accountId, userId } = {}) {
+  return String((quotaScope === "user" ? userId : accountId) ?? "");
+}
+
+/**
+ * Pick the live entitlement row for a feature: greatest `effective_date <= now`, not superseded.
+ * Rows are versioned rather than edited so a past invoice stays explicable.
+ */
+export function resolveEntitlementRow(rows = [], featureCode, now = new Date()) {
+  return rows
+    .filter((r) => r
+      && r.feature_code === featureCode
+      && new Date(r.effective_date) <= now
+      && (!r.superseded_date || new Date(r.superseded_date) > now))
+    .sort((a, b) => new Date(b.effective_date) - new Date(a.effective_date))[0] || null;
+}
+
+/** Apply a per-firm override on top of the plan row. Concessions live on the subscription. */
+function withOverride(row, overrides = [], featureCode) {
+  const o = (overrides || []).find((x) => x && x.feature_code === featureCode);
+  if (!o) return row;
+  const merged = { ...row };
+  for (const k of ["unlocked", "quota", "period_granularity", "quota_scope", "overage_policy", "single_usage_price"]) {
+    if (o[k] !== undefined) merged[k] = o[k];
+  }
+  return merged;
+}
+
+/**
+ * Decide entitlement for one feature.
+ *
+ * @param {Object} p
+ * @param {Object|null} p.subscription       account_subscriptions row
+ * @param {Array}  p.entitlementRows         plan_entitlements rows for this plan+cycle
+ * @param {string} p.featureCode
+ * @param {Object} p.feature                 registry row — `is_meterable` decides if quota applies
+ * @param {number} p.used                    already consumed in this period (caller supplies)
+ * @param {Object} p.identity                { accountId, userId }
+ * @param {boolean} [p.bypass]               D27 admin break-glass
+ * @param {Date}   [p.now]
+ * @returns {Object} { unlocked, quota, used, remaining, allowed, overage_policy, reason,
+ *                     period, subject_key, metered }
+ */
+export function resolveEntitlement({
+  subscription, entitlementRows = [], featureCode, feature = {},
+  used = 0, identity = {}, bypass = false, now = new Date(),
+} = {}) {
+  const base = {
+    quota: null, used, remaining: null, period: null, subject_key: null,
+    overage_policy: "unlimited", metered: false,
+  };
+  const open = (reason) => ({ ...base, unlocked: true, allowed: true, reason });
+
+  // D27: the break-glass resolves every gate open, including this one.
+  if (bypass) return open(R.ADMIN_BYPASS);
+
+  // `always_available` exists so login/billing/profile survive a blocked subscription — otherwise a
+  // past-due firm could not reach the screen that takes their money.
+  if (feature.always_available) return open(R.OK);
+
+  // No subscription: fail OPEN. Absence of a row is far more likely to be our gap than a customer
+  // genuinely owning nothing, and denying would break every un-migrated firm on day one.
+  if (!subscription) return open(R.NO_SUBSCRIPTION);
+
+  if (subscription.status === "blocked" || subscription.status === "expired") {
+    return { ...base, unlocked: false, allowed: false, reason: R.SUBSCRIPTION_BLOCKED };
+  }
+
+  const row = withOverride(
+    resolveEntitlementRow(entitlementRows, featureCode, now),
+    subscription.entitlement_overrides,
+    featureCode,
+  );
+  // Not named in the plan: OPEN. A plan that forgot to list a feature is a config gap, and P6 must
+  // not silently switch features off for everyone the moment it ships.
+  if (!row) return open(R.NOT_IN_PLAN);
+
+  if (row.unlocked === false) {
+    return { ...base, unlocked: false, allowed: false, overage_policy: row.overage_policy, reason: R.LOCKED };
+  }
+
+  // Unlocked but not metered → nothing to count.
+  if (!feature.is_meterable || row.quota === null || row.quota === undefined) {
+    return { ...open(feature.is_meterable ? R.OK : R.NOT_METERED), overage_policy: row.overage_policy || "unlimited" };
+  }
+
+  const granularity = row.period_granularity || "month";
+  const period = periodKey(granularity, { now, subscriptionId: subscription._id });
+  const subject_key = subjectKeyFor(row.quota_scope, identity);
+  const remaining = Math.max(0, Number(row.quota) - Number(used || 0));
+  const withinQuota = Number(used || 0) < Number(row.quota);
+  const policy = row.overage_policy || "block";
+
+  return {
+    unlocked: true,
+    quota: Number(row.quota),
+    used: Number(used || 0),
+    remaining,
+    // Only `block` denies. single_usage/unlimited let the call through — billing catches up after.
+    allowed: withinQuota || policy !== "block",
+    overage_policy: policy,
+    reason: withinQuota ? R.OK : R.QUOTA_EXCEEDED,
+    period,
+    subject_key,
+    metered: true,
+  };
+}
+
+export default { resolveEntitlement, resolveEntitlementRow, periodKey, subjectKeyFor };

package/src/grid-schema.js

@@ -0,0 +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,
+};