@i4e/invest4edu-access-core 0.32.0 → 0.33.0

package/src/entitlement-store.js

@@ -1,610 +1,610 @@
-/**
- * The entitlement STORE — reading a subject's entitlement, and consuming a unit of it.
- *
- * `entitlement.js` next door holds the pure DECISION (given a subscription, rows and a usage
- * count, what is allowed). This holds the part that talks to the database, because every backend
- * that gates a metered feature needs exactly the same two operations and there is nothing
- * app-specific about either.
- *
- * ── Why this exists ──────────────────────────────────────────────────────────────────────────
- * v1 and v2 each grew their own copy of these two functions, and they had ALREADY diverged in
- * shape before a third service needed them: v1's `entitlementFor` derives the subject from `req`
- * and returns carried state for `consume` to reuse, while v2's takes explicit ids and splits
- * `findSubscription` out. Two implementations of one contract is a bug waiting for the day they
- * disagree about whether someone is over quota. A third would have made it certain.
- *
- * So the mechanism lives here and only the DATA differs — which database, which logger. Nothing
- * Mongoose-shaped crosses this boundary: callers inject a `getDb()` returning a raw driver Db, so
- * the package stays model-agnostic and services keep owning their own connections.
- *
- * ── Fail open, always ────────────────────────────────────────────────────────────────────────
- * Entitlement never blocks on infrastructure error. RBAC is the layer that fails closed; this one
- * is commercial, and refusing paid work because our own counter was unreachable turns a small
- * outage into a customer-visible one. Absence is far more likely to be our gap than a customer
- * genuinely owning nothing.
- */
-import { resolveEntitlement, resolveEntitlementRow, periodKey, subjectKeyFor } from "./entitlement.js";
-import { CREDITS_FEATURE_CODE } from "./entitlement-schema.js";
-import { LIVE_STATUSES } from "./subscription-lifecycle.js";
-
-/** Every failure path returns this, so callers never have to branch on "did the lookup work". */
-const OPEN = (reason) => ({
-  allowed: true,
-  unlocked: true,
-  metered: false,
-  quota: null,
-  used: 0,
-  remaining: null,
-  overage_policy: "unlimited",
-  reason,
-});
-
-const noopLogger = { warn() {}, info() {} };
-
-/**
- * Build a store bound to one service's database.
- *
- * @param {Object}   opts
- * @param {Function} opts.getDb      returns a raw MongoDB `Db`, or null/undefined when unavailable
- * @param {Function} [opts.toObjectId] cast a string id the way this service's driver expects.
- *                                    Defaults to passing the value through — services using
- *                                    Mongoose should pass `mongoose.Types.ObjectId`, because a
- *                                    string will not match an ObjectId field and the customer
- *                                    would silently look unsubscribed.
- * @param {Object}   [opts.logger]   anything with `warn`
- */
-export function createEntitlementStore({
-  getDb,
-  toObjectId = (v) => v,
-  logger = noopLogger,
-  /**
-   * THE subscription master switch.
-   *
-   * One place that makes the whole domain inert: no entitlement decides anything, no counter
-   * moves, no subject is auto-provisioned. Per-feature `rollout_mode` still governs which gates
-   * are live once this is on — this is the switch above all of them, for shipping the code long
-   * before the product.
-   *
-   * OFF by default, deliberately. A release must be able to carry every line of this and change
-   * nothing for a single user; a default of "on" would make that depend on remembering to set a
-   * flag, and the failure mode is customers being charged and refused.
-   *
-   * Resolved by the CALLER — env, a config document, whatever each service already uses — so this
-   * package keeps no opinion about where configuration lives.
-   */
-  isEnabled = () => String(process.env.SUBSCRIPTION_ENABLED || "").toLowerCase() === "true",
-} = {}) {
-  if (typeof getDb !== "function") throw new Error("createEntitlementStore requires getDb()");
-
-  /** Resolved per call, never cached, so flipping the switch takes effect without a restart. */
-  const enabled = async () => {
-    try { return (await isEnabled()) === true; } catch { return false; }
-  };
-
-  const oid = (v) => {
-    try { return toObjectId(String(v)); } catch { return v; }
-  };
-
-  /** The live subscription governing this subject, or null. */
-  async function findSubscription({ subjectType, subjectId } = {}) {
-    const db = getDb();
-    if (!db || !subjectType || !subjectId) return null;
-    return db.collection("account_subscriptions").findOne({
-      subject_type: subjectType,
-      subject_id: oid(subjectId),
-      status: { $in: LIVE_STATUSES },
-    });
-  }
-
-  /**
-   * Resolve entitlement for one feature.
-   *
-   * Returns an OPEN result whenever anything is missing — no subscription, no plan row, no
-   * database — for the reason in the header.
-   */
-  async function entitlementFor({
-    subjectType, subjectId, featureCode, feature = {}, identity = {},
-    bypass = false, now = new Date(),
-  } = {}) {
-    try {
-      // Master switch off ⇒ the same OPEN answer as "no subscription": allowed, unshaped,
-      // unmetered. Every caller already handles this, because it is the fail-open path.
-      if (!(await enabled())) return OPEN("subscription_disabled");
-      const db = getDb();
-      if (!db || !subjectType || !subjectId) return OPEN("no_subject");
-
-      const subscription = await findSubscription({ subjectType, subjectId });
-      if (!subscription) return resolveEntitlement({ subscription: null, featureCode, feature, bypass, now });
-
-      /**
-       * Trial terms: while `trialing`, rows with cycle "trial" take precedence over the purchased
-       * cycle's — that is how a trial offers LESS than the paid plan without being a separate
-       * plan. No trial rows ⇒ the paid terms apply during trial, which is the
-       * time-limited-full-plan case.
-       */
-      const cycles = subscription.status === "trialing"
-        ? ["trial", subscription.cycle]
-        : [subscription.cycle];
-      /**
-       * Fetched together: the feature's own rows AND the plan's credit-allowance rows. A plan IS
-       * credits-mode when a SUBSCRIPTION.CREDITS row resolves — the mode is the data, so there is
-       * no flag to drift out of step with it.
-       */
-      const fetched = await db.collection("plan_entitlements").find({
-        plan_code: subscription.plan_code,
-        cycle: { $in: cycles },
-        feature_code: featureCode === CREDITS_FEATURE_CODE
-          ? featureCode
-          : { $in: [featureCode, CREDITS_FEATURE_CODE] },
-      }).toArray();
-      const pick = (code) => {
-        const mine = fetched.filter((r) => r.feature_code === code);
-        const trial = mine.filter((r) => r.cycle === "trial");
-        return subscription.status === "trialing" && trial.length
-          ? trial
-          : mine.filter((r) => r.cycle === subscription.cycle);
-      };
-      const rows = pick(featureCode);
-      const creditRows = featureCode === CREDITS_FEATURE_CODE ? [] : pick(CREDITS_FEATURE_CODE);
-      const creditsMode = creditRows.length > 0 && feature.is_meterable;
-
-      /**
-       * CREDITS MODE — the feature's own row says whether it is INCLUDED (and may override the
-       * cost); the guard runs against the shared credit allowance, priced per use.
-       *
-       *   cost = plan row's credit_cost  >  service's registry credit_cost  >  1
-       *
-       * The per-plan override is your "premium plans give more usage" lever: eCAS can cost 2 on
-       * Discover and 1 on Grow without any per-feature matrix returning through the back door.
-       */
-      /**
-       * A per-feature BUDGET opts out of credits mode.
-       *
-       * `quota` is overloaded, and the two meanings need opposite handling: on VPD it is "12
-       * sessions a year" — a budget that must decrement and refuse at zero — while on stock tips it
-       * is "5 ideas per answer", a ceiling read on every request and never spent. Credits mode
-       * counts only the wallet, so a budget expressed that way silently never moved: Grow showed
-       * 12 VPD sessions that could be used forever.
-       *
-       * So a row with a real number, on a feature that does NOT shape a response, falls through to
-       * count mode and is governed by its own counter. Credits stay for what is priced in credits.
-       * `shapes_response` is the discriminator because it is a property of the FEATURE — whether it
-       * trims an answer or counts a use — not of the plan that sells it.
-       */
-      const budgetRow = creditsMode ? resolveEntitlementRow(rows, featureCode, now) : null;
-      const isOwnBudget = !!budgetRow
-        && budgetRow.unlocked !== false
-        && feature.shapes_response !== true
-        && budgetRow.quota !== null && budgetRow.quota !== undefined && budgetRow.quota !== ""
-        && Number.isFinite(Number(budgetRow.quota));
-
-      if (creditsMode && !isOwnBudget) {
-        const svcRow = resolveEntitlementRow(rows, featureCode, now);
-        // 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) {
-          // 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 {
-            const bal = await db.collection("feature_credits").aggregate([
-              { $match: {
-                subject_type: subjectType,
-                subject_id: oid(subjectId),
-                feature_code: CREDITS_FEATURE_CODE,
-                $expr: { $lt: ["$consumed", "$purchased"] },
-                $or: [{ expires_at: null }, { expires_at: { $exists: false } }, { expires_at: { $gt: now } }],
-              } },
-              { $group: { _id: null, n: { $sum: { $subtract: ["$purchased", "$consumed"] } } } },
-            ]).toArray();
-            packBalance = bal[0]?.n || 0;
-          } catch (e) {
-            logger.warn(`[entitlement] credit-pack balance unreadable: ${e.message}`);
-          }
-
-          const creditRow = creditRows[0];
-          const period = periodKey(creditRow.period_granularity || "month", {
-            now, subscriptionId: subscription._id, periodStart: subscription.period_start,
-          });
-          const subjectKey = subjectKeyFor(creditRow.quota_scope, identity) || "";
-          const usage = await db.collection("subscription_usage").findOne({
-            subscription_id: subscription._id,
-            feature_code: CREDITS_FEATURE_CODE,
-            period,
-            subject_key: subjectKey,
-          });
-
-          const result = await resolveEntitlement({
-            subscription,
-            entitlementRows: creditRows,
-            featureCode: CREDITS_FEATURE_CODE,
-            feature: { is_meterable: true },
-            used: usage?.used || 0,
-            credits: packBalance,
-            identity, bypass, now, cost,
-          });
-
-          const effectiveCreditRow = creditRows[0]
-            ? { ...creditRows[0], quota: result.quota, overage_policy: result.overage_policy || creditRows[0].overage_policy }
-            : null;
-
-          /**
-           * A CEILING survives credits mode.
-           *
-           * `limit` shapes a response — "your list shows 5" — and is read on every request without
-           * ever being spent. A PRICE is what a use costs. They are orthogonal, and the two live on
-           * different fields for exactly that reason.
-           *
-           * Without this line the credits branch returned the wallet's numbers and no `limit` at
-           * all, so a consumer reading `ent.limit` (NFD AI's stock-tips shaper does) saw nothing
-           * and applied no ceiling. A free plan promising five stock ideas silently served every
-           * one of them — the paywall looked configured and was not.
-           *
-           * Same UNSET-vs-0 care as count mode: null means "no ceiling", 0 means "show nothing".
-           */
-          const rawCeiling = svcRow.quota;
-          const ceiling = rawCeiling === null || rawCeiling === undefined || rawCeiling === ""
-            ? null
-            : Number(rawCeiling);
-
-          return {
-            ...result,
-            limit: ceiling !== null && Number.isFinite(ceiling) && ceiling >= 0 ? ceiling : null,
-            mode: "credits",
-            carriedSubjectType: subjectType,
-            carriedSubjectId: subjectId,
-            carriedSubscriptionId: subscription._id,
-            carriedPeriodStart: subscription.period_start || null,
-            carriedIdentity: identity,
-            carriedRow: effectiveCreditRow,
-            // consume() counts against THIS bucket, at THIS price — never recomputed.
-            carriedFeatureCode: CREDITS_FEATURE_CODE,
-            carriedCost: cost,
-          };
-        }
-      }
-
-      /**
-       * À-la-carte credits — units bought singly. Summed across purchases that still have units
-       * left and have not expired. Read alongside usage because the resolver needs both to say
-       * whether the customer may proceed.
-       */
-      let credits = 0;
-      if (feature.is_meterable || feature.single_usage_purchasable) {
-        // Guarded separately: credits are a top-up, and failing to read them must not take the
-        // quota check down with it. Losing a purchased unit is bad; silently ceasing to meter
-        // everyone because one collection is unreachable is worse.
-        try {
-          const bal = await db.collection("feature_credits").aggregate([
-            {
-              $match: {
-                subject_type: subjectType,
-                subject_id: oid(subjectId),
-                feature_code: featureCode,
-                $expr: { $lt: ["$consumed", "$purchased"] },
-                $or: [{ expires_at: null }, { expires_at: { $exists: false } }, { expires_at: { $gt: now } }],
-              },
-            },
-            { $group: { _id: null, n: { $sum: { $subtract: ["$purchased", "$consumed"] } } } },
-          ]).toArray();
-          credits = bal[0]?.n || 0;
-        } catch (e) {
-          logger.warn(`[entitlement] credit balance unreadable for ${featureCode}: ${e.message}`);
-        }
-      }
-
-      // Only read the counter when something could actually be metered — an unmetered feature
-      // should not cost a query on every request.
-      let used = 0;
-      const row = rows[0] || null;
-      if (feature.is_meterable && row) {
-        const period = periodKey(row.period_granularity || "month", { now, subscriptionId: subscription._id, periodStart: subscription.period_start });
-        const subjectKey = subjectKeyFor(row.quota_scope, identity) || "";
-        const usage = await db.collection("subscription_usage").findOne({
-          subscription_id: subscription._id,
-          feature_code: featureCode,
-          period,
-          subject_key: subjectKey,
-        });
-        used = usage?.used || 0;
-      }
-
-      const result = await resolveEntitlement({
-        subscription, entitlementRows: rows, featureCode, feature, used, credits, identity, bypass, now,
-      });
-
-      /**
-       * Carry what consume() needs, so it cannot recompute the period key and count against a
-       * different bucket than the one that was just checked.
-       *
-       * The carried row takes its ceiling from the RESOLVED result, not from the raw plan row —
-       * because a per-subject override changes the decision without changing the row it came
-       * from. Carrying the raw row meant consume guarded on the plan's quota while the check had
-       * already passed on the overridden one: a subject granted 5 was refused at 2, and it
-       * surfaced as a counter that had simply stopped moving.
-       */
-      const effectiveRow = row
-        ? { ...row, quota: result.quota, overage_policy: result.overage_policy || row.overage_policy }
-        : null;
-
-      return {
-        ...result,
-        carriedSubjectType: subjectType,
-        carriedSubjectId: subjectId,
-        carriedSubscriptionId: subscription._id,
-        carriedPeriodStart: subscription.period_start || null,
-        carriedIdentity: identity,
-        carriedRow: effectiveRow,
-      };
-    } catch (e) {
-      logger.warn(`[entitlement] resolve failed for ${featureCode}, allowing through: ${e.message}`);
-      return OPEN("resolve_error");
-    }
-  }
-
-  /**
-   * Per-service breakdown when a shared bucket pays — "where did my 500 credits go".
-   *
-   * Fire-and-forget and unguarded: it is reporting, not enforcement, and a failed attribution
-   * row must never undo a consumption the guard already allowed. Only written when the bucket
-   * differs from the feature (credits mode) — in count mode the guarded row IS the attribution.
-   */
-  function recordAttribution({ db, entitlement, featureCode, bucketCode, subId, ident, n, units, now }) {
-    if (!db || bucketCode === featureCode) return;
-    try {
-      const row = entitlement?.carriedRow || {};
-      const period = periodKey(row.period_granularity || "month", {
-        now, subscriptionId: subId, periodStart: entitlement?.carriedPeriodStart,
-      });
-      const subjectKey = subjectKeyFor(row.quota_scope, ident) || "";
-      db.collection("subscription_usage").updateOne(
-        { subscription_id: subId, feature_code: featureCode, period, subject_key: subjectKey },
-        { $inc: { used: n, credits_spent: units }, $setOnInsert: { attribution: true } },
-        { upsert: true },
-      ).catch((e) => logger.warn(`[entitlement] attribution write failed: ${e.message}`));
-    } catch (e) {
-      logger.warn(`[entitlement] attribution skipped: ${e.message}`);
-    }
-  }
-
-  /**
-   * Consume one unit — race-free by construction.
-   *
-   * The `used < quota` test lives inside the FILTER, so Mongo decides atomically whether the
-   * increment may happen; matchedCount 0 means the ceiling was already reached. A read-then-write
-   * would let two concurrent requests both pass a 5-of-5 check and land a 6th.
-   *
-   * Only `block` enforces the ceiling — under `warn` the count still rises, and that record is the
-   * evidence for whether a quota is right before anyone is ever refused.
-   *
-   * Accepts either the result of `entitlementFor` (preferred — it carries the exact bucket that
-   * was checked) or the explicit pieces, so both existing call shapes keep working.
-   */
-  async function consume({
-    entitlement, featureCode, n = 1, now = new Date(),
-    subscriptionId, row, identity, periodStart,
-  } = {}) {
-    try {
-      const db = getDb();
-      const subId = subscriptionId || entitlement?.carriedSubscriptionId;
-      const useRow = row || entitlement?.carriedRow;
-      const ident = identity || entitlement?.carriedIdentity || {};
-      // An unmetered feature has nothing to count; saying so is not a failure.
-      /**
-       * Checked before anything else, including the not-metered short-circuits: "the domain is
-       * off" is a truer answer than "this feature is not metered", and it has to hold even when
-       * the caller passed nothing useful. Returning `consumed: false` rather than throwing keeps
-       * callers on the path they already have for "the counter did not move".
-       */
-      if (!(await enabled())) return { consumed: false, reason: "subscription_disabled" };
-
-      if (entitlement && !entitlement.metered) return { consumed: false, reason: "not_metered" };
-      if (!db || !subId || !useRow) return { consumed: false, reason: "not_metered" };
-
-      /**
-       * Credits mode: the BUCKET is the plan's credit allowance, and one action costs `cost`
-       * units. Both were decided by the resolve that authorised this call — recomputing either
-       * here could draw from a bucket nobody checked, at a price nobody quoted.
-       */
-      const bucketCode = entitlement?.carriedFeatureCode || featureCode;
-      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.
-      const start = periodStart !== undefined ? periodStart : entitlement?.carriedPeriodStart;
-      /**
-       * Spending a purchased credit instead of the plan's allowance.
-       *
-       * `usingCredit` was decided by the same resolve that authorised this call, so the two cannot
-       * disagree about which bucket was checked and which is being drawn down. The guard
-       * `consumed < purchased` sits INSIDE the filter for the same reason the quota test does:
-       * Mongo decides atomically, so two concurrent calls cannot both spend the last unit.
-       *
-       * Oldest purchase first — a credit with an expiry should be used before one without.
-       */
-      if (entitlement?.usingCredit) {
-        const hit = await db.collection("feature_credits").findOneAndUpdate(
-          {
-            subject_type: entitlement.carriedSubjectType,
-            subject_id: oid(entitlement.carriedSubjectId),
-            feature_code: bucketCode,
-            /**
-             * The WHOLE cost must fit in one pack row, decided atomically. A 2-credit action
-             * against a pack with 1 left is refused rather than split across purchases —
-             * splitting would need a transaction across rows, and the boundary case (the last
-             * unit of one pack) is not worth that machinery. The refusal falls through to the
-             * plan counter, which answers honestly.
-             */
-            $expr: { $lte: [{ $add: ["$consumed", units] }, "$purchased"] },
-            $or: [{ expires_at: null }, { expires_at: { $exists: false } }, { expires_at: { $gt: now } }],
-          },
-          { $inc: { consumed: units } },
-          { sort: { expires_at: 1, createdAt: 1 } },
-        );
-        if (hit) {
-          recordAttribution({ db, entitlement, featureCode, bucketCode, subId, ident, n, units, now });
-          return { consumed: true, fromCredit: true };
-        }
-        // No credit left after all — fall through and let the plan counter answer, which may well
-        // refuse. Better than silently succeeding on a balance that just went to zero.
-      }
-
-      const period = periodKey(useRow.period_granularity || "month", { now, subscriptionId: subId, periodStart: start });
-      const subjectKey = subjectKeyFor(useRow.quota_scope, ident) || "";
-      const filter = {
-        subscription_id: subId,
-        feature_code: bucketCode,
-        period,
-        subject_key: subjectKey,
-      };
-      const policy = useRow.overage_policy || "block";
-      const capped = policy === "block" && useRow.quota != null;
-
-      // Unguarded (warn / unlimited): a plain upsert is right — the count rises either way, and
-      // that record is the evidence for whether a quota is set correctly before anyone is refused.
-      if (!capped) {
-        await db.collection("subscription_usage").updateOne(
-          filter, { $inc: { used: units }, $setOnInsert: { ...filter } }, { upsert: true },
-        );
-        recordAttribution({ db, entitlement, featureCode, bucketCode, subId, ident, n, units, now });
-        return { consumed: true };
-      }
-
-      // Capped: try the GUARDED update first, without upsert. Cost-aware — the whole cost must
-      // fit ($lte quota - units is exactly $lt quota when units is 1), and a balance never goes
-      // negative on an in-flight action.
-      const guarded = { ...filter, used: { $lte: Number(useRow.quota) - units } };
-      const hit = await db.collection("subscription_usage").updateOne(guarded, { $inc: { used: units } });
-      if (hit.matchedCount > 0) {
-        recordAttribution({ db, entitlement, featureCode, bucketCode, subId, ident, n, units, now });
-        return { consumed: true };
-      }
-
-      // No match means either "no row yet" (first use this period) or "quota reached". Distinguish
-      // by INSERTING — the unique index makes that safe under concurrency: exactly one racer wins
-      // and the loser's duplicate-key means the row now exists, i.e. the quota case.
-      //
-      // Doing this as an upsert on the guarded filter instead would rely on a duplicate-key
-      // EXCEPTION to mean "quota exceeded" — correct by accident, and unreadable.
-      try {
-        // First use this period must ALSO fit — an allowance smaller than one action's cost is
-        // refused on action one, not discovered at minus-something.
-        if (Number(useRow.quota) - units < 0) return { consumed: false, reason: "quota_exceeded" };
-        await db.collection("subscription_usage").insertOne({ ...filter, used: units, createdAt: new Date() });
-        recordAttribution({ db, entitlement, featureCode, bucketCode, subId, ident, n, units, now });
-        return { consumed: true };
-      } catch (e) {
-        if (e?.code === 11000) return { consumed: false, reason: "quota_exceeded" };
-        throw e;
-      }
-    } catch (e) {
-      logger.warn(`[entitlement] consume failed for ${featureCode}: ${e.message}`);
-      // Fail open on infrastructure error: never refuse a request because our counter misbehaved.
-      return { consumed: false, reason: "error" };
-    }
-  }
-
-  /**
-   * Give a subject the default plan, if there is one and they have none.
-   *
-   * A distributor who has never bought anything currently resolves to "no subscription", which
-   * fails OPEN — so today every distributor silently has unlimited everything. A default plan is
-   * how that becomes deliberate: a real package with real limits, assigned automatically, so the
-   * system's answer to "what may this person do" stops being "we never decided".
-   *
-   * ── Idempotent, and safe to call from anywhere ───────────────────────────────────────────────
-   * Returns the existing subscription untouched if one is live. That matters because the natural
-   * call site is distributor creation, and distributors get created down several paths (self
-   * onboarding, admin, draft approval, bulk import) — a provisioner that could double-assign would
-   * have to be wired carefully into exactly one of them, which is how coverage gaps happen. This
-   * one can be called from all of them, or twice, or after the fact.
-   *
-   * ── Never fatal ──────────────────────────────────────────────────────────────────────────────
-   * Returns null on any failure rather than throwing. Callers create distributors; a subscription
-   * that could not be provisioned must never be the reason a distributor does not exist. The gap
-   * is recoverable by calling this again — a failed creation is not.
-   *
-   * @param {Object} p
-   * @param {string} p.subjectType   "distributor" | "client"
-   * @param {string} p.subjectId
-   * @param {string} [p.accountId]
-   * @param {Date}   [p.now]
-   * @returns {Promise<Object|null>} the subscription (existing or new), or null
-   */
-  async function provisionDefault({ subjectType, subjectId, accountId = null, now = new Date() } = {}) {
-    try {
-      // No auto-provisioning while the domain is off, whatever the catalogue says. This is the
-      // one that would otherwise write rows into production on the first distributor created.
-      if (!(await enabled())) return null;
-
-      const db = getDb();
-      if (!db || !subjectType || !subjectId) return null;
-
-      const existing = await findSubscription({ subjectType, subjectId });
-      if (existing) return existing;
-
-      // The default plan is a property of the CATALOGUE, not of this code — so which package new
-      // distributors get, and for how long, is changed by editing a plan rather than deploying.
-      const plan = await db.collection("plan_catalog").findOne({
-        default_for: subjectType,
-        status: "active",
-      });
-      if (!plan) return null;
-
-      const days = Number(plan.default_duration_days) || 0;
-      const start = new Date(now);
-      const end = new Date(now);
-      if (days > 0) end.setDate(end.getDate() + days);
-      // No duration means an open-ended default tier; period_end null reads as "does not lapse".
-      const periodEnd = days > 0 ? end : null;
-
-      /**
-       * Status is `active`, not `trialing`.
-       *
-       * This is a real package on real terms, not a taste of a bigger one — and `trialing` would
-       * make trial-cycle entitlement rows take precedence, quietly applying terms nobody wrote for
-       * this plan. The trial mechanism stays available for plans that actually want it.
-       */
-      const doc = {
-        account_id: accountId ? oid(accountId) : null,
-        subject_type: subjectType,
-        subject_id: oid(subjectId),
-        plan_code: plan.plan_code,
-        cycle: plan.default_cycle || "monthly",
-        status: "active",
-        period_start: start,
-        period_end: periodEnd,
-        provisioned_default: true,   // so a report can tell "given" from "bought"
-        createdAt: new Date(),
-      };
-
-      try {
-        await db.collection("account_subscriptions").insertOne(doc);
-      } catch (e) {
-        // Two creation paths racing on the same subject. The partial unique index on a live
-        // subscription is what makes this safe: one wins, and the loser reads the winner's row
-        // rather than creating a duplicate.
-        if (e?.code === 11000) return findSubscription({ subjectType, subjectId });
-        throw e;
-      }
-      return doc;
-    } catch (e) {
-      logger.warn(`[entitlement] default provisioning failed for ${subjectType} ${subjectId}: ${e.message}`);
-      return null;
-    }
-  }
-
-  return { findSubscription, entitlementFor, consume, provisionDefault };
-}
-
-export default { createEntitlementStore };
+/**
+ * The entitlement STORE — reading a subject's entitlement, and consuming a unit of it.
+ *
+ * `entitlement.js` next door holds the pure DECISION (given a subscription, rows and a usage
+ * count, what is allowed). This holds the part that talks to the database, because every backend
+ * that gates a metered feature needs exactly the same two operations and there is nothing
+ * app-specific about either.
+ *
+ * ── Why this exists ──────────────────────────────────────────────────────────────────────────
+ * v1 and v2 each grew their own copy of these two functions, and they had ALREADY diverged in
+ * shape before a third service needed them: v1's `entitlementFor` derives the subject from `req`
+ * and returns carried state for `consume` to reuse, while v2's takes explicit ids and splits
+ * `findSubscription` out. Two implementations of one contract is a bug waiting for the day they
+ * disagree about whether someone is over quota. A third would have made it certain.
+ *
+ * So the mechanism lives here and only the DATA differs — which database, which logger. Nothing
+ * Mongoose-shaped crosses this boundary: callers inject a `getDb()` returning a raw driver Db, so
+ * the package stays model-agnostic and services keep owning their own connections.
+ *
+ * ── Fail open, always ────────────────────────────────────────────────────────────────────────
+ * Entitlement never blocks on infrastructure error. RBAC is the layer that fails closed; this one
+ * is commercial, and refusing paid work because our own counter was unreachable turns a small
+ * outage into a customer-visible one. Absence is far more likely to be our gap than a customer
+ * genuinely owning nothing.
+ */
+import { resolveEntitlement, resolveEntitlementRow, periodKey, subjectKeyFor } from "./entitlement.js";
+import { CREDITS_FEATURE_CODE } from "./entitlement-schema.js";
+import { LIVE_STATUSES } from "./subscription-lifecycle.js";
+
+/** Every failure path returns this, so callers never have to branch on "did the lookup work". */
+const OPEN = (reason) => ({
+  allowed: true,
+  unlocked: true,
+  metered: false,
+  quota: null,
+  used: 0,
+  remaining: null,
+  overage_policy: "unlimited",
+  reason,
+});
+
+const noopLogger = { warn() {}, info() {} };
+
+/**
+ * Build a store bound to one service's database.
+ *
+ * @param {Object}   opts
+ * @param {Function} opts.getDb      returns a raw MongoDB `Db`, or null/undefined when unavailable
+ * @param {Function} [opts.toObjectId] cast a string id the way this service's driver expects.
+ *                                    Defaults to passing the value through — services using
+ *                                    Mongoose should pass `mongoose.Types.ObjectId`, because a
+ *                                    string will not match an ObjectId field and the customer
+ *                                    would silently look unsubscribed.
+ * @param {Object}   [opts.logger]   anything with `warn`
+ */
+export function createEntitlementStore({
+  getDb,
+  toObjectId = (v) => v,
+  logger = noopLogger,
+  /**
+   * THE subscription master switch.
+   *
+   * One place that makes the whole domain inert: no entitlement decides anything, no counter
+   * moves, no subject is auto-provisioned. Per-feature `rollout_mode` still governs which gates
+   * are live once this is on — this is the switch above all of them, for shipping the code long
+   * before the product.
+   *
+   * OFF by default, deliberately. A release must be able to carry every line of this and change
+   * nothing for a single user; a default of "on" would make that depend on remembering to set a
+   * flag, and the failure mode is customers being charged and refused.
+   *
+   * Resolved by the CALLER — env, a config document, whatever each service already uses — so this
+   * package keeps no opinion about where configuration lives.
+   */
+  isEnabled = () => String(process.env.SUBSCRIPTION_ENABLED || "").toLowerCase() === "true",
+} = {}) {
+  if (typeof getDb !== "function") throw new Error("createEntitlementStore requires getDb()");
+
+  /** Resolved per call, never cached, so flipping the switch takes effect without a restart. */
+  const enabled = async () => {
+    try { return (await isEnabled()) === true; } catch { return false; }
+  };
+
+  const oid = (v) => {
+    try { return toObjectId(String(v)); } catch { return v; }
+  };
+
+  /** The live subscription governing this subject, or null. */
+  async function findSubscription({ subjectType, subjectId } = {}) {
+    const db = getDb();
+    if (!db || !subjectType || !subjectId) return null;
+    return db.collection("account_subscriptions").findOne({
+      subject_type: subjectType,
+      subject_id: oid(subjectId),
+      status: { $in: LIVE_STATUSES },
+    });
+  }
+
+  /**
+   * Resolve entitlement for one feature.
+   *
+   * Returns an OPEN result whenever anything is missing — no subscription, no plan row, no
+   * database — for the reason in the header.
+   */
+  async function entitlementFor({
+    subjectType, subjectId, featureCode, feature = {}, identity = {},
+    bypass = false, now = new Date(),
+  } = {}) {
+    try {
+      // Master switch off ⇒ the same OPEN answer as "no subscription": allowed, unshaped,
+      // unmetered. Every caller already handles this, because it is the fail-open path.
+      if (!(await enabled())) return OPEN("subscription_disabled");
+      const db = getDb();
+      if (!db || !subjectType || !subjectId) return OPEN("no_subject");
+
+      const subscription = await findSubscription({ subjectType, subjectId });
+      if (!subscription) return resolveEntitlement({ subscription: null, featureCode, feature, bypass, now });
+
+      /**
+       * Trial terms: while `trialing`, rows with cycle "trial" take precedence over the purchased
+       * cycle's — that is how a trial offers LESS than the paid plan without being a separate
+       * plan. No trial rows ⇒ the paid terms apply during trial, which is the
+       * time-limited-full-plan case.
+       */
+      const cycles = subscription.status === "trialing"
+        ? ["trial", subscription.cycle]
+        : [subscription.cycle];
+      /**
+       * Fetched together: the feature's own rows AND the plan's credit-allowance rows. A plan IS
+       * credits-mode when a SUBSCRIPTION.CREDITS row resolves — the mode is the data, so there is
+       * no flag to drift out of step with it.
+       */
+      const fetched = await db.collection("plan_entitlements").find({
+        plan_code: subscription.plan_code,
+        cycle: { $in: cycles },
+        feature_code: featureCode === CREDITS_FEATURE_CODE
+          ? featureCode
+          : { $in: [featureCode, CREDITS_FEATURE_CODE] },
+      }).toArray();
+      const pick = (code) => {
+        const mine = fetched.filter((r) => r.feature_code === code);
+        const trial = mine.filter((r) => r.cycle === "trial");
+        return subscription.status === "trialing" && trial.length
+          ? trial
+          : mine.filter((r) => r.cycle === subscription.cycle);
+      };
+      const rows = pick(featureCode);
+      const creditRows = featureCode === CREDITS_FEATURE_CODE ? [] : pick(CREDITS_FEATURE_CODE);
+      const creditsMode = creditRows.length > 0 && feature.is_meterable;
+
+      /**
+       * CREDITS MODE — the feature's own row says whether it is INCLUDED (and may override the
+       * cost); the guard runs against the shared credit allowance, priced per use.
+       *
+       *   cost = plan row's credit_cost  >  service's registry credit_cost  >  1
+       *
+       * The per-plan override is your "premium plans give more usage" lever: eCAS can cost 2 on
+       * Discover and 1 on Grow without any per-feature matrix returning through the back door.
+       */
+      /**
+       * A per-feature BUDGET opts out of credits mode.
+       *
+       * `quota` is overloaded, and the two meanings need opposite handling: on VPD it is "12
+       * sessions a year" — a budget that must decrement and refuse at zero — while on stock tips it
+       * is "5 ideas per answer", a ceiling read on every request and never spent. Credits mode
+       * counts only the wallet, so a budget expressed that way silently never moved: Grow showed
+       * 12 VPD sessions that could be used forever.
+       *
+       * So a row with a real number, on a feature that does NOT shape a response, falls through to
+       * count mode and is governed by its own counter. Credits stay for what is priced in credits.
+       * `shapes_response` is the discriminator because it is a property of the FEATURE — whether it
+       * trims an answer or counts a use — not of the plan that sells it.
+       */
+      const budgetRow = creditsMode ? resolveEntitlementRow(rows, featureCode, now) : null;
+      const isOwnBudget = !!budgetRow
+        && budgetRow.unlocked !== false
+        && feature.shapes_response !== true
+        && budgetRow.quota !== null && budgetRow.quota !== undefined && budgetRow.quota !== ""
+        && Number.isFinite(Number(budgetRow.quota));
+
+      if (creditsMode && !isOwnBudget) {
+        const svcRow = resolveEntitlementRow(rows, featureCode, now);
+        // 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) {
+          // 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 {
+            const bal = await db.collection("feature_credits").aggregate([
+              { $match: {
+                subject_type: subjectType,
+                subject_id: oid(subjectId),
+                feature_code: CREDITS_FEATURE_CODE,
+                $expr: { $lt: ["$consumed", "$purchased"] },
+                $or: [{ expires_at: null }, { expires_at: { $exists: false } }, { expires_at: { $gt: now } }],
+              } },
+              { $group: { _id: null, n: { $sum: { $subtract: ["$purchased", "$consumed"] } } } },
+            ]).toArray();
+            packBalance = bal[0]?.n || 0;
+          } catch (e) {
+            logger.warn(`[entitlement] credit-pack balance unreadable: ${e.message}`);
+          }
+
+          const creditRow = creditRows[0];
+          const period = periodKey(creditRow.period_granularity || "month", {
+            now, subscriptionId: subscription._id, periodStart: subscription.period_start,
+          });
+          const subjectKey = subjectKeyFor(creditRow.quota_scope, identity) || "";
+          const usage = await db.collection("subscription_usage").findOne({
+            subscription_id: subscription._id,
+            feature_code: CREDITS_FEATURE_CODE,
+            period,
+            subject_key: subjectKey,
+          });
+
+          const result = await resolveEntitlement({
+            subscription,
+            entitlementRows: creditRows,
+            featureCode: CREDITS_FEATURE_CODE,
+            feature: { is_meterable: true },
+            used: usage?.used || 0,
+            credits: packBalance,
+            identity, bypass, now, cost,
+          });
+
+          const effectiveCreditRow = creditRows[0]
+            ? { ...creditRows[0], quota: result.quota, overage_policy: result.overage_policy || creditRows[0].overage_policy }
+            : null;
+
+          /**
+           * A CEILING survives credits mode.
+           *
+           * `limit` shapes a response — "your list shows 5" — and is read on every request without
+           * ever being spent. A PRICE is what a use costs. They are orthogonal, and the two live on
+           * different fields for exactly that reason.
+           *
+           * Without this line the credits branch returned the wallet's numbers and no `limit` at
+           * all, so a consumer reading `ent.limit` (NFD AI's stock-tips shaper does) saw nothing
+           * and applied no ceiling. A free plan promising five stock ideas silently served every
+           * one of them — the paywall looked configured and was not.
+           *
+           * Same UNSET-vs-0 care as count mode: null means "no ceiling", 0 means "show nothing".
+           */
+          const rawCeiling = svcRow.quota;
+          const ceiling = rawCeiling === null || rawCeiling === undefined || rawCeiling === ""
+            ? null
+            : Number(rawCeiling);
+
+          return {
+            ...result,
+            limit: ceiling !== null && Number.isFinite(ceiling) && ceiling >= 0 ? ceiling : null,
+            mode: "credits",
+            carriedSubjectType: subjectType,
+            carriedSubjectId: subjectId,
+            carriedSubscriptionId: subscription._id,
+            carriedPeriodStart: subscription.period_start || null,
+            carriedIdentity: identity,
+            carriedRow: effectiveCreditRow,
+            // consume() counts against THIS bucket, at THIS price — never recomputed.
+            carriedFeatureCode: CREDITS_FEATURE_CODE,
+            carriedCost: cost,
+          };
+        }
+      }
+
+      /**
+       * À-la-carte credits — units bought singly. Summed across purchases that still have units
+       * left and have not expired. Read alongside usage because the resolver needs both to say
+       * whether the customer may proceed.
+       */
+      let credits = 0;
+      if (feature.is_meterable || feature.single_usage_purchasable) {
+        // Guarded separately: credits are a top-up, and failing to read them must not take the
+        // quota check down with it. Losing a purchased unit is bad; silently ceasing to meter
+        // everyone because one collection is unreachable is worse.
+        try {
+          const bal = await db.collection("feature_credits").aggregate([
+            {
+              $match: {
+                subject_type: subjectType,
+                subject_id: oid(subjectId),
+                feature_code: featureCode,
+                $expr: { $lt: ["$consumed", "$purchased"] },
+                $or: [{ expires_at: null }, { expires_at: { $exists: false } }, { expires_at: { $gt: now } }],
+              },
+            },
+            { $group: { _id: null, n: { $sum: { $subtract: ["$purchased", "$consumed"] } } } },
+          ]).toArray();
+          credits = bal[0]?.n || 0;
+        } catch (e) {
+          logger.warn(`[entitlement] credit balance unreadable for ${featureCode}: ${e.message}`);
+        }
+      }
+
+      // Only read the counter when something could actually be metered — an unmetered feature
+      // should not cost a query on every request.
+      let used = 0;
+      const row = rows[0] || null;
+      if (feature.is_meterable && row) {
+        const period = periodKey(row.period_granularity || "month", { now, subscriptionId: subscription._id, periodStart: subscription.period_start });
+        const subjectKey = subjectKeyFor(row.quota_scope, identity) || "";
+        const usage = await db.collection("subscription_usage").findOne({
+          subscription_id: subscription._id,
+          feature_code: featureCode,
+          period,
+          subject_key: subjectKey,
+        });
+        used = usage?.used || 0;
+      }
+
+      const result = await resolveEntitlement({
+        subscription, entitlementRows: rows, featureCode, feature, used, credits, identity, bypass, now,
+      });
+
+      /**
+       * Carry what consume() needs, so it cannot recompute the period key and count against a
+       * different bucket than the one that was just checked.
+       *
+       * The carried row takes its ceiling from the RESOLVED result, not from the raw plan row —
+       * because a per-subject override changes the decision without changing the row it came
+       * from. Carrying the raw row meant consume guarded on the plan's quota while the check had
+       * already passed on the overridden one: a subject granted 5 was refused at 2, and it
+       * surfaced as a counter that had simply stopped moving.
+       */
+      const effectiveRow = row
+        ? { ...row, quota: result.quota, overage_policy: result.overage_policy || row.overage_policy }
+        : null;
+
+      return {
+        ...result,
+        carriedSubjectType: subjectType,
+        carriedSubjectId: subjectId,
+        carriedSubscriptionId: subscription._id,
+        carriedPeriodStart: subscription.period_start || null,
+        carriedIdentity: identity,
+        carriedRow: effectiveRow,
+      };
+    } catch (e) {
+      logger.warn(`[entitlement] resolve failed for ${featureCode}, allowing through: ${e.message}`);
+      return OPEN("resolve_error");
+    }
+  }
+
+  /**
+   * Per-service breakdown when a shared bucket pays — "where did my 500 credits go".
+   *
+   * Fire-and-forget and unguarded: it is reporting, not enforcement, and a failed attribution
+   * row must never undo a consumption the guard already allowed. Only written when the bucket
+   * differs from the feature (credits mode) — in count mode the guarded row IS the attribution.
+   */
+  function recordAttribution({ db, entitlement, featureCode, bucketCode, subId, ident, n, units, now }) {
+    if (!db || bucketCode === featureCode) return;
+    try {
+      const row = entitlement?.carriedRow || {};
+      const period = periodKey(row.period_granularity || "month", {
+        now, subscriptionId: subId, periodStart: entitlement?.carriedPeriodStart,
+      });
+      const subjectKey = subjectKeyFor(row.quota_scope, ident) || "";
+      db.collection("subscription_usage").updateOne(
+        { subscription_id: subId, feature_code: featureCode, period, subject_key: subjectKey },
+        { $inc: { used: n, credits_spent: units }, $setOnInsert: { attribution: true } },
+        { upsert: true },
+      ).catch((e) => logger.warn(`[entitlement] attribution write failed: ${e.message}`));
+    } catch (e) {
+      logger.warn(`[entitlement] attribution skipped: ${e.message}`);
+    }
+  }
+
+  /**
+   * Consume one unit — race-free by construction.
+   *
+   * The `used < quota` test lives inside the FILTER, so Mongo decides atomically whether the
+   * increment may happen; matchedCount 0 means the ceiling was already reached. A read-then-write
+   * would let two concurrent requests both pass a 5-of-5 check and land a 6th.
+   *
+   * Only `block` enforces the ceiling — under `warn` the count still rises, and that record is the
+   * evidence for whether a quota is right before anyone is ever refused.
+   *
+   * Accepts either the result of `entitlementFor` (preferred — it carries the exact bucket that
+   * was checked) or the explicit pieces, so both existing call shapes keep working.
+   */
+  async function consume({
+    entitlement, featureCode, n = 1, now = new Date(),
+    subscriptionId, row, identity, periodStart,
+  } = {}) {
+    try {
+      const db = getDb();
+      const subId = subscriptionId || entitlement?.carriedSubscriptionId;
+      const useRow = row || entitlement?.carriedRow;
+      const ident = identity || entitlement?.carriedIdentity || {};
+      // An unmetered feature has nothing to count; saying so is not a failure.
+      /**
+       * Checked before anything else, including the not-metered short-circuits: "the domain is
+       * off" is a truer answer than "this feature is not metered", and it has to hold even when
+       * the caller passed nothing useful. Returning `consumed: false` rather than throwing keeps
+       * callers on the path they already have for "the counter did not move".
+       */
+      if (!(await enabled())) return { consumed: false, reason: "subscription_disabled" };
+
+      if (entitlement && !entitlement.metered) return { consumed: false, reason: "not_metered" };
+      if (!db || !subId || !useRow) return { consumed: false, reason: "not_metered" };
+
+      /**
+       * Credits mode: the BUCKET is the plan's credit allowance, and one action costs `cost`
+       * units. Both were decided by the resolve that authorised this call — recomputing either
+       * here could draw from a bucket nobody checked, at a price nobody quoted.
+       */
+      const bucketCode = entitlement?.carriedFeatureCode || featureCode;
+      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.
+      const start = periodStart !== undefined ? periodStart : entitlement?.carriedPeriodStart;
+      /**
+       * Spending a purchased credit instead of the plan's allowance.
+       *
+       * `usingCredit` was decided by the same resolve that authorised this call, so the two cannot
+       * disagree about which bucket was checked and which is being drawn down. The guard
+       * `consumed < purchased` sits INSIDE the filter for the same reason the quota test does:
+       * Mongo decides atomically, so two concurrent calls cannot both spend the last unit.
+       *
+       * Oldest purchase first — a credit with an expiry should be used before one without.
+       */
+      if (entitlement?.usingCredit) {
+        const hit = await db.collection("feature_credits").findOneAndUpdate(
+          {
+            subject_type: entitlement.carriedSubjectType,
+            subject_id: oid(entitlement.carriedSubjectId),
+            feature_code: bucketCode,
+            /**
+             * The WHOLE cost must fit in one pack row, decided atomically. A 2-credit action
+             * against a pack with 1 left is refused rather than split across purchases —
+             * splitting would need a transaction across rows, and the boundary case (the last
+             * unit of one pack) is not worth that machinery. The refusal falls through to the
+             * plan counter, which answers honestly.
+             */
+            $expr: { $lte: [{ $add: ["$consumed", units] }, "$purchased"] },
+            $or: [{ expires_at: null }, { expires_at: { $exists: false } }, { expires_at: { $gt: now } }],
+          },
+          { $inc: { consumed: units } },
+          { sort: { expires_at: 1, createdAt: 1 } },
+        );
+        if (hit) {
+          recordAttribution({ db, entitlement, featureCode, bucketCode, subId, ident, n, units, now });
+          return { consumed: true, fromCredit: true };
+        }
+        // No credit left after all — fall through and let the plan counter answer, which may well
+        // refuse. Better than silently succeeding on a balance that just went to zero.
+      }
+
+      const period = periodKey(useRow.period_granularity || "month", { now, subscriptionId: subId, periodStart: start });
+      const subjectKey = subjectKeyFor(useRow.quota_scope, ident) || "";
+      const filter = {
+        subscription_id: subId,
+        feature_code: bucketCode,
+        period,
+        subject_key: subjectKey,
+      };
+      const policy = useRow.overage_policy || "block";
+      const capped = policy === "block" && useRow.quota != null;
+
+      // Unguarded (warn / unlimited): a plain upsert is right — the count rises either way, and
+      // that record is the evidence for whether a quota is set correctly before anyone is refused.
+      if (!capped) {
+        await db.collection("subscription_usage").updateOne(
+          filter, { $inc: { used: units }, $setOnInsert: { ...filter } }, { upsert: true },
+        );
+        recordAttribution({ db, entitlement, featureCode, bucketCode, subId, ident, n, units, now });
+        return { consumed: true };
+      }
+
+      // Capped: try the GUARDED update first, without upsert. Cost-aware — the whole cost must
+      // fit ($lte quota - units is exactly $lt quota when units is 1), and a balance never goes
+      // negative on an in-flight action.
+      const guarded = { ...filter, used: { $lte: Number(useRow.quota) - units } };
+      const hit = await db.collection("subscription_usage").updateOne(guarded, { $inc: { used: units } });
+      if (hit.matchedCount > 0) {
+        recordAttribution({ db, entitlement, featureCode, bucketCode, subId, ident, n, units, now });
+        return { consumed: true };
+      }
+
+      // No match means either "no row yet" (first use this period) or "quota reached". Distinguish
+      // by INSERTING — the unique index makes that safe under concurrency: exactly one racer wins
+      // and the loser's duplicate-key means the row now exists, i.e. the quota case.
+      //
+      // Doing this as an upsert on the guarded filter instead would rely on a duplicate-key
+      // EXCEPTION to mean "quota exceeded" — correct by accident, and unreadable.
+      try {
+        // First use this period must ALSO fit — an allowance smaller than one action's cost is
+        // refused on action one, not discovered at minus-something.
+        if (Number(useRow.quota) - units < 0) return { consumed: false, reason: "quota_exceeded" };
+        await db.collection("subscription_usage").insertOne({ ...filter, used: units, createdAt: new Date() });
+        recordAttribution({ db, entitlement, featureCode, bucketCode, subId, ident, n, units, now });
+        return { consumed: true };
+      } catch (e) {
+        if (e?.code === 11000) return { consumed: false, reason: "quota_exceeded" };
+        throw e;
+      }
+    } catch (e) {
+      logger.warn(`[entitlement] consume failed for ${featureCode}: ${e.message}`);
+      // Fail open on infrastructure error: never refuse a request because our counter misbehaved.
+      return { consumed: false, reason: "error" };
+    }
+  }
+
+  /**
+   * Give a subject the default plan, if there is one and they have none.
+   *
+   * A distributor who has never bought anything currently resolves to "no subscription", which
+   * fails OPEN — so today every distributor silently has unlimited everything. A default plan is
+   * how that becomes deliberate: a real package with real limits, assigned automatically, so the
+   * system's answer to "what may this person do" stops being "we never decided".
+   *
+   * ── Idempotent, and safe to call from anywhere ───────────────────────────────────────────────
+   * Returns the existing subscription untouched if one is live. That matters because the natural
+   * call site is distributor creation, and distributors get created down several paths (self
+   * onboarding, admin, draft approval, bulk import) — a provisioner that could double-assign would
+   * have to be wired carefully into exactly one of them, which is how coverage gaps happen. This
+   * one can be called from all of them, or twice, or after the fact.
+   *
+   * ── Never fatal ──────────────────────────────────────────────────────────────────────────────
+   * Returns null on any failure rather than throwing. Callers create distributors; a subscription
+   * that could not be provisioned must never be the reason a distributor does not exist. The gap
+   * is recoverable by calling this again — a failed creation is not.
+   *
+   * @param {Object} p
+   * @param {string} p.subjectType   "distributor" | "client"
+   * @param {string} p.subjectId
+   * @param {string} [p.accountId]
+   * @param {Date}   [p.now]
+   * @returns {Promise<Object|null>} the subscription (existing or new), or null
+   */
+  async function provisionDefault({ subjectType, subjectId, accountId = null, now = new Date() } = {}) {
+    try {
+      // No auto-provisioning while the domain is off, whatever the catalogue says. This is the
+      // one that would otherwise write rows into production on the first distributor created.
+      if (!(await enabled())) return null;
+
+      const db = getDb();
+      if (!db || !subjectType || !subjectId) return null;
+
+      const existing = await findSubscription({ subjectType, subjectId });
+      if (existing) return existing;
+
+      // The default plan is a property of the CATALOGUE, not of this code — so which package new
+      // distributors get, and for how long, is changed by editing a plan rather than deploying.
+      const plan = await db.collection("plan_catalog").findOne({
+        default_for: subjectType,
+        status: "active",
+      });
+      if (!plan) return null;
+
+      const days = Number(plan.default_duration_days) || 0;
+      const start = new Date(now);
+      const end = new Date(now);
+      if (days > 0) end.setDate(end.getDate() + days);
+      // No duration means an open-ended default tier; period_end null reads as "does not lapse".
+      const periodEnd = days > 0 ? end : null;
+
+      /**
+       * Status is `active`, not `trialing`.
+       *
+       * This is a real package on real terms, not a taste of a bigger one — and `trialing` would
+       * make trial-cycle entitlement rows take precedence, quietly applying terms nobody wrote for
+       * this plan. The trial mechanism stays available for plans that actually want it.
+       */
+      const doc = {
+        account_id: accountId ? oid(accountId) : null,
+        subject_type: subjectType,
+        subject_id: oid(subjectId),
+        plan_code: plan.plan_code,
+        cycle: plan.default_cycle || "monthly",
+        status: "active",
+        period_start: start,
+        period_end: periodEnd,
+        provisioned_default: true,   // so a report can tell "given" from "bought"
+        createdAt: new Date(),
+      };
+
+      try {
+        await db.collection("account_subscriptions").insertOne(doc);
+      } catch (e) {
+        // Two creation paths racing on the same subject. The partial unique index on a live
+        // subscription is what makes this safe: one wins, and the loser reads the winner's row
+        // rather than creating a duplicate.
+        if (e?.code === 11000) return findSubscription({ subjectType, subjectId });
+        throw e;
+      }
+      return doc;
+    } catch (e) {
+      logger.warn(`[entitlement] default provisioning failed for ${subjectType} ${subjectId}: ${e.message}`);
+      return null;
+    }
+  }
+
+  return { findSubscription, entitlementFor, consume, provisionDefault };
+}
+
+export default { createEntitlementStore };