@i4e/invest4edu-access-core 0.24.0 → 0.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@i4e/invest4edu-access-core",
-  "version": "0.24.0",
+  "version": "0.25.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": {

package/src/entitlement.js

@@ -144,6 +144,12 @@ export function resolveEntitlement({
   const base = {
     quota: null, used, remaining: null, period: null, subject_key: null,
     overage_policy: "unlimited", metered: false,
+    /**
+     * A CEILING that shapes a response — top-N picks, tips per answer — as opposed to `quota`,
+     * which is a budget that decrements. Null when the plan sets none. Present on every result so
+     * a caller never has to tell "no ceiling" from "this resolver is too old to send one".
+     */
+    limit: null,
   };
   const open = (reason) => ({ ...base, unlocked: true, allowed: true, reason });
 
@@ -211,8 +217,28 @@ export function resolveEntitlement({
   }
 
   // Unlocked but not metered → nothing to count.
+  /**
+   * Unlocked but not counted.
+   *
+   * `limit` is carried through even though nothing is metered, because a number on an unmetered
+   * row is a CEILING rather than a budget: "your top-picks list shows 5" is read on every request
+   * and never decrements. Returning it lets a caller shape its response from the plan instead of
+   * hard-coding the shape, which is the difference between a config edit and a deploy.
+   *
+   * `quota` deliberately stays null here — it means "how much is left", and nothing is being
+   * spent. Reusing it for a ceiling would make `remaining` a lie and invite a consume() call that
+   * should never happen.
+   */
   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" };
+    // null/undefined is UNSET, and Number() turns both into 0 — which would read as "show
+    // nothing", the exact opposite. Only a real number is a ceiling.
+    const raw = row.quota;
+    const ceiling = raw === null || raw === undefined || raw === "" ? null : Number(raw);
+    return {
+      ...open(feature.is_meterable ? R.OK : R.NOT_METERED),
+      overage_policy: row.overage_policy || "unlimited",
+      limit: ceiling !== null && Number.isFinite(ceiling) && ceiling >= 0 ? ceiling : null,
+    };
   }
 
   const granularity = row.period_granularity || "month";
@@ -252,6 +278,8 @@ export function resolveEntitlement({
 
   return {
     unlocked: true,
+    // Declared even on a metered result: absence must never be mistaken for "no ceiling".
+    limit: null,
     quota: Number(row.quota),
     used: Number(used || 0),
     remaining,