@i4e/invest4edu-access-core 0.32.0 → 0.33.0

package/src/subscription-lifecycle.js

@@ -1,106 +1,106 @@
-/**
- * Subscription lifecycle — statuses, transitions and event types. SHARED, because code branches
- * on these in both backends and a status list that drifts between them means one side treats a
- * subscription as live while the other has cut access (invariant #11).
- *
- * The machine:
- *
- *   trialing → active | cancelled | expired
- *   active   → past_due | blocked | cancelled
- *   past_due → active | blocked | cancelled          (payment recovered | gave up | user quit)
- *   blocked  → active | cancelled                    (recovered | closed)
- *   cancelled / expired → (terminal — a new purchase creates a NEW subscription)
- *
- * Terminal states stay terminal on purpose: "reactivating" a cancelled row would resurrect its
- * history, overrides and period as if nothing happened. A fresh subscription is honest about the
- * gap and keeps the audit trail of the old one intact.
- *
- * Upgrade/downgrade are TRANSITIONS OF PLAN, not of status — a plan change happens on a live
- * subscription and does not appear here.
- */
-
-export const SUBSCRIPTION_STATUSES = Object.freeze([
-  "trialing", "active", "past_due", "blocked", "cancelled", "expired",
-]);
-
-/** States in which entitlements resolve. past_due keeps working — cutting access the moment a
- *  payment is late loses more than it protects; `blocked` is the deliberate cut-off. */
-export const LIVE_STATUSES = Object.freeze(["trialing", "active", "past_due"]);
-
-export const TRANSITIONS = Object.freeze({
-  trialing: ["active", "cancelled", "expired"],
-  // `expired` because a FIXED-TERM subscription that reaches its end has simply run out. Without
-  // it the only exits are `blocked`, which implies a deliberate cut-off, and `cancelled`, which
-  // implies the customer chose to leave — neither is true of a 90-day plan reaching day 91.
-  active: ["past_due", "blocked", "cancelled", "expired"],
-  past_due: ["active", "blocked", "cancelled"],
-  blocked: ["active", "cancelled"],
-  cancelled: [],
-  expired: [],
-});
-
-/** `{ ok }` or `{ ok: false, message }` naming the legal moves — the caller shows it verbatim. */
-export function canTransition(from, to) {
-  const allowed = TRANSITIONS[from];
-  if (!allowed) return { ok: false, message: `${from} is not a subscription status` };
-  if (from === to) return { ok: false, message: `already ${from}` };
-  if (!allowed.includes(to)) {
-    return {
-      ok: false,
-      message: allowed.length
-        ? `${from} can only move to: ${allowed.join(", ")}`
-        : `${from} is terminal — a new purchase creates a new subscription`,
-    };
-  }
-  return { ok: true };
-}
-
-/**
- * Event types — the audit spine AND what the Events Engine receives (`subscription.<type>`).
- * Engagement and monitoring both hang off this list, so an unlisted type is an event nobody can
- * subscribe to: recording one is refused rather than silently accepted.
- */
-export const SUBSCRIPTION_EVENT_TYPES = Object.freeze([
-  "created", "trial_started", "activated", "renewed",
-  "plan_changed", "cycle_changed", "period_extended",
-  /**
-   * A term cut short by hand. Its own type rather than a negative `period_extended`, because the
-   * two raise opposite money questions — one leaves us owing product, the other owing money — and
-   * a stream where they look alike cannot be read for either.
-   */
-  "period_shortened",
-  /** Somebody looked at a raised billing question and closed it. */
-  "billing_review_cleared",
-  "override_set", "override_removed",
-  "status_changed", "cancelled", "blocked", "expired",
-  "payment_captured", "payment_failed",
-  "quota_exceeded",
-  // 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",
-  /**
-   * Credits handed out by an admin, rather than bought or rolled over.
-   *
-   * It used to be recorded as `override_set`, which made the history unreadable at exactly the
-   * moment it mattered: a one-off top-up and a permanent change to somebody's per-period allowance
-   * are different promises, and "who gave this partner 500 credits" cannot be answered by a stream
-   * where both look identical.
-   */
-  "credits_granted",
-  /**
-   * 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.
-   *
-   * A refund is the one flow where WHO ASKED and WHO AGREED both matter later — a credit note
-   * shows money went back but not that anyone approved it. `refund_requested` is the customer's
-   * ask, `refund_rejected` closes it with a reason, and `refunded` is the money actually moving.
-   */
-  "refund_requested", "refund_approved", "refund_rejected", "refunded",
-]);
-
-export default { SUBSCRIPTION_STATUSES, LIVE_STATUSES, TRANSITIONS, canTransition, SUBSCRIPTION_EVENT_TYPES };
+/**
+ * Subscription lifecycle — statuses, transitions and event types. SHARED, because code branches
+ * on these in both backends and a status list that drifts between them means one side treats a
+ * subscription as live while the other has cut access (invariant #11).
+ *
+ * The machine:
+ *
+ *   trialing → active | cancelled | expired
+ *   active   → past_due | blocked | cancelled
+ *   past_due → active | blocked | cancelled          (payment recovered | gave up | user quit)
+ *   blocked  → active | cancelled                    (recovered | closed)
+ *   cancelled / expired → (terminal — a new purchase creates a NEW subscription)
+ *
+ * Terminal states stay terminal on purpose: "reactivating" a cancelled row would resurrect its
+ * history, overrides and period as if nothing happened. A fresh subscription is honest about the
+ * gap and keeps the audit trail of the old one intact.
+ *
+ * Upgrade/downgrade are TRANSITIONS OF PLAN, not of status — a plan change happens on a live
+ * subscription and does not appear here.
+ */
+
+export const SUBSCRIPTION_STATUSES = Object.freeze([
+  "trialing", "active", "past_due", "blocked", "cancelled", "expired",
+]);
+
+/** States in which entitlements resolve. past_due keeps working — cutting access the moment a
+ *  payment is late loses more than it protects; `blocked` is the deliberate cut-off. */
+export const LIVE_STATUSES = Object.freeze(["trialing", "active", "past_due"]);
+
+export const TRANSITIONS = Object.freeze({
+  trialing: ["active", "cancelled", "expired"],
+  // `expired` because a FIXED-TERM subscription that reaches its end has simply run out. Without
+  // it the only exits are `blocked`, which implies a deliberate cut-off, and `cancelled`, which
+  // implies the customer chose to leave — neither is true of a 90-day plan reaching day 91.
+  active: ["past_due", "blocked", "cancelled", "expired"],
+  past_due: ["active", "blocked", "cancelled"],
+  blocked: ["active", "cancelled"],
+  cancelled: [],
+  expired: [],
+});
+
+/** `{ ok }` or `{ ok: false, message }` naming the legal moves — the caller shows it verbatim. */
+export function canTransition(from, to) {
+  const allowed = TRANSITIONS[from];
+  if (!allowed) return { ok: false, message: `${from} is not a subscription status` };
+  if (from === to) return { ok: false, message: `already ${from}` };
+  if (!allowed.includes(to)) {
+    return {
+      ok: false,
+      message: allowed.length
+        ? `${from} can only move to: ${allowed.join(", ")}`
+        : `${from} is terminal — a new purchase creates a new subscription`,
+    };
+  }
+  return { ok: true };
+}
+
+/**
+ * Event types — the audit spine AND what the Events Engine receives (`subscription.<type>`).
+ * Engagement and monitoring both hang off this list, so an unlisted type is an event nobody can
+ * subscribe to: recording one is refused rather than silently accepted.
+ */
+export const SUBSCRIPTION_EVENT_TYPES = Object.freeze([
+  "created", "trial_started", "activated", "renewed",
+  "plan_changed", "cycle_changed", "period_extended",
+  /**
+   * A term cut short by hand. Its own type rather than a negative `period_extended`, because the
+   * two raise opposite money questions — one leaves us owing product, the other owing money — and
+   * a stream where they look alike cannot be read for either.
+   */
+  "period_shortened",
+  /** Somebody looked at a raised billing question and closed it. */
+  "billing_review_cleared",
+  "override_set", "override_removed",
+  "status_changed", "cancelled", "blocked", "expired",
+  "payment_captured", "payment_failed",
+  "quota_exceeded",
+  // 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",
+  /**
+   * Credits handed out by an admin, rather than bought or rolled over.
+   *
+   * It used to be recorded as `override_set`, which made the history unreadable at exactly the
+   * moment it mattered: a one-off top-up and a permanent change to somebody's per-period allowance
+   * are different promises, and "who gave this partner 500 credits" cannot be answered by a stream
+   * where both look identical.
+   */
+  "credits_granted",
+  /**
+   * 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.
+   *
+   * A refund is the one flow where WHO ASKED and WHO AGREED both matter later — a credit note
+   * shows money went back but not that anyone approved it. `refund_requested` is the customer's
+   * ask, `refund_rejected` closes it with a reason, and `refunded` is the money actually moving.
+   */
+  "refund_requested", "refund_approved", "refund_rejected", "refunded",
+]);
+
+export default { SUBSCRIPTION_STATUSES, LIVE_STATUSES, TRANSITIONS, canTransition, SUBSCRIPTION_EVENT_TYPES };

