@i4e/invest4edu-access-core 0.22.0 → 0.24.0

package/package.json

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

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

package/src/subscription-lifecycle.js

@@ -70,6 +70,12 @@ export const SUBSCRIPTION_EVENT_TYPES = Object.freeze([
   // Consumption that happened outside the software — a webinar attended, a VPD session held.
   // There is no request behind it, so this event is the only record of who said it happened.
   "usage_recorded",
+  /**
+   * A term closed with credits unspent and the plan's policy carried them forward. Worth its own
+   * type because a customer WILL ask why their balance is bigger than their allowance, and the
+   * answer — which period it came from, how much, and what the cap did — has to be findable.
+   */
+  "credits_rolled_over",
   /**
    * The refund conversation, recorded as it happens rather than reconstructed afterwards.
    *