@i4e/invest4edu-access-core 0.32.0 → 0.33.0

package/src/access-schema.js

@@ -1,174 +1,174 @@
-/**
- * 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"]);
-
-/**
- * How a SCREEN presents the product-keyed things it renders — product tiles, product tabs, the
- * product column on Add Order, scheme lists.
- *
- * Deliberately separate from `products[]` on the same feature, which is *reachability* ("this
- * screen exists only for these products"). The two are independent and neither implies the other:
- * Open Orders is product-agnostic (`products: []`, it serves every product) yet renders product
- * tabs that must be filtered; Product Setup is equally agnostic and should hide nothing. Same
- * reachability, opposite presentation — so this cannot be derived, it has to be declared.
- *
- *   none      render everything. The default, so every existing screen is unchanged.
- *   filter    hide product-keyed items outside the caller's scope. For transactional screens.
- *   readonly  show everything, but out-of-scope items are not interactive. For configuration
- *             screens, where hiding a product reads as "the catalogue is broken" rather than as
- *             "you may not touch this".
- *
- * This is presentation only. The server-side gate is what actually refuses a write — hiding a
- * tile has never stopped a POST.
- */
-export const PRODUCT_UI_MODES = Object.freeze(["none", "filter", "readonly"]);
-
-/** 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" },
-    product_ui: { type: "String", enum: PRODUCT_UI_MODES, default: "none" },
-
-    // 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,
-  PRODUCT_UI_MODES,
-  GRANT_EFFECTS,
-  GRANT_SUBJECTS,
-  FEATURE_CODE_PATTERN,
-  isValidFeatureCode,
-  parentCodeOf,
-  moduleCodeOf,
-  ACCESS_MODULE_DEF,
-  ACCESS_FEATURE_DEF,
-  ACCESS_GRANT_DEF,
-};
+/**
+ * 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"]);
+
+/**
+ * How a SCREEN presents the product-keyed things it renders — product tiles, product tabs, the
+ * product column on Add Order, scheme lists.
+ *
+ * Deliberately separate from `products[]` on the same feature, which is *reachability* ("this
+ * screen exists only for these products"). The two are independent and neither implies the other:
+ * Open Orders is product-agnostic (`products: []`, it serves every product) yet renders product
+ * tabs that must be filtered; Product Setup is equally agnostic and should hide nothing. Same
+ * reachability, opposite presentation — so this cannot be derived, it has to be declared.
+ *
+ *   none      render everything. The default, so every existing screen is unchanged.
+ *   filter    hide product-keyed items outside the caller's scope. For transactional screens.
+ *   readonly  show everything, but out-of-scope items are not interactive. For configuration
+ *             screens, where hiding a product reads as "the catalogue is broken" rather than as
+ *             "you may not touch this".
+ *
+ * This is presentation only. The server-side gate is what actually refuses a write — hiding a
+ * tile has never stopped a POST.
+ */
+export const PRODUCT_UI_MODES = Object.freeze(["none", "filter", "readonly"]);
+
+/** 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" },
+    product_ui: { type: "String", enum: PRODUCT_UI_MODES, default: "none" },
+
+    // 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,
+  PRODUCT_UI_MODES,
+  GRANT_EFFECTS,
+  GRANT_SUBJECTS,
+  FEATURE_CODE_PATTERN,
+  isValidFeatureCode,
+  parentCodeOf,
+  moduleCodeOf,
+  ACCESS_MODULE_DEF,
+  ACCESS_FEATURE_DEF,
+  ACCESS_GRANT_DEF,
+};

package/src/credits.js

@@ -1,128 +1,128 @@
-/**
- * Credits — what happens to an unused allowance when a term ends.
- *
- * A credits plan hands out an allowance per term (500 credits a month) and every service spends
- * from it at its own price. At the term boundary the counter resets, and the question nobody can
- * avoid answering is what the unspent remainder was worth. Silence is itself an answer — the
- * default today is that it evaporates, which is fine as a policy and indefensible as an accident.
- *
- * ── Rollover is a POLICY, resolved in layers ─────────────────────────────────────────────────
- * platform default < plan. Same shape and same merge rule as proration, because they are the
- * same kind of decision: what unused value is worth when the ground moves under it.
- *
- * ── The rules that are NOT configurable, because getting them wrong invents credits ──────────
- *   · you can never roll more than went unused — the cap trims, it never tops up
- *   · an unlimited allowance rolls nothing: there was no scarcity to carry forward
- *   · rounding is DOWN, so a rollover never hands out a credit that was not left over
- *   · rolled credits expire; carrying them forever turns a monthly allowance into a savings
- *     account and makes the liability unbounded. They lapse at the end of the term they land in
- *
- * Kept pure — no database, no clock, no subscription — so the arithmetic is testable on its own.
- */
-
-/** Every knob, with the conservative answer as the default. */
-export const CREDITS_DEFAULTS = {
-  /**
-   *   none   — the remainder lapses at the term boundary (today's behaviour)
-   *   full   — everything unused carries into the next term
-   *   capped — carries, but no more than `cap_percent` of the allowance
-   */
-  rollover_mode: "none",
-  /** Ceiling on what may roll, as a percentage of the term's allowance. Only used by `capped`. */
-  rollover_cap_percent: 50,
-  /**
-   * How long rolled credits survive, in terms. 1 = they must be used in the term they land in.
-   * Rolled credits never roll again regardless — carrying a carry compounds into a balance that
-   * no one budgeted for.
-   */
-  rollover_expires_in_terms: 1,
-};
-
-/**
- * Merge policy layers. Later wins, and only for keys it actually specifies — a plan that sets
- * only the mode must not silently reset a cap someone configured globally.
- */
-export function resolveCreditsPolicy(...layers) {
-  const out = { ...CREDITS_DEFAULTS };
-  for (const layer of layers) {
-    if (!layer || typeof layer !== "object") continue;
-    for (const k of Object.keys(CREDITS_DEFAULTS)) {
-      if (layer[k] !== undefined && layer[k] !== null) out[k] = layer[k];
-    }
-  }
-  return out;
-}
-
-/**
- * How many credits carry into the next term.
- *
- * @param {object}  a
- * @param {number|null} a.quota  the term's allowance. null = unlimited ⇒ nothing to carry
- * @param {number}  a.used       credits spent this term
- * @param {object}  a.policy     resolved policy (see resolveCreditsPolicy)
- * @returns {{units:number, reason:string, unused:number, cap:number|null, mode:string}}
- */
-export function computeRollover({ quota, used = 0, policy = CREDITS_DEFAULTS } = {}) {
-  const p = resolveCreditsPolicy(policy);
-  const mode = p.rollover_mode;
-  const nil = (reason) => ({ units: 0, reason, unused: 0, cap: null, mode });
-
-  if (mode === "none") return nil("rollover is off");
-  // Unlimited means the allowance never constrained anything, so there is no remainder to carry.
-  // Rolling "infinity minus what you used" is not a number, and any finite stand-in is invented.
-  if (quota == null) return nil("allowance is unlimited — nothing to carry");
-
-  const allowance = Number(quota);
-  if (!Number.isFinite(allowance) || allowance <= 0) return nil("no allowance this term");
-
-  const spent = Math.max(0, Number(used) || 0);
-  // Overage can push `used` past the quota under a warn policy; a negative remainder is not a debt.
-  const unused = Math.max(0, allowance - spent);
-  if (unused <= 0) return { units: 0, reason: "allowance fully used", unused: 0, cap: null, mode };
-
-  if (mode === "full") {
-    return { units: Math.floor(unused), reason: "carried in full", unused, cap: null, mode };
-  }
-
-  if (mode === "capped") {
-    const pct = Math.max(0, Math.min(100, Number(p.rollover_cap_percent) || 0));
-    const cap = Math.floor((allowance * pct) / 100);
-    const units = Math.min(Math.floor(unused), cap);
-    return {
-      units,
-      reason: units < unused ? `capped at ${pct}% of the allowance` : "carried in full (under the cap)",
-      unused,
-      cap,
-      mode,
-    };
-  }
-
-  // An unrecognised mode is a config error. Carrying nothing is the safe reading of it — the
-  // alternative invents a balance from a typo.
-  return nil(`unknown rollover mode "${mode}"`);
-}
-
-/**
- * When rolled credits lapse: the end of the term they can be used in.
- *
- * Needs the length of the term they are landing in, which the caller knows and this module
- * deliberately does not. A term with no end (open-ended subscription) yields null — nothing to
- * expire against, and inventing a date would silently destroy paid-for value.
- */
-export function rolloverExpiryDate({ nextPeriodStart, nextPeriodEnd, policy = CREDITS_DEFAULTS } = {}) {
-  const p = resolveCreditsPolicy(policy);
-  if (!nextPeriodEnd) return null;
-  const end = new Date(nextPeriodEnd);
-  if (Number.isNaN(end.getTime())) return null;
-
-  const terms = Math.max(1, Math.floor(Number(p.rollover_expires_in_terms) || 1));
-  if (terms === 1) return end;
-
-  // More than one term: extend by the length of the term they land in, which is the only measure
-  // of "a term" available here. Without a start we cannot know that length, so we keep the single
-  // term rather than guess — under-granting is recoverable, over-granting is not.
-  const start = nextPeriodStart ? new Date(nextPeriodStart) : null;
-  if (!start || Number.isNaN(start.getTime()) || start >= end) return end;
-  const termMs = end.getTime() - start.getTime();
-  return new Date(end.getTime() + termMs * (terms - 1));
-}
+/**
+ * Credits — what happens to an unused allowance when a term ends.
+ *
+ * A credits plan hands out an allowance per term (500 credits a month) and every service spends
+ * from it at its own price. At the term boundary the counter resets, and the question nobody can
+ * avoid answering is what the unspent remainder was worth. Silence is itself an answer — the
+ * default today is that it evaporates, which is fine as a policy and indefensible as an accident.
+ *
+ * ── Rollover is a POLICY, resolved in layers ─────────────────────────────────────────────────
+ * platform default < plan. Same shape and same merge rule as proration, because they are the
+ * same kind of decision: what unused value is worth when the ground moves under it.
+ *
+ * ── The rules that are NOT configurable, because getting them wrong invents credits ──────────
+ *   · you can never roll more than went unused — the cap trims, it never tops up
+ *   · an unlimited allowance rolls nothing: there was no scarcity to carry forward
+ *   · rounding is DOWN, so a rollover never hands out a credit that was not left over
+ *   · rolled credits expire; carrying them forever turns a monthly allowance into a savings
+ *     account and makes the liability unbounded. They lapse at the end of the term they land in
+ *
+ * Kept pure — no database, no clock, no subscription — so the arithmetic is testable on its own.
+ */
+
+/** Every knob, with the conservative answer as the default. */
+export const CREDITS_DEFAULTS = {
+  /**
+   *   none   — the remainder lapses at the term boundary (today's behaviour)
+   *   full   — everything unused carries into the next term
+   *   capped — carries, but no more than `cap_percent` of the allowance
+   */
+  rollover_mode: "none",
+  /** Ceiling on what may roll, as a percentage of the term's allowance. Only used by `capped`. */
+  rollover_cap_percent: 50,
+  /**
+   * How long rolled credits survive, in terms. 1 = they must be used in the term they land in.
+   * Rolled credits never roll again regardless — carrying a carry compounds into a balance that
+   * no one budgeted for.
+   */
+  rollover_expires_in_terms: 1,
+};
+
+/**
+ * Merge policy layers. Later wins, and only for keys it actually specifies — a plan that sets
+ * only the mode must not silently reset a cap someone configured globally.
+ */
+export function resolveCreditsPolicy(...layers) {
+  const out = { ...CREDITS_DEFAULTS };
+  for (const layer of layers) {
+    if (!layer || typeof layer !== "object") continue;
+    for (const k of Object.keys(CREDITS_DEFAULTS)) {
+      if (layer[k] !== undefined && layer[k] !== null) out[k] = layer[k];
+    }
+  }
+  return out;
+}
+
+/**
+ * How many credits carry into the next term.
+ *
+ * @param {object}  a
+ * @param {number|null} a.quota  the term's allowance. null = unlimited ⇒ nothing to carry
+ * @param {number}  a.used       credits spent this term
+ * @param {object}  a.policy     resolved policy (see resolveCreditsPolicy)
+ * @returns {{units:number, reason:string, unused:number, cap:number|null, mode:string}}
+ */
+export function computeRollover({ quota, used = 0, policy = CREDITS_DEFAULTS } = {}) {
+  const p = resolveCreditsPolicy(policy);
+  const mode = p.rollover_mode;
+  const nil = (reason) => ({ units: 0, reason, unused: 0, cap: null, mode });
+
+  if (mode === "none") return nil("rollover is off");
+  // Unlimited means the allowance never constrained anything, so there is no remainder to carry.
+  // Rolling "infinity minus what you used" is not a number, and any finite stand-in is invented.
+  if (quota == null) return nil("allowance is unlimited — nothing to carry");
+
+  const allowance = Number(quota);
+  if (!Number.isFinite(allowance) || allowance <= 0) return nil("no allowance this term");
+
+  const spent = Math.max(0, Number(used) || 0);
+  // Overage can push `used` past the quota under a warn policy; a negative remainder is not a debt.
+  const unused = Math.max(0, allowance - spent);
+  if (unused <= 0) return { units: 0, reason: "allowance fully used", unused: 0, cap: null, mode };
+
+  if (mode === "full") {
+    return { units: Math.floor(unused), reason: "carried in full", unused, cap: null, mode };
+  }
+
+  if (mode === "capped") {
+    const pct = Math.max(0, Math.min(100, Number(p.rollover_cap_percent) || 0));
+    const cap = Math.floor((allowance * pct) / 100);
+    const units = Math.min(Math.floor(unused), cap);
+    return {
+      units,
+      reason: units < unused ? `capped at ${pct}% of the allowance` : "carried in full (under the cap)",
+      unused,
+      cap,
+      mode,
+    };
+  }
+
+  // An unrecognised mode is a config error. Carrying nothing is the safe reading of it — the
+  // alternative invents a balance from a typo.
+  return nil(`unknown rollover mode "${mode}"`);
+}
+
+/**
+ * When rolled credits lapse: the end of the term they can be used in.
+ *
+ * Needs the length of the term they are landing in, which the caller knows and this module
+ * deliberately does not. A term with no end (open-ended subscription) yields null — nothing to
+ * expire against, and inventing a date would silently destroy paid-for value.
+ */
+export function rolloverExpiryDate({ nextPeriodStart, nextPeriodEnd, policy = CREDITS_DEFAULTS } = {}) {
+  const p = resolveCreditsPolicy(policy);
+  if (!nextPeriodEnd) return null;
+  const end = new Date(nextPeriodEnd);
+  if (Number.isNaN(end.getTime())) return null;
+
+  const terms = Math.max(1, Math.floor(Number(p.rollover_expires_in_terms) || 1));
+  if (terms === 1) return end;
+
+  // More than one term: extend by the length of the term they land in, which is the only measure
+  // of "a term" available here. Without a start we cannot know that length, so we keep the single
+  // term rather than guess — under-granting is recoverable, over-granting is not.
+  const start = nextPeriodStart ? new Date(nextPeriodStart) : null;
+  if (!start || Number.isNaN(start.getTime()) || start >= end) return end;
+  const termMs = end.getTime() - start.getTime();
+  return new Date(end.getTime() + termMs * (terms - 1));
+}