package/src/tenant-context.js

@@ -1,26 +1,26 @@
-/**
- * Tenant request-context — @i4e/invest4edu-access-core (Track 3 D1 keystone).
- *
- * AsyncLocalStorage carries the authenticated identity (`account_id`, `userId`, `roles`)
- * for the lifetime of a request. The tenant plugin (tenant-plugin.js) reads `account_id`
- * from here and injects it into every tenant-scoped read.
- *
- * Store shapes:
- *   { account_id, userId, roles }  — a normal authenticated request (JWT path)
- *   { system: true }               — a legitimate cross-tenant/non-request context via runAsSystem()
- *   (empty)                        — no identity. Plugin fails closed in `enforce`, warns in `warn`.
- */
-import { AsyncLocalStorage } from "async_hooks";
-
-const als = new AsyncLocalStorage();
-
-/** Run `fn` with the given tenant identity in context. */
-export const runWithTenant = (store, fn) => als.run(store || {}, fn);
-
-/** Run `fn` in a system context that bypasses tenant injection (scripts, cross-tenant reads). */
-export const runAsSystem = (fn) => als.run({ system: true }, fn);
-
-/** Current tenant store (or undefined outside any run scope). */
-export const getTenantStore = () => als.getStore();
-
-export default als;
+/**
+ * Tenant request-context — @i4e/invest4edu-access-core (Track 3 D1 keystone).
+ *
+ * AsyncLocalStorage carries the authenticated identity (`account_id`, `userId`, `roles`)
+ * for the lifetime of a request. The tenant plugin (tenant-plugin.js) reads `account_id`
+ * from here and injects it into every tenant-scoped read.
+ *
+ * Store shapes:
+ *   { account_id, userId, roles }  — a normal authenticated request (JWT path)
+ *   { system: true }               — a legitimate cross-tenant/non-request context via runAsSystem()
+ *   (empty)                        — no identity. Plugin fails closed in `enforce`, warns in `warn`.
+ */
+import { AsyncLocalStorage } from "async_hooks";
+
+const als = new AsyncLocalStorage();
+
+/** Run `fn` with the given tenant identity in context. */
+export const runWithTenant = (store, fn) => als.run(store || {}, fn);
+
+/** Run `fn` in a system context that bypasses tenant injection (scripts, cross-tenant reads). */
+export const runAsSystem = (fn) => als.run({ system: true }, fn);
+
+/** Current tenant store (or undefined outside any run scope). */
+export const getTenantStore = () => als.getStore();
+
+export default als;

