@i4e/invest4edu-access-core 0.32.0 → 0.33.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,
+};

package/src/index.js

@@ -1,74 +1,75 @@
-/**
- * @i4e/invest4edu-access-core — shared access-control primitives for the NFD backends.
- * Tenant isolation (D1 keystone) + role capabilities (G7).
- */
-export { default as als, runWithTenant, runAsSystem, getTenantStore } from "./tenant-context.js";
-export {
-  default as tenantPlugin,
-  setTenantMode,
-  getTenantMode,
-  setTenantWriteMode,
-  getTenantWriteMode,
-  TENANT_MODES,
-} from "./tenant-plugin.js";
-export {
-  CAPABILITY_FLAGS,
-  DEFAULT_ROLE_CAPABILITIES,
-  buildCapabilityMap,
-  resolveCapabilities,
-} from "./role-capabilities.js";
-export { resolveReporteeUserIds } from "./reportee-tree.js";
-export {
-  ENTITY,
-  ENTITY_STATUS,
-  isEntityLoginAllowed,
-  entityInactiveMessage,
-  checkPortalEntityAccess,
-} from "./entity-status.js";
-export {
-  CONFLICTING_ENTITIES,
-  conflictingEntityFor,
-  entityConflictMessage,
-} from "./user-entity-link.js";
-export {
-  CLIENT_APP_ROLE_NAMES,
-  ROLE_TYPE_PRIORITY,
-  pickPortalRoleName,
-} from "./portal-roles.js";
-export {
-  DEFAULT_ACCESS_FLAGS,
-  ACCESS_FLAG_ENV_NAMES,
-  flagEnvName,
-  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";
+/**
+ * @i4e/invest4edu-access-core — shared access-control primitives for the NFD backends.
+ * Tenant isolation (D1 keystone) + role capabilities (G7).
+ */
+export { default as als, runWithTenant, runAsSystem, getTenantStore } from "./tenant-context.js";
+export {
+  default as tenantPlugin,
+  setTenantMode,
+  getTenantMode,
+  setTenantWriteMode,
+  getTenantWriteMode,
+  TENANT_MODES,
+} from "./tenant-plugin.js";
+export {
+  CAPABILITY_FLAGS,
+  DEFAULT_ROLE_CAPABILITIES,
+  buildCapabilityMap,
+  resolveCapabilities,
+} from "./role-capabilities.js";
+export { resolveReporteeUserIds } from "./reportee-tree.js";
+export {
+  ENTITY,
+  ENTITY_STATUS,
+  isEntityLoginAllowed,
+  entityInactiveMessage,
+  checkPortalEntityAccess,
+} from "./entity-status.js";
+export {
+  CONFLICTING_ENTITIES,
+  conflictingEntityFor,
+  entityConflictMessage,
+} from "./user-entity-link.js";
+export {
+  CLIENT_APP_ROLE_NAMES,
+  ROLE_TYPE_PRIORITY,
+  pickPortalRoleName,
+} from "./portal-roles.js";
+export {
+  DEFAULT_ACCESS_FLAGS,
+  ACCESS_FLAG_ENV_NAMES,
+  flagEnvName,
+  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 { normalizeRoute, screenForRoute } from "./route-screen.js";
+export {
+  resolveAccessSnapshot,
+  mergeGrants,
+  buildNav,
+  hasFeature,
+  isUsable,
+  ENTITLEMENT_REASONS,
+} from "./access-resolver.js";
+export {
+  evaluateVisibleWhen,
+  filterVisible,
+  applyRelabel,
+  resolveColumns,
+} from "./visible-when.js";