@i4e/invest4edu-access-core 0.21.0 → 0.23.0

package/package.json

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

@@ -134,9 +134,10 @@ export function createEntitlementStore({ getDb, toObjectId = (v) => v, logger =
         // Not named in a credits plan → the same fail-open NOT_IN_PLAN as count mode. A plan
         // that forgot to include a feature is a config gap, not a paywall.
         if (svcRow && svcRow.unlocked !== false) {
-          const cost = Number(svcRow.credit_cost) > 0
-            ? Number(svcRow.credit_cost)
-            : (Number(feature.credit_cost) > 0 ? Number(feature.credit_cost) : 1);
+          // UNSET falls through to the next layer; 0 does not — it is the plan saying "free".
+          const priced = (v) => (v === null || v === undefined || v === "" || !Number.isFinite(Number(v)) || Number(v) < 0
+            ? null : Number(v));
+          const cost = priced(svcRow.credit_cost) ?? priced(feature.credit_cost) ?? 1;
 
           let packBalance = 0;
           try {
@@ -332,7 +333,14 @@ export function createEntitlementStore({ getDb, toObjectId = (v) => v, logger =
        * here could draw from a bucket nobody checked, at a price nobody quoted.
        */
       const bucketCode = entitlement?.carriedFeatureCode || featureCode;
-      const units = n * (Number(entitlement?.carriedCost) > 0 ? Number(entitlement.carriedCost) : 1);
+      const carried = Number(entitlement?.carriedCost);
+      const units = n * (Number.isFinite(carried) && carried >= 0 ? carried : 1);
+
+      /**
+       * A free action inside a credits plan: authorised, but there is no balance to move. Writing
+       * a zero increment would still create the row and make it look like something was spent.
+       */
+      if (units === 0) return { consumed: true, free: true };
 
       // The SAME bucket that entitlementFor just checked — recomputing it from different inputs
       // would count against a period nobody validated.

package/src/entitlement.js

@@ -183,7 +183,18 @@ export function resolveEntitlement({
   const granularity = row.period_granularity || "month";
   const period = periodKey(granularity, { now, subscriptionId: subscription._id, periodStart: subscription.period_start });
   const subject_key = subjectKeyFor(row.quota_scope, identity);
-  const unitCost = Number(cost) > 0 ? Number(cost) : 1;
+  /**
+   * Zero is a PRICE, not a missing value.
+   *
+   * "Included, costs nothing" is a thing a credits plan has to be able to say, and the most
+   * important thing it says it about is placing an order: metered, unlimited on every plan today,
+   * and the last action that should ever be refused for an empty balance. Coercing 0 up to 1
+   * would quietly put revenue behind the credit meter.
+   */
+  // null and "" are UNSET, and Number() turns both into 0 — which would read as "free" and hand
+  // away exactly what this branch exists to protect. Only a real number counts as a price.
+  const raw = cost === null || cost === undefined || cost === "" ? 1 : Number(cost);
+  const unitCost = Number.isFinite(raw) && raw >= 0 ? raw : 1;
   const planRemaining = Math.max(0, Number(row.quota) - Number(used || 0));
   // Cost-aware: the action is allowed only if the WHOLE cost fits. Refusing at balance < cost is
   // the agreed rule — a balance never goes negative on an in-flight action.

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.
    *