package/src/tenant-plugin.js

@@ -1,177 +1,177 @@
-/**
- * Tenant-isolation Mongoose plugin — @i4e/invest4edu-access-core (Track 3 D1 keystone).
- *
- * Applied to tenant-scoped models. It injects `account_id` from the request's ALS store
- * (tenant-context.js) into the FILTER of every operation that selects existing documents, so a
- * query cannot reach Mongo without the caller's tenant boundary — even if the controller forgot it.
- *
- * ── TWO LADDERS, ON PURPOSE ──────────────────────────────────────────────────────────────────
- * Reads and writes have SEPARATE switches, each defaulting to `off`:
- *
- *   reads   `TENANT_ENFORCEMENT`         / accessconfig.tenantEnforcement
- *   writes  `TENANT_ENFORCEMENT_WRITES`  / accessconfig.tenantEnforcementWrites
- *
- * They are separate because the blast radius is not comparable. A read that gains a filter
- * returns less data; a write that gains a filter silently modifies NOTHING, and the caller is
- * told it succeeded. Nobody promoting reads to `warn` should discover they also armed writes.
- *
- * Each ladder: off → warn (burn-in, watch `[tenant] identity-less`) → enforce.
- *
- *   off (DEFAULT)  literal no-op; behaviour identical to pre-Track-3. Safe merge baseline.
- *   warn           READS:  inject when identity present; log identity-less reads.
- *                  WRITES: log identity-less writes; NEVER alter the filter (see below).
- *   enforce        inject when identity present; THROW on identity-less (fail-closed).
- *
- * The read/write asymmetry at `warn` is deliberate. `warn` means "tell me what enforce would do",
- * and for a destructive operation that promise is only kept by changing nothing. Injecting on a
- * write under a mode named `warn` would silently turn UPDATEs into no-ops in production — the
- * exact failure the burn-in step exists to avoid. The signal you need before promoting is which
- * writes run identity-less, and that is logged.
- *
- * Precedence per ladder: env var (if valid) > DB value (setTenantMode/setTenantWriteMode) > "off".
- * The DB value is the admin-UI toggle (takes effect on the next config refresh, no restart); the
- * env var is the infra-level emergency override.
- *
- * Bypass: `runAsSystem(fn)` or `.setOptions({ skipTenant: true })` for legitimately cross-tenant
- * operations. NOT covered: aggregation pipelines — add an explicit `{ $match: { account_id } }`.
- *
- * Logging is intentionally `console.warn` (not a repo-specific logger) so this file stays
- * byte-identical across both backends. Warnings surface in stdout logs during burn-in.
- */
-import als from "./tenant-context.js";
-
-/** Reads. Governed by the READ ladder. */
-const READ_OPS = ["find", "findOne", "countDocuments", "distinct"];
-
-/**
- * Writes that SELECT existing documents by filter. Governed by the WRITE ladder.
- *
- * `save` / `create` / `insertMany` are absent and cannot be added: they carry no filter. Putting
- * `account_id` ON a new document is the caller's job — this plugin only constrains which EXISTING
- * documents an operation may reach. `estimatedDocumentCount` is absent for the same reason: it
- * takes no filter, so there is nothing to scope.
- */
-const WRITE_OPS = [
-  "updateOne",
-  "updateMany",
-  "replaceOne",
-  "deleteOne",
-  "deleteMany",
-  "findOneAndUpdate",
-  "findOneAndReplace",
-  "findOneAndDelete",
-];
-
-/**
- * Mongoose registers these names as BOTH document and query middleware, and which one you get by
- * default has moved between major versions (the package supports mongoose >= 6). Pin the query
- * form explicitly. The document form would be wrong here anyway — it fires on an already-loaded
- * document, which was fetched through a read hook and is therefore already scoped.
- */
-const DUAL_HOOKS = new Set(["updateOne", "deleteOne"]);
-
-/**
- * The enforcement ladder, in order. Exported because both backends validate an incoming mode
- * before storing it and render the choices in the admin UI — without this they each keep their
- * own `["off","warn","enforce"]` literal, and a mode added here would be silently unsettable.
- */
-export const TENANT_MODES = Object.freeze(["off", "warn", "enforce"]);
-
-const VALID = new Set(TENANT_MODES);
-
-let dbMode = null; // reads
-let dbWriteMode = null; // writes
-
-/** Bad values are reported once each, not once per query — this runs on every operation. */
-const warnedBadValues = new Set();
-
-/**
- * Parse a mode from env or DB. Returns null for absent OR unrecognised, so the caller falls
- * through to the next source in the precedence chain.
- *
- * Trimming matters more than it looks: `TENANT_ENFORCEMENT="enforce "` pasted into App Service
- * config, or a stray space in the admin UI, used to fail the VALID check and silently downgrade
- * enforcement to `off` while every screen still read "enforce".
- */
-function normaliseMode(raw, source) {
-  const v = raw == null ? "" : String(raw).trim().toLowerCase();
-  if (!v) return null;
-  if (VALID.has(v)) return v;
-
-  const seen = `${source}=${v}`;
-  if (!warnedBadValues.has(seen)) {
-    warnedBadValues.add(seen);
-    // eslint-disable-next-line no-console
-    console.warn(
-      `[tenant] unrecognised enforcement mode ${seen} — expected ${[...VALID].join(" | ")}; ignoring this source`,
-    );
-  }
-  return null;
-}
-
-/** Called by the backend from the `accessconfig` DB doc so a UI toggle takes effect (~refresh). */
-export function setTenantMode(m) {
-  dbMode = normaliseMode(m, "accessconfig.tenantEnforcement");
-}
-
-/** Effective READ mode. */
-export function getTenantMode() {
-  return normaliseMode(process.env.TENANT_ENFORCEMENT, "TENANT_ENFORCEMENT") || dbMode || "off";
-}
-
-/** Write-ladder counterpart of setTenantMode. */
-export function setTenantWriteMode(m) {
-  dbWriteMode = normaliseMode(m, "accessconfig.tenantEnforcementWrites");
-}
-
-/** Effective WRITE mode. Independent of the read mode — never inherits it. */
-export function getTenantWriteMode() {
-  return (
-    normaliseMode(process.env.TENANT_ENFORCEMENT_WRITES, "TENANT_ENFORCEMENT_WRITES") ||
-    dbWriteMode ||
-    "off"
-  );
-}
-
-/**
- * @param {() => string} getMode      the ladder this op answers to
- * @param {string} opName            fallback for `this.op`
- * @param {"read"|"write"} kind
- */
-function makeTenantHook(getMode, opName, kind) {
-  return function tenantHook() {
-    const mode = getMode();
-    if (mode === "off") return; // literal no-op — identical to pre-Track-3
-
-    const opts = typeof this.getOptions === "function" ? this.getOptions() : this.options || {};
-    if (opts && opts.skipTenant) return;
-
-    const store = als.getStore();
-    if (store && store.system) return; // runAsSystem — cross-tenant by design
-
-    if (store && store.account_id) {
-      // A write under `warn` is observed, never altered. See the ladder note at the top.
-      if (kind === "write" && mode === "warn") return;
-      this.where({ account_id: store.account_id }); // identity is authoritative
-      return;
-    }
-
-    const modelName = (this.model && this.model.modelName) || "unknown";
-    const op = this.op || opName;
-    if (mode === "enforce") {
-      throw new Error(`tenant identity required — no account_id in context for ${modelName}.${op}`);
-    }
-    // eslint-disable-next-line no-console
-    console.warn(`[tenant] identity-less ${kind} ${modelName}.${op} not scoped (warn mode)`);
-  };
-}
-
-export default function tenantPlugin(schema) {
-  READ_OPS.forEach((op) => schema.pre(op, makeTenantHook(getTenantMode, op, "read")));
-
-  WRITE_OPS.forEach((op) => {
-    const hook = makeTenantHook(getTenantWriteMode, op, "write");
-    if (DUAL_HOOKS.has(op)) schema.pre(op, { document: false, query: true }, hook);
-    else schema.pre(op, hook);
-  });
-}
+/**
+ * Tenant-isolation Mongoose plugin — @i4e/invest4edu-access-core (Track 3 D1 keystone).
+ *
+ * Applied to tenant-scoped models. It injects `account_id` from the request's ALS store
+ * (tenant-context.js) into the FILTER of every operation that selects existing documents, so a
+ * query cannot reach Mongo without the caller's tenant boundary — even if the controller forgot it.
+ *
+ * ── TWO LADDERS, ON PURPOSE ──────────────────────────────────────────────────────────────────
+ * Reads and writes have SEPARATE switches, each defaulting to `off`:
+ *
+ *   reads   `TENANT_ENFORCEMENT`         / accessconfig.tenantEnforcement
+ *   writes  `TENANT_ENFORCEMENT_WRITES`  / accessconfig.tenantEnforcementWrites
+ *
+ * They are separate because the blast radius is not comparable. A read that gains a filter
+ * returns less data; a write that gains a filter silently modifies NOTHING, and the caller is
+ * told it succeeded. Nobody promoting reads to `warn` should discover they also armed writes.
+ *
+ * Each ladder: off → warn (burn-in, watch `[tenant] identity-less`) → enforce.
+ *
+ *   off (DEFAULT)  literal no-op; behaviour identical to pre-Track-3. Safe merge baseline.
+ *   warn           READS:  inject when identity present; log identity-less reads.
+ *                  WRITES: log identity-less writes; NEVER alter the filter (see below).
+ *   enforce        inject when identity present; THROW on identity-less (fail-closed).
+ *
+ * The read/write asymmetry at `warn` is deliberate. `warn` means "tell me what enforce would do",
+ * and for a destructive operation that promise is only kept by changing nothing. Injecting on a
+ * write under a mode named `warn` would silently turn UPDATEs into no-ops in production — the
+ * exact failure the burn-in step exists to avoid. The signal you need before promoting is which
+ * writes run identity-less, and that is logged.
+ *
+ * Precedence per ladder: env var (if valid) > DB value (setTenantMode/setTenantWriteMode) > "off".
+ * The DB value is the admin-UI toggle (takes effect on the next config refresh, no restart); the
+ * env var is the infra-level emergency override.
+ *
+ * Bypass: `runAsSystem(fn)` or `.setOptions({ skipTenant: true })` for legitimately cross-tenant
+ * operations. NOT covered: aggregation pipelines — add an explicit `{ $match: { account_id } }`.
+ *
+ * Logging is intentionally `console.warn` (not a repo-specific logger) so this file stays
+ * byte-identical across both backends. Warnings surface in stdout logs during burn-in.
+ */
+import als from "./tenant-context.js";
+
+/** Reads. Governed by the READ ladder. */
+const READ_OPS = ["find", "findOne", "countDocuments", "distinct"];
+
+/**
+ * Writes that SELECT existing documents by filter. Governed by the WRITE ladder.
+ *
+ * `save` / `create` / `insertMany` are absent and cannot be added: they carry no filter. Putting
+ * `account_id` ON a new document is the caller's job — this plugin only constrains which EXISTING
+ * documents an operation may reach. `estimatedDocumentCount` is absent for the same reason: it
+ * takes no filter, so there is nothing to scope.
+ */
+const WRITE_OPS = [
+  "updateOne",
+  "updateMany",
+  "replaceOne",
+  "deleteOne",
+  "deleteMany",
+  "findOneAndUpdate",
+  "findOneAndReplace",
+  "findOneAndDelete",
+];
+
+/**
+ * Mongoose registers these names as BOTH document and query middleware, and which one you get by
+ * default has moved between major versions (the package supports mongoose >= 6). Pin the query
+ * form explicitly. The document form would be wrong here anyway — it fires on an already-loaded
+ * document, which was fetched through a read hook and is therefore already scoped.
+ */
+const DUAL_HOOKS = new Set(["updateOne", "deleteOne"]);
+
+/**
+ * The enforcement ladder, in order. Exported because both backends validate an incoming mode
+ * before storing it and render the choices in the admin UI — without this they each keep their
+ * own `["off","warn","enforce"]` literal, and a mode added here would be silently unsettable.
+ */
+export const TENANT_MODES = Object.freeze(["off", "warn", "enforce"]);
+
+const VALID = new Set(TENANT_MODES);
+
+let dbMode = null; // reads
+let dbWriteMode = null; // writes
+
+/** Bad values are reported once each, not once per query — this runs on every operation. */
+const warnedBadValues = new Set();
+
+/**
+ * Parse a mode from env or DB. Returns null for absent OR unrecognised, so the caller falls
+ * through to the next source in the precedence chain.
+ *
+ * Trimming matters more than it looks: `TENANT_ENFORCEMENT="enforce "` pasted into App Service
+ * config, or a stray space in the admin UI, used to fail the VALID check and silently downgrade
+ * enforcement to `off` while every screen still read "enforce".
+ */
+function normaliseMode(raw, source) {
+  const v = raw == null ? "" : String(raw).trim().toLowerCase();
+  if (!v) return null;
+  if (VALID.has(v)) return v;
+
+  const seen = `${source}=${v}`;
+  if (!warnedBadValues.has(seen)) {
+    warnedBadValues.add(seen);
+    // eslint-disable-next-line no-console
+    console.warn(
+      `[tenant] unrecognised enforcement mode ${seen} — expected ${[...VALID].join(" | ")}; ignoring this source`,
+    );
+  }
+  return null;
+}
+
+/** Called by the backend from the `accessconfig` DB doc so a UI toggle takes effect (~refresh). */
+export function setTenantMode(m) {
+  dbMode = normaliseMode(m, "accessconfig.tenantEnforcement");
+}
+
+/** Effective READ mode. */
+export function getTenantMode() {
+  return normaliseMode(process.env.TENANT_ENFORCEMENT, "TENANT_ENFORCEMENT") || dbMode || "off";
+}
+
+/** Write-ladder counterpart of setTenantMode. */
+export function setTenantWriteMode(m) {
+  dbWriteMode = normaliseMode(m, "accessconfig.tenantEnforcementWrites");
+}
+
+/** Effective WRITE mode. Independent of the read mode — never inherits it. */
+export function getTenantWriteMode() {
+  return (
+    normaliseMode(process.env.TENANT_ENFORCEMENT_WRITES, "TENANT_ENFORCEMENT_WRITES") ||
+    dbWriteMode ||
+    "off"
+  );
+}
+
+/**
+ * @param {() => string} getMode      the ladder this op answers to
+ * @param {string} opName            fallback for `this.op`
+ * @param {"read"|"write"} kind
+ */
+function makeTenantHook(getMode, opName, kind) {
+  return function tenantHook() {
+    const mode = getMode();
+    if (mode === "off") return; // literal no-op — identical to pre-Track-3
+
+    const opts = typeof this.getOptions === "function" ? this.getOptions() : this.options || {};
+    if (opts && opts.skipTenant) return;
+
+    const store = als.getStore();
+    if (store && store.system) return; // runAsSystem — cross-tenant by design
+
+    if (store && store.account_id) {
+      // A write under `warn` is observed, never altered. See the ladder note at the top.
+      if (kind === "write" && mode === "warn") return;
+      this.where({ account_id: store.account_id }); // identity is authoritative
+      return;
+    }
+
+    const modelName = (this.model && this.model.modelName) || "unknown";
+    const op = this.op || opName;
+    if (mode === "enforce") {
+      throw new Error(`tenant identity required — no account_id in context for ${modelName}.${op}`);
+    }
+    // eslint-disable-next-line no-console
+    console.warn(`[tenant] identity-less ${kind} ${modelName}.${op} not scoped (warn mode)`);
+  };
+}
+
+export default function tenantPlugin(schema) {
+  READ_OPS.forEach((op) => schema.pre(op, makeTenantHook(getTenantMode, op, "read")));
+
+  WRITE_OPS.forEach((op) => {
+    const hook = makeTenantHook(getTenantWriteMode, op, "write");
+    if (DUAL_HOOKS.has(op)) schema.pre(op, { document: false, query: true }, hook);
+    else schema.pre(op, hook);
+  });
+}