@i4e/invest4edu-access-core 0.31.0 → 0.32.0

package/src/entitlement.js

@@ -1,300 +1,300 @@
-/**
- * Entitlement resolution — @i4e/invest4edu-access-core (P6). Pure: no DB, no Mongoose.
- *
- * RBAC says whether a user MAY do a thing. This says whether the FIRM's plan has it unlocked and
- * whether the allowance is spent. Both must pass (TDD §4.2).
- *
- * The one hard rule (§4.3): entitlement **fails open**. An outage in the entitlement path must
- * never block a feature a customer has paid for — the worst acceptable outcome is that we
- * occasionally fail to charge. `overage_policy: 'block'` is the only branch that denies, and only
- * on a definite quota-exceeded answer.
- */
-import {
-  ENTITLEMENT_REASONS as R,
-  QUOTA_TIMEZONE,
-  PERIOD_GRANULARITIES,
-} from "./entitlement-schema.js";
-
-export { ENTITLEMENT_REASONS } from "./entitlement-schema.js";
-
-/**
- * Calendar parts of `date` in QUOTA_TIMEZONE.
- *
- * Deliberately via Intl rather than date arithmetic: an offset constant would be wrong the moment
- * anything changes, and a naive `toISOString()` would put an Indian partner's daily reset at 05:30
- * local — silently costing them the tail of every working day.
- */
-function partsInZone(date, timeZone = QUOTA_TIMEZONE) {
-  const fmt = new Intl.DateTimeFormat("en-CA", {
-    timeZone, year: "numeric", month: "2-digit", day: "2-digit",
-  });
-  const [{ value: y }, , { value: m }, , { value: d }] = fmt.formatToParts(date);
-  return { y, m, d };
-}
-
-/**
- * The bucket key an allowance is counted in. The granularity lives IN the key, so a reset needs no
- * cron: at midnight the key simply changes and the new bucket starts at zero.
- *
- * @param {string} granularity   day | month | year | term | lifetime
- * @param {Object} [opts]
- * @param {Date}   [opts.now]
- * @param {string} [opts.subscriptionId]  required for `term`
- * @param {Date|string} [opts.periodStart] the current term's start — rolls the `term` bucket
- * @param {string} [opts.timeZone]
- */
-export function periodKey(granularity, { now = new Date(), subscriptionId = null, periodStart = null, timeZone } = {}) {
-  const g = PERIOD_GRANULARITIES.includes(granularity) ? granularity : "month";
-  if (g === "lifetime") return "lifetime";
-  // A term quota with no subscription would silently collapse every firm into one shared bucket.
-  /**
-   * A term bucket is one BILLING TERM, not the subscription's whole life.
-   *
-   * Keying on the subscription alone looks right and is subtly wrong: a subscription document
-   * survives its own transitions — trial becomes paid, a plan is downgraded then upgraded, a year
-   * renews — all on the same `_id`. So an annual allowance consumed during a trial would come out
-   * of the year the customer then paid for. Including where the term STARTED rolls the bucket
-   * every time the term does.
-   *
-   * Without a start date it degrades to the old lifetime-of-subscription key rather than throwing,
-   * because a missing date must not silently move everyone into one shared bucket.
-   */
-  if (g === "term") {
-    if (!subscriptionId) return "lifetime";
-    if (!periodStart) return `term:${String(subscriptionId)}`;
-    const start = periodStart instanceof Date ? periodStart : new Date(periodStart);
-    if (Number.isNaN(start.getTime())) return `term:${String(subscriptionId)}`;
-    return `term:${String(subscriptionId)}:${start.toISOString().slice(0, 10)}`;
-  }
-
-  const { y, m, d } = partsInZone(now, timeZone);
-  if (g === "year") return y;
-  if (g === "month") return `${y}-${m}`;
-  return `${y}-${m}-${d}`;
-}
-
-/** Whose allowance this is: the firm, or the individual seat. */
-export function subjectKeyFor(quotaScope, { accountId, userId } = {}) {
-  return String((quotaScope === "user" ? userId : accountId) ?? "");
-}
-
-/**
- * Pick the live entitlement row for a feature: greatest `effective_date <= now`, not superseded.
- * Rows are versioned rather than edited so a past invoice stays explicable.
- */
-export function resolveEntitlementRow(rows = [], featureCode, now = new Date()) {
-  return rows
-    .filter((r) => r
-      && r.feature_code === featureCode
-      && new Date(r.effective_date) <= now
-      && (!r.superseded_date || new Date(r.superseded_date) > now))
-    .sort((a, b) => new Date(b.effective_date) - new Date(a.effective_date))[0] || null;
-}
-
-/** Apply a per-firm override on top of the plan row. Concessions live on the subscription. */
-function withOverride(row, overrides = [], featureCode) {
-  /**
-   * Two shapes in the wild, and getting this wrong is silent AND total.
-   *
-   * Everything that WRITES an override — the model, the admin API, the Subscribers view — uses an
-   * object map keyed by feature code. This function only understood an array, so `.find` on the
-   * object threw, `resolveEntitlement` failed open, and the subscriber stopped being metered
-   * altogether. Setting a per-customer allowance therefore disabled that customer's counting —
-   * the opposite of the intent, with no error anywhere.
-   *
-   * Both shapes are accepted now. The map is the canonical one.
-   */
-  const o = Array.isArray(overrides)
-    ? overrides.find((x) => x && x.feature_code === featureCode)
-    : (overrides && typeof overrides === "object" ? overrides[featureCode] : null);
-  if (!o) return row;
-  const merged = { ...row };
-  for (const k of ["unlocked", "quota", "period_granularity", "quota_scope", "overage_policy", "single_usage_price"]) {
-    if (o[k] !== undefined) merged[k] = o[k];
-  }
-  return merged;
-}
-
-/**
- * Decide entitlement for one feature.
- *
- * @param {Object} p
- * @param {Object|null} p.subscription       account_subscriptions row
- * @param {Array}  p.entitlementRows         plan_entitlements rows for this plan+cycle
- * @param {string} p.featureCode
- * @param {Object} p.feature                 registry row — `is_meterable` decides if quota applies
- * @param {number} p.used                    already consumed in this period (caller supplies)
- * @param {number} [p.credits]               à-la-carte units bought and not yet spent
- * @param {Object} p.identity                { accountId, userId }
- * @param {boolean} [p.bypass]               D27 admin break-glass
- * @param {Date}   [p.now]
- * @returns {Object} { unlocked, quota, used, remaining, allowed, overage_policy, reason,
- *                     period, subject_key, metered }
- */
-export function resolveEntitlement({
-  subscription, entitlementRows = [], featureCode, feature = {},
-  used = 0, credits = 0, identity = {}, bypass = false, now = new Date(),
-  /**
-   * Units this ONE action costs. 1 for count-mode (used + 1 ≤ quota is exactly the old
-   * used < quota), the service's credit cost when a credits-mode plan is paying. Threading it
-   * through here is what lets one resolver serve both modes instead of a parallel copy.
-   */
-  cost = 1,
-} = {}) {
-  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 });
-
-  // D27: the break-glass resolves every gate open, including this one.
-  if (bypass) return open(R.ADMIN_BYPASS);
-
-  // `always_available` exists so login/billing/profile survive a blocked subscription — otherwise a
-  // past-due firm could not reach the screen that takes their money.
-  if (feature.always_available) return open(R.OK);
-
-  // No subscription: fail OPEN. Absence of a row is far more likely to be our gap than a customer
-  // genuinely owning nothing, and denying would break every un-migrated firm on day one.
-  if (!subscription) return open(R.NO_SUBSCRIPTION);
-
-  if (subscription.status === "blocked" || subscription.status === "expired") {
-    return { ...base, unlocked: false, allowed: false, reason: R.SUBSCRIPTION_BLOCKED };
-  }
-
-  const row = withOverride(
-    resolveEntitlementRow(entitlementRows, featureCode, now),
-    subscription.entitlement_overrides,
-    featureCode,
-  );
-  // Not named in the plan: OPEN. A plan that forgot to list a feature is a config gap, and P6 must
-  // 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) {
-    // 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";
-  const period = periodKey(granularity, { now, subscriptionId: subscription._id, periodStart: subscription.period_start });
-  const subject_key = subjectKeyFor(row.quota_scope, identity);
-  /**
-   * 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.
-  const withinQuota = Number(used || 0) + unitCost <= Number(row.quota);
-  const policy = row.overage_policy || "block";
-
-  /**
-   * À-la-carte credits — units bought one at a time rather than as part of a plan.
-   *
-   * They top up the plan's allowance rather than replacing it, and are spent ONLY once the plan
-   * allowance is gone. That ordering is the whole point: someone who bought ten extra analyses and
-   * then renews should not find their purchase quietly consumed by a month they had covered
-   * anyway. Plan first, purchase second.
-   *
-   * Credits do not reset with the period — they were paid for, so they last until used.
-   */
-  const creditBalance = Math.max(0, Number(credits || 0));
-  const usingCredit = !withinQuota && creditBalance >= unitCost;
-  const remaining = planRemaining + creditBalance;
-
-  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,
-    credits: creditBalance,
-    /** Tells consume() which bucket to draw from — the plan's counter, or a purchased credit. */
-    usingCredit,
-    // Only `block` denies. single_usage/unlimited let the call through — billing catches up after.
-    allowed: withinQuota || usingCredit || policy !== "block",
-    overage_policy: policy,
-    reason: withinQuota || usingCredit ? R.OK : R.QUOTA_EXCEEDED,
-    period,
-    subject_key,
-    metered: true,
-    cost: unitCost,
-  };
-}
-
-export default { resolveEntitlement, resolveEntitlementRow, periodKey, subjectKeyFor };
+/**
+ * Entitlement resolution — @i4e/invest4edu-access-core (P6). Pure: no DB, no Mongoose.
+ *
+ * RBAC says whether a user MAY do a thing. This says whether the FIRM's plan has it unlocked and
+ * whether the allowance is spent. Both must pass (TDD §4.2).
+ *
+ * The one hard rule (§4.3): entitlement **fails open**. An outage in the entitlement path must
+ * never block a feature a customer has paid for — the worst acceptable outcome is that we
+ * occasionally fail to charge. `overage_policy: 'block'` is the only branch that denies, and only
+ * on a definite quota-exceeded answer.
+ */
+import {
+  ENTITLEMENT_REASONS as R,
+  QUOTA_TIMEZONE,
+  PERIOD_GRANULARITIES,
+} from "./entitlement-schema.js";
+
+export { ENTITLEMENT_REASONS } from "./entitlement-schema.js";
+
+/**
+ * Calendar parts of `date` in QUOTA_TIMEZONE.
+ *
+ * Deliberately via Intl rather than date arithmetic: an offset constant would be wrong the moment
+ * anything changes, and a naive `toISOString()` would put an Indian partner's daily reset at 05:30
+ * local — silently costing them the tail of every working day.
+ */
+function partsInZone(date, timeZone = QUOTA_TIMEZONE) {
+  const fmt = new Intl.DateTimeFormat("en-CA", {
+    timeZone, year: "numeric", month: "2-digit", day: "2-digit",
+  });
+  const [{ value: y }, , { value: m }, , { value: d }] = fmt.formatToParts(date);
+  return { y, m, d };
+}
+
+/**
+ * The bucket key an allowance is counted in. The granularity lives IN the key, so a reset needs no
+ * cron: at midnight the key simply changes and the new bucket starts at zero.
+ *
+ * @param {string} granularity   day | month | year | term | lifetime
+ * @param {Object} [opts]
+ * @param {Date}   [opts.now]
+ * @param {string} [opts.subscriptionId]  required for `term`
+ * @param {Date|string} [opts.periodStart] the current term's start — rolls the `term` bucket
+ * @param {string} [opts.timeZone]
+ */
+export function periodKey(granularity, { now = new Date(), subscriptionId = null, periodStart = null, timeZone } = {}) {
+  const g = PERIOD_GRANULARITIES.includes(granularity) ? granularity : "month";
+  if (g === "lifetime") return "lifetime";
+  // A term quota with no subscription would silently collapse every firm into one shared bucket.
+  /**
+   * A term bucket is one BILLING TERM, not the subscription's whole life.
+   *
+   * Keying on the subscription alone looks right and is subtly wrong: a subscription document
+   * survives its own transitions — trial becomes paid, a plan is downgraded then upgraded, a year
+   * renews — all on the same `_id`. So an annual allowance consumed during a trial would come out
+   * of the year the customer then paid for. Including where the term STARTED rolls the bucket
+   * every time the term does.
+   *
+   * Without a start date it degrades to the old lifetime-of-subscription key rather than throwing,
+   * because a missing date must not silently move everyone into one shared bucket.
+   */
+  if (g === "term") {
+    if (!subscriptionId) return "lifetime";
+    if (!periodStart) return `term:${String(subscriptionId)}`;
+    const start = periodStart instanceof Date ? periodStart : new Date(periodStart);
+    if (Number.isNaN(start.getTime())) return `term:${String(subscriptionId)}`;
+    return `term:${String(subscriptionId)}:${start.toISOString().slice(0, 10)}`;
+  }
+
+  const { y, m, d } = partsInZone(now, timeZone);
+  if (g === "year") return y;
+  if (g === "month") return `${y}-${m}`;
+  return `${y}-${m}-${d}`;
+}
+
+/** Whose allowance this is: the firm, or the individual seat. */
+export function subjectKeyFor(quotaScope, { accountId, userId } = {}) {
+  return String((quotaScope === "user" ? userId : accountId) ?? "");
+}
+
+/**
+ * Pick the live entitlement row for a feature: greatest `effective_date <= now`, not superseded.
+ * Rows are versioned rather than edited so a past invoice stays explicable.
+ */
+export function resolveEntitlementRow(rows = [], featureCode, now = new Date()) {
+  return rows
+    .filter((r) => r
+      && r.feature_code === featureCode
+      && new Date(r.effective_date) <= now
+      && (!r.superseded_date || new Date(r.superseded_date) > now))
+    .sort((a, b) => new Date(b.effective_date) - new Date(a.effective_date))[0] || null;
+}
+
+/** Apply a per-firm override on top of the plan row. Concessions live on the subscription. */
+function withOverride(row, overrides = [], featureCode) {
+  /**
+   * Two shapes in the wild, and getting this wrong is silent AND total.
+   *
+   * Everything that WRITES an override — the model, the admin API, the Subscribers view — uses an
+   * object map keyed by feature code. This function only understood an array, so `.find` on the
+   * object threw, `resolveEntitlement` failed open, and the subscriber stopped being metered
+   * altogether. Setting a per-customer allowance therefore disabled that customer's counting —
+   * the opposite of the intent, with no error anywhere.
+   *
+   * Both shapes are accepted now. The map is the canonical one.
+   */
+  const o = Array.isArray(overrides)
+    ? overrides.find((x) => x && x.feature_code === featureCode)
+    : (overrides && typeof overrides === "object" ? overrides[featureCode] : null);
+  if (!o) return row;
+  const merged = { ...row };
+  for (const k of ["unlocked", "quota", "period_granularity", "quota_scope", "overage_policy", "single_usage_price"]) {
+    if (o[k] !== undefined) merged[k] = o[k];
+  }
+  return merged;
+}
+
+/**
+ * Decide entitlement for one feature.
+ *
+ * @param {Object} p
+ * @param {Object|null} p.subscription       account_subscriptions row
+ * @param {Array}  p.entitlementRows         plan_entitlements rows for this plan+cycle
+ * @param {string} p.featureCode
+ * @param {Object} p.feature                 registry row — `is_meterable` decides if quota applies
+ * @param {number} p.used                    already consumed in this period (caller supplies)
+ * @param {number} [p.credits]               à-la-carte units bought and not yet spent
+ * @param {Object} p.identity                { accountId, userId }
+ * @param {boolean} [p.bypass]               D27 admin break-glass
+ * @param {Date}   [p.now]
+ * @returns {Object} { unlocked, quota, used, remaining, allowed, overage_policy, reason,
+ *                     period, subject_key, metered }
+ */
+export function resolveEntitlement({
+  subscription, entitlementRows = [], featureCode, feature = {},
+  used = 0, credits = 0, identity = {}, bypass = false, now = new Date(),
+  /**
+   * Units this ONE action costs. 1 for count-mode (used + 1 ≤ quota is exactly the old
+   * used < quota), the service's credit cost when a credits-mode plan is paying. Threading it
+   * through here is what lets one resolver serve both modes instead of a parallel copy.
+   */
+  cost = 1,
+} = {}) {
+  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 });
+
+  // D27: the break-glass resolves every gate open, including this one.
+  if (bypass) return open(R.ADMIN_BYPASS);
+
+  // `always_available` exists so login/billing/profile survive a blocked subscription — otherwise a
+  // past-due firm could not reach the screen that takes their money.
+  if (feature.always_available) return open(R.OK);
+
+  // No subscription: fail OPEN. Absence of a row is far more likely to be our gap than a customer
+  // genuinely owning nothing, and denying would break every un-migrated firm on day one.
+  if (!subscription) return open(R.NO_SUBSCRIPTION);
+
+  if (subscription.status === "blocked" || subscription.status === "expired") {
+    return { ...base, unlocked: false, allowed: false, reason: R.SUBSCRIPTION_BLOCKED };
+  }
+
+  const row = withOverride(
+    resolveEntitlementRow(entitlementRows, featureCode, now),
+    subscription.entitlement_overrides,
+    featureCode,
+  );
+  // Not named in the plan: OPEN. A plan that forgot to list a feature is a config gap, and P6 must
+  // 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) {
+    // 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";
+  const period = periodKey(granularity, { now, subscriptionId: subscription._id, periodStart: subscription.period_start });
+  const subject_key = subjectKeyFor(row.quota_scope, identity);
+  /**
+   * 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.
+  const withinQuota = Number(used || 0) + unitCost <= Number(row.quota);
+  const policy = row.overage_policy || "block";
+
+  /**
+   * À-la-carte credits — units bought one at a time rather than as part of a plan.
+   *
+   * They top up the plan's allowance rather than replacing it, and are spent ONLY once the plan
+   * allowance is gone. That ordering is the whole point: someone who bought ten extra analyses and
+   * then renews should not find their purchase quietly consumed by a month they had covered
+   * anyway. Plan first, purchase second.
+   *
+   * Credits do not reset with the period — they were paid for, so they last until used.
+   */
+  const creditBalance = Math.max(0, Number(credits || 0));
+  const usingCredit = !withinQuota && creditBalance >= unitCost;
+  const remaining = planRemaining + creditBalance;
+
+  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,
+    credits: creditBalance,
+    /** Tells consume() which bucket to draw from — the plan's counter, or a purchased credit. */
+    usingCredit,
+    // Only `block` denies. single_usage/unlimited let the call through — billing catches up after.
+    allowed: withinQuota || usingCredit || policy !== "block",
+    overage_policy: policy,
+    reason: withinQuota || usingCredit ? R.OK : R.QUOTA_EXCEEDED,
+    period,
+    subject_key,
+    metered: true,
+    cost: unitCost,
+  };
+}
+
+export default { resolveEntitlement, resolveEntitlementRow, periodKey, subjectKeyFor };