Enforce tenant isolation in the data layer instead of per route

Every route had to remember to add the business filter to every query;
nothing stopped one that forgot. The audit for this change found several
that had: the M-Pesa status re-check, the stock ledger's duplicate checks,
the daily-inventory and branch-price upserts, a cash-sale replay lookup,
several load-by-id lookups, and every populate().

- tenantGuard: a Mongoose plugin on all ten business-scoped models. Any
  find/update/delete/count/distinct, or an aggregate whose first stage is
  not a $match, that does not pin exactly one businessId throws
  TenantScopeError before reaching the database ($in, $exists and other
  operators do not count).
- crossTenant("reason", fn): the explicit, documented exemption for the
  queries that must span businesses - login's email lookup, refresh and
  invite-token lookups, the M-Pesa callback, the platform console and the
  maintenance scripts. git grep crossTenant lists them all.
- scopedPopulate: populated branch, product and staff names are also
  restricted to the business.
- Every flagged query site now names the business (or is exempted with a
  reason).
- Tests: a check that every model with a businessId field carries the
  guard; the guard refusing unscoped queries of every kind; and a route
  sweep where business A sends business B's ids to every read route
  (nothing of B's comes back) and every write route (all refused, B's
  data unchanged). Test-side database inspections go through db(), an
  explicit test exemption. Removing one route's business filter makes the
  suite fail.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

tests/followups.test.ts

@@ -19,7 +19,7 @@ import * as profit from "@/app/api/reports/profit/route";
 import * as cash from "@/app/api/transactions/cash/route";
 import * as adjustments from "@/app/api/stock/adjustments/route";
 import * as transfers from "@/app/api/stock/transfers/route";
-import { json, makeTenant, params, req, uuid, type Tenant } from "./helpers";
+import { json, makeTenant, params, req, uuid, type Tenant, db } from "./helpers";
 
 async function setPlan(t: Tenant, tier: string, subscriptionStatus: string) {
   await Business.updateOne({ _id: t.businessId }, { tier, subscriptionStatus });
@@ -39,7 +39,7 @@ describe("F-01 trial branch allowance", () => {
   it("counts only active branches, and a paid Starter plan allows one", async () => {
     const t = await makeTenant();
     await setPlan(t, "STARTER", "TRIALING");
-    await Branch.updateOne({ _id: t.branchB }, { isActive: false });
+    await db(() => Branch.updateOne({ _id: t.branchB }, { isActive: false }));
     expect((await branches.POST(req("POST", "/x", { as: t.owner, body: newBranch("C") }))).status).toBe(201);
 
     await setPlan(t, "STARTER", "ACTIVE");
@@ -70,7 +70,7 @@ describe("F-06 branch deactivation", () => {
     expect(withStaff.status).toBe(409);
     expect((await withStaff.json()).error).toMatch(/active staff/);
 
-    await User.updateOne({ _id: t.cashierB.id }, { isActive: false });
+    await db(() => User.updateOne({ _id: t.cashierB.id }, { isActive: false }));
     expect((await deactivate()).status).toBe(200);
 
     // Hidden from pickers, kept on the Branches page.
@@ -82,7 +82,7 @@ describe("F-06 branch deactivation", () => {
 
   it("will not reactivate a branch past the plan's limit", async () => {
     const t = await makeTenant();
-    await Branch.updateOne({ _id: t.branchB }, { isActive: false });
+    await db(() => Branch.updateOne({ _id: t.branchB }, { isActive: false }));
     await setPlan(t, "STARTER", "ACTIVE");
     const res = await branchById.PATCH(req("PATCH", "/x", { as: t.owner, body: { isActive: true } }), params({ id: t.branchB }));
     expect(res.status).toBe(403);
@@ -152,7 +152,7 @@ describe("F-04 / F-05 / CAT-12 catalogue", () => {
     await adjustments.POST(
       req("POST", "/x", { as: t.owner, body: { clientUuid: uuid(), branchId: t.branchA, productId: t.water5, mode: "DELTA", quantity: 7 } })
     );
-    await Product.updateOne({ _id: t.water5 }, { isActive: false });
+    await db(() => Product.updateOne({ _id: t.water5 }, { isActive: false }));
 
     const forManager = await json(await products.GET(req("GET", "/api/products?includeInactive=1", { as: t.managerA })));
     const forCashier = await json(await products.GET(req("GET", "/api/products?includeInactive=1", { as: t.cashierA })));
@@ -228,13 +228,13 @@ describe("STA-04 staff invites", () => {
     expect((await invites.GET(req("GET", "/x"), params({ token }))).status).toBe(404);
     expect((await invites.GET(req("GET", "/x"), params({ token: fresh }))).status).toBe(200);
 
-    await User.updateOne({ _id: new mongoose.Types.ObjectId(userId) }, { inviteExpiresAt: new Date(Date.now() - 1000) });
+    await db(() => User.updateOne({ _id: new mongoose.Types.ObjectId(userId) }, { inviteExpiresAt: new Date(Date.now() - 1000) }));
     expect((await invites.GET(req("GET", "/x"), params({ token: fresh }))).status).toBe(404);
   });
 
   it("does not let a manager re-invite another branch's staff", async () => {
     const t = await makeTenant();
-    await User.updateOne({ _id: t.cashierB.id }, { inviteExpiresAt: new Date(Date.now() + 60_000) });
+    await db(() => User.updateOne({ _id: t.cashierB.id }, { inviteExpiresAt: new Date(Date.now() + 60_000) }));
     const res = await reinvite.POST(req("POST", "/x", { as: t.managerA }), params({ id: t.cashierB.id }));
     expect(res.status).toBe(403);
   });