@i4e/invest4edu-access-core 0.23.0 → 0.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@i4e/invest4edu-access-core",
-  "version": "0.23.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 });
 
@@ -171,13 +177,68 @@ export function resolveEntitlement({
   // not silently switch features off for everyone the moment it ships.
   if (!row) return open(R.NOT_IN_PLAN);
 
+  /**
+   * Locked: the plan does not carry this feature at all.
+   *
+   * A locked row is an ACCESS decision, so no allowance gets past it — that is what makes tiering
+   * mean anything. If a shared credit balance could unlock a locked feature, the cheap plan plus a
+   * top-up would be strictly better than the expensive plan, and the tier would collapse.
+   *
+   * A unit bought OUTRIGHT is different, and is the deliberate escape hatch: someone who paid for
+   * one portfolio analysis has bought that analysis, not access to the feature. `credits` here is
+   * always the balance for THIS feature — the caller resolves credits-mode plans down this same
+   * path precisely because their shared pool must not reach it — so consulting it cannot leak the
+   * pool. Nothing is on sale individually by default, which keeps this dormant until someone
+   * prices a service for it.
+   */
   if (row.unlocked === false) {
+    const owned = Math.max(0, Number(credits || 0));
+    if (owned >= 1) {
+      return {
+        ...base,
+        unlocked: true,
+        allowed: true,
+        credits: owned,
+        remaining: owned,
+        usingCredit: true,
+        metered: true,
+        quota: 0,
+        used: Number(used || 0),
+        overage_policy: row.overage_policy || "block",
+        reason: R.OK,
+        period: periodKey(row.period_granularity || "month", {
+          now, subscriptionId: subscription._id, periodStart: subscription.period_start,
+        }),
+        subject_key: subjectKeyFor(row.quota_scope, identity),
+        cost: 1,
+      };
+    }
     return { ...base, unlocked: false, allowed: false, overage_policy: row.overage_policy, reason: R.LOCKED };
   }
 
   // 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";
@@ -217,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,