@7365admin1/core 3.65.2 → 3.67.0

package/test/org-owner-repair.test.mjs

@@ -0,0 +1,726 @@
+/**
+ * THE ORGANISATION WITH NO OWNER — the decision, and the wiring around it.
+ *
+ * Two halves, tested two ways, the same split the console-audit and
+ * default-role work uses. The DECISION (may this organisation be repaired) is
+ * pure and is executed here. The WIRING (staff gate, claim before write, the
+ * owner never coming from the request, the role resolved only after the count
+ * says zero) is read off the source, because constructing the controller needs a
+ * live Atlas connection. The end-to-end half is
+ * `test/e2e/org-owner-repair.e2e.test.mjs`.
+ *
+ * Every assertion has a POSITIVE CONTROL beside it. Without them a planner that
+ * refused everything would pass "never writes a second owner" and "fails closed"
+ * perfectly while repairing nothing at all.
+ *
+ * **Nothing here opens a socket or a database.**
+ */
+
+import { strict as assert } from "node:assert";
+import test from "node:test";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+import {
+  ORG_OWNER_REPAIR_CLAIM_STALE_MS,
+  ORG_OWNER_REPAIR_CLAIM_TAKEN_REASON,
+  ORG_OWNER_REPAIR_DEFAULT,
+  ORG_OWNER_REPAIR_OFF_REASON,
+  claimReadsAsStale,
+  orgOwnerRepairOn,
+  orgQualifiesForOwnerRepair,
+  planOrgOwnerRepair,
+} from "./.build/utils/org-owner-repair.util.mjs";
+import { MEMBER_TYPES } from "./.build/models/member.model.mjs";
+import {
+  ConsoleAuditAction,
+  CONSOLE_AUDIT_LABELS,
+  pickAuditFields,
+} from "./.build/utils/console-audit.util.mjs";
+import { orgOwnerRepairHandlers } from "./.build/controllers/organization.controller.mjs";
+
+const ORG = "68b0c1d2e3f4a5b6c7d8e9f0";
+const USER = "6a951ce503be44033d434f67";
+const ROLE = "6aa0c7308d25d0ba14fc5c12";
+
+const org = (extra = {}) => ({ _id: ORG, status: "active", email: "owner@example.com", ...extra });
+const plan = (extra = {}) =>
+  planOrgOwnerRepair({
+    gateOn: true,
+    org: org(),
+    orgMemberCount: 0,
+    ownerUserId: USER,
+    ownerRoleId: ROLE,
+    ...extra,
+  });
+
+// ── the row it writes ───────────────────────────────────────────────────────
+
+test("the row it plans is the one the console's landing page reads", () => {
+  assert.deepEqual(plan().payload, {
+    userId: USER,
+    orgId: ORG,
+    roleId: ROLE,
+    app: "organization",
+    onboardingRequired: true,
+  });
+
+  // `GET /api/members/user/:id/app/organization` is the query every console
+  // landing page makes, so a row of any other type leaves the owner locked out
+  // exactly as they are now. The string is the contract, not a default.
+  assert.equal(plan().payload.app, "organization");
+  assert.ok(MEMBER_TYPES.includes(plan().payload.app));
+
+  // `onboardingRequired: true` is what POST /organizations/onboarding writes for
+  // a brand-new owner, and the wizard is still ahead of these organisations.
+  assert.equal(plan().payload.onboardingRequired, true);
+
+  // POSITIVE CONTROL: the app-typed row the wizard writes for a SITE person is
+  // not this row, and must not satisfy the assertion above.
+  assert.throws(() => assert.equal("property_management_agency", "organization"));
+});
+
+// ── 1. the zero-member gate ─────────────────────────────────────────────────
+
+test("an organisation that already has a member is refused, with no exceptions", () => {
+  for (const count of [1, 2, 3, 9, 146]) {
+    const refused = plan({ orgMemberCount: count });
+    assert.equal(refused.payload, undefined, `count ${count} must plan nothing`);
+    assert.match(refused.skip, /already has/);
+  }
+
+  // POSITIVE CONTROL: zero is the one count that must NOT be refused, or this
+  // repairs nothing at all.
+  assert.ok(plan({ orgMemberCount: 0 }).payload);
+});
+
+test("an unreadable member count fails CLOSED", () => {
+  // Not knowing is not the same as knowing there are none. -1 is what the
+  // handler substitutes when the count read throws.
+  for (const count of [-1, -99, null, undefined, NaN, "0", 0.5, 1.5, Infinity, [], {}]) {
+    const refused = plan({ orgMemberCount: count });
+    assert.equal(
+      refused.payload,
+      undefined,
+      `count ${JSON.stringify(count)} must plan nothing`,
+    );
+    assert.match(refused.skip, /could not be read/);
+  }
+
+  // POSITIVE CONTROL: a real integer zero still plans.
+  assert.ok(plan({ orgMemberCount: 0 }).payload);
+});
+
+// ── 2. active organisations only ────────────────────────────────────────────
+
+test("only an active organisation is repaired", () => {
+  for (const status of ["suspended", "deleted", "inactive", "pending", "", "   ", null, undefined]) {
+    const refused = plan({ org: org({ status }) });
+    assert.equal(refused.payload, undefined, `status ${JSON.stringify(status)} must plan nothing`);
+    assert.match(refused.skip, /Only an active organisation/);
+  }
+
+  // Case and padding must not be a way past it, in either direction.
+  assert.ok(plan({ org: org({ status: "ACTIVE" }) }).payload);
+  assert.ok(plan({ org: org({ status: " active " }) }).payload);
+
+  // POSITIVE CONTROL: the ordinary active organisation plans.
+  assert.ok(plan().payload);
+});
+
+test("never an organisation without a 24-hex id", () => {
+  for (const bad of [undefined, null, "", "   ", "not-hex", "68b0c1d2", `${ORG}00`, 12345, {}]) {
+    assert.equal(
+      plan({ org: { _id: bad, status: "active" } }).payload,
+      undefined,
+      `id ${JSON.stringify(bad)} must plan nothing`,
+    );
+  }
+  assert.equal(plan({ org: null }).payload, undefined);
+  assert.equal(plan({ org: undefined }).payload, undefined);
+
+  // POSITIVE CONTROL: a good id does plan, and the payload carries it.
+  assert.equal(plan().payload.orgId, ORG);
+});
+
+// ── 3. the owner is never guessed ───────────────────────────────────────────
+
+test("no account holding the organisation's address means nothing is written", () => {
+  for (const bad of ["", null, undefined, "   ", "not-an-id", "68b0c1d2", 12345]) {
+    const refused = plan({ ownerUserId: bad });
+    assert.equal(refused.payload, undefined, `owner ${JSON.stringify(bad)} must plan nothing`);
+    assert.match(refused.skip, /No account holds/);
+  }
+
+  // POSITIVE CONTROL: a real account id does plan.
+  assert.ok(plan().payload);
+});
+
+test("a membership is never pointed at no role", () => {
+  for (const bad of ["", null, undefined, "nope", 12345]) {
+    const refused = plan({ ownerRoleId: bad });
+    assert.equal(refused.payload, undefined, `role ${JSON.stringify(bad)} must plan nothing`);
+    assert.match(refused.skip, /no .?organization.? owner role/);
+  }
+
+  // POSITIVE CONTROL
+  assert.ok(plan().payload);
+});
+
+// ── 4. the switch ───────────────────────────────────────────────────────────
+
+test("the switch off refuses everything, whatever else is true", () => {
+  const refused = plan({ gateOn: false });
+  assert.equal(refused.payload, undefined);
+  assert.equal(refused.skip, ORG_OWNER_REPAIR_OFF_REASON);
+
+  // It is checked FIRST, so an otherwise perfect organisation is still refused.
+  assert.equal(orgQualifiesForOwnerRepair({ gateOn: false }), ORG_OWNER_REPAIR_OFF_REASON);
+
+  // POSITIVE CONTROL: the same input with the switch on plans.
+  assert.ok(plan({ gateOn: true }).payload);
+});
+
+test("the switch reads off/false/0/no, defaults on, and is read per call", () => {
+  assert.equal(ORG_OWNER_REPAIR_DEFAULT, "on");
+  assert.equal(orgOwnerRepairOn({}), true, "absent means on");
+
+  for (const off of ["off", "OFF", " off ", "false", "FALSE", "0", "no", "No"]) {
+    assert.equal(orgOwnerRepairOn({ ORG_OWNER_REPAIR: off }), false, off);
+  }
+
+  for (const on of ["on", "true", "1", "yes", "", "anything"]) {
+    assert.equal(orgOwnerRepairOn({ ORG_OWNER_REPAIR: on }), true, on);
+  }
+
+  // The same spellings `MODULE_LIST_GATE` accepts, so a lead has one vocabulary.
+  const source = read("src/utils/org-owner-repair.util.ts");
+  assert.match(source, /\["off", "false", "0", "no"\]/);
+  assert.match(source, /env\.ORG_OWNER_REPAIR \?\? ORG_OWNER_REPAIR_DEFAULT/);
+});
+
+// ── 5. the short-circuit that keeps a refusal from writing ──────────────────
+
+test("the organisation-level refusals need nothing looked up", () => {
+  // This is the function the handler calls BEFORE resolving the owner role,
+  // because resolving that role can SEED roles. It must decide the switch, the
+  // id, the status and the count on its own.
+  assert.equal(orgQualifiesForOwnerRepair({ gateOn: true, org: org(), orgMemberCount: 0 }), undefined);
+  assert.match(orgQualifiesForOwnerRepair({ gateOn: true, org: org(), orgMemberCount: 1 }), /already has/);
+  assert.match(orgQualifiesForOwnerRepair({ gateOn: true, org: org({ status: "suspended" }), orgMemberCount: 0 }), /active/);
+  assert.match(orgQualifiesForOwnerRepair({ gateOn: true, org: org(), orgMemberCount: -1 }), /could not be read/);
+
+  // ... and `planOrgOwnerRepair` re-checks every one of them, so the
+  // short-circuit is never the only guard.
+  for (const [input, pattern] of [
+    [{ orgMemberCount: 1 }, /already has/],
+    [{ org: org({ status: "suspended" }) }, /active/],
+    [{ orgMemberCount: -1 }, /could not be read/],
+    [{ gateOn: false }, /switched off/],
+  ]) {
+    assert.match(plan(input).skip, pattern);
+  }
+});
+
+// ── 6. the audit row ────────────────────────────────────────────────────────
+
+test("the repair records ids and a type, and cannot record a person", () => {
+  const action = ConsoleAuditAction.CLIENT_OWNER_REPAIRED;
+
+  assert.equal(action, "client.owner-repaired");
+  assert.ok(CONSOLE_AUDIT_LABELS[action] && CONSOLE_AUDIT_LABELS[action] !== action);
+
+  const picked = pickAuditFields(action, {
+    member: USER,
+    role: ROLE,
+    memberType: "organization",
+    // everything below is NOT on the allow-list
+    email: "owner@example.com",
+    name: "A Person",
+    password: "hashed-secret-value",
+    contact: "+65 8000 0000",
+  });
+
+  assert.deepEqual(Object.keys(picked).sort(), ["member", "memberType", "role"]);
+
+  // POSITIVE CONTROL: the allow-list really is doing the work.
+  assert.equal(pickAuditFields(action, { email: "owner@example.com" }), undefined);
+});
+
+// ── 7. the wiring, read off the source ──────────────────────────────────────
+
+const read = (path) =>
+  readFileSync(fileURLToPath(new URL(`../${path}`, import.meta.url)), "utf8");
+
+/**
+ * The source with its comments taken out.
+ *
+ * Every "this file must not do X" assertion below needs it: these files
+ * deliberately NAME the thing they refuse to do, in prose, and a check run over
+ * the comments cannot tell "does not use $regex" from "explains why it does not
+ * use $regex".
+ */
+const stripComments = (src) =>
+  src.replace(/\/\*[\s\S]*?\*\//g, "").replace(/^\s*\/\/.*$/gm, "");
+
+const CONTROLLER = read("src/controllers/organization.controller.ts");
+const REPO = read("src/repositories/org-owner-repair.repo.ts");
+
+/** The body of the repair handler. */
+const HANDLER = (() => {
+  const from = CONTROLLER.indexOf("  async function repairOwnerMembership(");
+  assert.ok(from > 0, "repairOwnerMembership is gone");
+  const to = CONTROLLER.indexOf("\n  return { repairOwnerMembership };", from);
+  assert.ok(to > from);
+  return CONTROLLER.slice(from, to);
+})();
+
+/**
+ * The same two, with the prose removed. Every "this must not do X" assertion
+ * runs over these: both files deliberately NAME the thing they refuse to do
+ * (`$regex`, `countByOrg`, `GET /api/roles`, a unique index) to say why it is
+ * not used, and a check that cannot tell code from comment fails for the wrong
+ * reason.
+ */
+const REPO_CODE = stripComments(REPO);
+const HANDLER_CODE = stripComments(HANDLER);
+
+test("the endpoint is staff-gated, and the gate runs before anything else", () => {
+  assert.match(
+    HANDLER,
+    /const staffId = await requireConsolePermission\(req, "organizations"\)/,
+    "the repair is not behind the console permission",
+  );
+
+  const gate = HANDLER.indexOf("await requireConsolePermission(req");
+  for (const [what, needle] of [
+    ["the switch", "orgOwnerRepairOn"],
+    ["the organisation read", "await getOrgUncached(orgId)"],
+    ["the claim", "await claim(orgId)"],
+    ["the write", "await createMemberDirect("],
+  ]) {
+    const at = HANDLER.indexOf(needle);
+    assert.ok(at > gate, `${what} happens before the caller is judged`);
+  }
+});
+
+test("the user id is derived server-side and never taken from the request", () => {
+  // This is what stops the repair becoming a way to join an organisation you do
+  // not own, and what keeps the 3.65.0 self-enrolment guards (S2, G1) intact:
+  // the only input is the organisation id in the URL.
+  assert.doesNotMatch(HANDLER, /req\.body/, "the handler reads the request body");
+  assert.doesNotMatch(HANDLER, /userId:\s*req\./, "the user id comes from the request");
+  assert.match(
+    HANDLER,
+    /Joi\.object\(\{\s*id: Joi\.string\(\)\.hex\(\)\.length\(24\)\.required\(\),\s*\}\)/,
+    "the only validated input is the organisation id",
+  );
+
+  // The owner is the account the organisation is registered under, confirmed by
+  // `hasOrgOwnership` rather than trusted from the lookup.
+  assert.match(HANDLER, /findUserByEmail\(\s*org\?\.email/);
+  assert.match(HANDLER, /await confirmOwnership\(candidateId, orgId\)\.catch\(\(\) => false\)/);
+  assert.match(
+    CONTROLLER,
+    /confirmOwnership: hasOrgOwnership/,
+    "ownership is decided by something other than hasOrgOwnership",
+  );
+
+  // ... and the membership is attributed to the session the gate resolved.
+  assert.match(HANDLER, /createMemberDirect\(\{ \.\.\.payload, callerId: staffId \}\)/);
+});
+
+test("one writer: the claim is taken before the write and the count re-read under it", () => {
+  const claim = HANDLER.indexOf("claimToken = await claim(orgId)");
+  const recount = HANDLER.indexOf("const orgMemberCount = await countOrgMembers(orgId)");
+  const write = HANDLER.indexOf("await createMemberDirect(");
+
+  assert.ok(claim > 0 && recount > claim, "the count is not re-read UNDER the claim");
+  assert.ok(write > recount, "the write happens before the count that decides");
+
+  // The loser of the race writes nothing at all.
+  assert.match(
+    HANDLER,
+    /if \(!claimToken\) \{[\s\S]*?ORG_OWNER_REPAIR_CLAIM_TAKEN_REASON/,
+  );
+
+  // A refusal or a throw gives the claim back, so the ledger row always means
+  // "we wrote this organisation's owner membership". The release is conditional
+  // on the stamp we inserted, so it can never delete somebody else's claim.
+  assert.match(HANDLER, /if \(!payload\) \{[\s\S]*?await release\(orgId, claimToken\)/);
+  assert.match(HANDLER, /if \(claimToken\) await release\(orgId, claimToken\)/);
+  assert.match(REPO_CODE, /claims\.deleteOne\(\{ _id: toId\(org\), repairedAt \}\)/);
+
+  // The claim is an `_id` insert — atomic in a collection that already exists.
+  // No index is created and no unique constraint is added to `members`.
+  // `id` is `toId(org)`, hoisted once so the takeover below reuses it.
+  assert.match(REPO_CODE, /const id = toId\(org\);/);
+  // The stamp is created once and RETURNED, so the holder can prove later that
+  // the claim in the ledger is still the one it inserted (`holdsClaim`).
+  assert.match(REPO_CODE, /const repairedAt = new Date\(\);/);
+  assert.match(REPO_CODE, /claims\.insertOne\(\{ _id: id, repairedAt \}\)/);
+  assert.match(REPO_CODE, /return repairedAt;/);
+  assert.match(REPO, /error\?\.code === 11000/);
+  assert.doesNotMatch(REPO_CODE, /createIndex|createIndexes|unique/i);
+
+  // A SEPARATE ledger from the default-role self-heal: sharing it would mean an
+  // organisation whose roles had already healed could never be repaired.
+  assert.match(REPO, /org-owner-repair-claims/);
+  assert.doesNotMatch(REPO_CODE, /org-default-role-seeds/);
+});
+
+// ── 8. a claim that outlived its request must not block forever ─────────────
+
+test("a claim is stale only after the full window, and unreadable is NOT stale", () => {
+  assert.equal(ORG_OWNER_REPAIR_CLAIM_STALE_MS, 10 * 60 * 1000);
+
+  const now = Date.UTC(2026, 8, 12, 12, 0, 0);
+  const ago = (ms) => new Date(now - ms);
+
+  // Still running, or only just finished.
+  for (const ms of [0, 1000, 60 * 1000, 9 * 60 * 1000, ORG_OWNER_REPAIR_CLAIM_STALE_MS - 1]) {
+    assert.equal(claimReadsAsStale(ago(ms), now), false, `${ms}ms must not be stale`);
+  }
+
+  // Old enough to be a request that died.
+  for (const ms of [ORG_OWNER_REPAIR_CLAIM_STALE_MS, 11 * 60 * 1000, 24 * 60 * 60 * 1000]) {
+    assert.equal(claimReadsAsStale(ago(ms), now), true, `${ms}ms must be stale`);
+  }
+
+  // An ISO string reads the same as a Date, because that is what a row can hold.
+  assert.equal(claimReadsAsStale(ago(11 * 60 * 1000).toISOString(), now), true);
+  assert.equal(claimReadsAsStale(ago(60 * 1000).toISOString(), now), false);
+
+  // FAILS CLOSED: anything unreadable is not stale, so a live repair can never
+  // acquire a second writer through a malformed row.
+  for (const bad of [undefined, null, "", "   ", "not-a-date", NaN, {}, []]) {
+    assert.equal(
+      claimReadsAsStale(bad, now),
+      false,
+      `${JSON.stringify(bad)} must not read as abandoned`,
+    );
+  }
+
+  // A clock that has gone backwards is not a stale claim either.
+  assert.equal(claimReadsAsStale(new Date(now + 60 * 1000), now), false);
+
+  // POSITIVE CONTROL: the function really can say yes.
+  assert.equal(claimReadsAsStale(ago(20 * 60 * 1000), now), true);
+});
+
+test("a stale claim is taken over by ONE request, and only while nobody is in the org", () => {
+  // Why this exists: the claim is inserted BEFORE the membership is written, so a
+  // process killed in between left a row that blocked the repair forever — and
+  // the only remedy would be deleting a row by hand in the database, which this
+  // project forbids. One unlucky restart would permanently block the repair for
+  // exactly the organisations this was built for.
+  const fn = REPO_CODE.slice(
+    REPO_CODE.indexOf("async function claimRepair("),
+    REPO_CODE.indexOf("async function releaseRepair("),
+  );
+  assert.ok(fn.length > 0, "claimRepair is gone");
+
+  // A fresh claim still stands the caller down, exactly as before.
+  assert.match(fn, /if \(!existing \|\| !claimReadsAsStale\(existing\.repairedAt\)\) return null/);
+
+  // The organisation must still have NOBODY in it: if the dead request got its
+  // write in after all, there is nothing to repair.
+  const staleCheck = fn.indexOf("claimReadsAsStale(");
+  const countCheck = fn.indexOf("await countOrgMemberships(id)) !== 0");
+  const del = fn.indexOf("claims.deleteOne(");
+  assert.ok(countCheck > staleCheck, "the count is not checked before the takeover");
+  assert.ok(del > countCheck, "the claim is deleted before the count is checked");
+
+  // THE RACE GUARD: the delete is conditional on the `_id` AND the stale
+  // timestamp in ONE filter, so it is a single atomic compare-and-delete. Two
+  // requests here cannot both have deletedCount 1.
+  assert.match(
+    fn,
+    /claims\.deleteOne\(\{\s*_id: id,\s*repairedAt: \{ \$lte: cutoff \},\s*\}\)/,
+    "the takeover delete is not a conditional compare-and-delete",
+  );
+  assert.match(fn, /if \(!taken\.deletedCount\) return null/);
+
+  // Retried exactly ONCE: the loser collides with the winner's FRESH claim, gets
+  // 11000 again and stands down rather than looping.
+  assert.equal(
+    (fn.match(/claims\.insertOne\(/g) ?? []).length,
+    2,
+    "the claim insert is attempted more than twice",
+  );
+  assert.doesNotMatch(fn, /while \(|for \(/, "the takeover loops");
+
+  // A real error is still thrown rather than read as "nobody else is here".
+  assert.match(fn, /if \(error\?\.code !== 11000\) throw error/);
+
+  // The claim is STILL not what authorises the write - the count is re-read under
+  // it by the caller, which is asserted in the one-writer test above.
+  assert.match(HANDLER_CODE, /const orgMemberCount = await countOrgMembers\(orgId\)/);
+});
+
+test("the role is resolved only after the count says zero, so a refusal writes nothing", () => {
+  // Resolving the owner role can SEED an organisation's default roles. If it ran
+  // before the count, an organisation that already has a member would be written
+  // to by a request that then refuses.
+  assert.match(
+    HANDLER,
+    /const qualifies = orgMemberCount === 0 && Boolean\(ownerUserId\)/,
+  );
+  const qualifies = HANDLER.indexOf("const qualifies =");
+  const heal = HANDLER.indexOf("await healDefaultRoles(orgId)");
+  const recount = HANDLER.indexOf("const orgMemberCount = await countOrgMembers(orgId)");
+
+  assert.ok(recount < qualifies, "the seed guard is computed before the count");
+  assert.ok(heal > qualifies, "roles can be seeded before the count is known");
+  assert.match(HANDLER, /if \(qualifies && !ownerRoleId\) \{/);
+});
+
+test("the counts and the role are read UNCACHED, and never through GET /api/roles", () => {
+  // `member.repo countByOrg` answers from a 15-minute Redis cache and counts
+  // `status: "active"` only; a cached zero is exactly the answer that must not
+  // be trusted by something about to write, and a SUSPENDED owner is a row that
+  // exists.
+  assert.match(REPO, /members\.countDocuments\(\{/);
+  assert.match(REPO, /type: "organization"/);
+  assert.match(REPO, /status: \{ \$ne: "deleted" \}/);
+  assert.doesNotMatch(REPO_CODE, /countByOrg|getCache|setCache|makeCacheKey/);
+
+  // `GET /api/roles` self-heals, so reading it is a write. The role is read from
+  // the collection with the same filter `getOwnerRolesByTypeOrg` uses.
+  assert.doesNotMatch(REPO_CODE, /api\/roles|fetch\(/);
+  assert.doesNotMatch(HANDLER_CODE, /api\/roles|fetch\(/);
+  assert.match(REPO_CODE, /const roles = db\.collection\("roles"\)/);
+  assert.match(REPO_CODE, /roles\.findOne</);
+  assert.match(REPO_CODE, /permissions: "\*"/);
+
+  // The ORGANISATION too. `organization.repo getById` is Redis-cached, and
+  // `status` and `email` are exactly what decide whether to repair and who the
+  // owner is — a stale copy could repair a SUSPENDED client, or point the
+  // membership at an address the organisation no longer uses.
+  assert.match(REPO_CODE, /const organizations = db\.collection\("organizations"\)/);
+  assert.match(REPO_CODE, /organizations\.findOne</);
+  assert.match(HANDLER_CODE, /await getOrgUncached\(orgId\)/);
+  assert.doesNotMatch(
+    HANDLER_CODE,
+    /_getById/,
+    "the repair reads the organisation through the CACHED repository",
+  );
+  // ... and the 404 for an organisation that is not there is preserved.
+  assert.match(HANDLER_CODE, /if \(!org\) throw new NotFoundError\(/);
+});
+
+test("the e-mail is matched case-insensitively BY COLLATION, never by a regex", () => {
+  // The reason `hasOrgOwnership` and `hasOrgInvitation` both give: an address may
+  // contain `+` or `.`, and building a pattern out of one invites an escaping
+  // bug. Same collation, same strength.
+  assert.match(REPO, /collation: \{ locale: "en", strength: 2 \}/);
+  // Against the CODE, not the prose: the doc comment names `$regex` to say why
+  // it is not used, and a check that cannot tell the two apart is a check that
+  // fails for the wrong reason.
+  assert.doesNotMatch(stripComments(REPO), /\$regex|new RegExp/);
+
+  // POSITIVE CONTROL: `hasOrgOwnership` is where that rule comes from, and it
+  // must still be spelled the same way.
+  assert.match(
+    read("src/utils/invite-actor.util.ts").slice(
+      read("src/utils/invite-actor.util.ts").indexOf("export async function hasOrgOwnership("),
+    ),
+    /collation: \{ locale: "en", strength: 2 \}/,
+  );
+});
+
+test("the repair records an audit row, after the write and before the reply", () => {
+  const write = HANDLER.indexOf("await createMemberDirect(");
+  const record = HANDLER.indexOf("await recordConsoleAction(");
+  const reply = HANDLER.search(/res\.json\(/);
+
+  assert.ok(write !== -1 && record !== -1 && reply !== -1, "nothing to compare");
+  assert.ok(write < record, "it records before it writes");
+  assert.ok(record < reply, "it replies before it records");
+
+  assert.match(HANDLER, /action: ConsoleAuditAction\.CLIENT_OWNER_REPAIRED/);
+  assert.match(HANDLER, /actor: staffId/);
+  assert.doesNotMatch(HANDLER, /actor: (req|value|payload|plan)/);
+
+  // A lost audit row cannot undo the repair.
+  const call = HANDLER.slice(record, reply);
+  assert.doesNotMatch(call, /\.catch\(|throw /);
+});
+
+test("no schema change, no migration, no backfill, no index", () => {
+  for (const [name, src] of [["controller", HANDLER_CODE], ["repository", REPO_CODE]]) {
+    assert.doesNotMatch(src, /createIndex|dropIndex/, `${name} touches an index`);
+    assert.doesNotMatch(src, /updateMany|deleteMany|drop\(/, `${name} writes in bulk`);
+  }
+
+  // The only write to a live collection is the membership itself, through the
+  // onboarding service call. The claim ledger is this feature's own collection.
+  assert.doesNotMatch(HANDLER_CODE, /insertOne|updateOne|deleteOne/);
+});
+
+test("nothing on the landing or sign-in path is touched", () => {
+  // The landing page starts working because the row it always asked for now
+  // exists, not because the read changed.
+  const member = read("src/controllers/member.controller.ts");
+  const repo = read("src/repositories/member.repo.ts");
+
+  for (const [name, src] of [["member.controller", member], ["member.repo", repo]]) {
+    assert.doesNotMatch(
+      src,
+      /org-owner-repair|repairOwnerMembership|ORG_OWNER_REPAIR/,
+      `${name} was changed by the repair`,
+    );
+  }
+});
+
+// ── 9. the handler itself, driven with stubs ────────────────────────────────
+//
+// THE INTERLEAVING the claim alone does not stop. A holder that is alive but
+// STALLED past the staleness window is not dead:
+//
+//   A claims -> A stalls >10 min -> B sees a stale claim, takes it over,
+//   re-reads the count as 0 under its own fresh claim, WRITES -> A resumes and
+//   writes too, on the strength of a count it read before any of that.
+//
+// `members` has no unique index for this shape (the declared one is
+// {org, siteId, user, type} with a partial filter, and nothing in this package
+// creates it), so nothing downstream would catch the second row. The handler
+// therefore re-reads its own claim immediately before writing. That is behaviour,
+// not wiring, so it is executed here rather than read off the source - the
+// handler's dependencies are injected for exactly this.
+
+const STAFF = "6b0c1d2e3f4a5b6c7d8e9f01";
+
+function fakeRepair(over = {}) {
+  const calls = { written: [], released: [], audited: [], order: [] };
+  const token = new Date("2026-09-12T12:00:00.000Z");
+
+  const deps = {
+    requireConsolePermission: async () => STAFF,
+    getOrgUncached: async () => ({
+      _id: ORG,
+      status: "active",
+      email: "owner@example.com",
+    }),
+    countOrgMembers: async () => 0,
+    claim: async () => token,
+    release: async (org, repairedAt) => calls.released.push([org, repairedAt]),
+    holdsClaim: async () => {
+      calls.order.push("revalidate");
+      return true;
+    },
+    findUserByEmail: async () => ({ _id: USER }),
+    confirmOwnership: async () => true,
+    findOwnerRoleId: async () => ROLE,
+    healDefaultRoles: async () => 0,
+    createMemberDirect: async (input) => {
+      calls.order.push("write");
+      calls.written.push(input);
+    },
+    recordConsoleAction: async (entry) => calls.audited.push(entry),
+    gateOn: () => true,
+    ...over,
+  };
+
+  return { calls, token, handlers: orgOwnerRepairHandlers(deps) };
+}
+
+async function run(world, params = { id: ORG }) {
+  const out = {};
+  const res = {
+    json: (value) => ((out.json = value), res),
+    status: () => res,
+  };
+
+  await world.handlers.repairOwnerMembership(
+    { params, body: {}, query: {} },
+    res,
+    (error) => (out.error = error),
+  );
+
+  return out;
+}
+
+test("the ordinary repair writes once, records once, and keeps its claim", () => {
+  return (async () => {
+    const world = fakeRepair();
+    const out = await run(world);
+
+    assert.equal(out.error, undefined, String(out.error?.message));
+    assert.equal(world.calls.written.length, 1);
+    assert.deepEqual(world.calls.written[0], {
+      userId: USER,
+      orgId: ORG,
+      roleId: ROLE,
+      app: "organization",
+      onboardingRequired: true,
+      callerId: STAFF,
+    });
+    assert.equal(world.calls.audited.length, 1);
+    assert.equal(world.calls.released.length, 0, "a successful repair keeps its claim");
+
+    // The revalidation is the LAST thing before the write.
+    assert.deepEqual(world.calls.order, ["revalidate", "write"]);
+  })();
+});
+
+test("a claim taken over while this request stalled writes NOTHING", async () => {
+  // B stole the claim and has already written. A resumes here.
+  const world = fakeRepair({ holdsClaim: async () => false });
+  const out = await run(world);
+
+  assert.equal(world.calls.written.length, 0, "it wrote a SECOND owner membership");
+  assert.equal(world.calls.audited.length, 0, "it recorded a write that did not happen");
+  assert.ok(out.error, "a stolen claim must be refused");
+  assert.equal(out.error.message, ORG_OWNER_REPAIR_CLAIM_TAKEN_REASON);
+  assert.equal(out.json, undefined);
+
+  // ... and it must NOT release: that row belongs to the other request now, and
+  // deleting it would hand a third request a free claim on a live repair.
+  assert.equal(
+    world.calls.released.length,
+    0,
+    "it released a claim that now belongs to another request",
+  );
+});
+
+test("a revalidation that cannot be read fails CLOSED", async () => {
+  const world = fakeRepair({
+    holdsClaim: async () => {
+      throw new Error("mongo is gone");
+    },
+  });
+  const out = await run(world);
+
+  assert.equal(world.calls.written.length, 0, "an unreadable claim let the write through");
+  assert.equal(out.error.message, ORG_OWNER_REPAIR_CLAIM_TAKEN_REASON);
+  assert.equal(world.calls.released.length, 0);
+});
+
+test("a refusal after the claim gives the claim back, with the stamp it inserted", async () => {
+  // Somebody is already a member: refused, and the ledger row must not be left
+  // behind claiming we repaired this organisation.
+  const world = fakeRepair({ countOrgMembers: async () => 2 });
+  const out = await run(world);
+
+  assert.equal(world.calls.written.length, 0);
+  assert.match(out.error.message, /already has 2/);
+});
+
+test("losing the claim outright refuses, writes nothing and releases nothing", async () => {
+  const world = fakeRepair({ claim: async () => null });
+  const out = await run(world);
+
+  assert.equal(world.calls.written.length, 0);
+  assert.equal(world.calls.released.length, 0);
+  assert.equal(out.error.message, ORG_OWNER_REPAIR_CLAIM_TAKEN_REASON);
+});
+
+test("the switch off refuses before the claim is even taken", async () => {
+  const world = fakeRepair({ gateOn: () => false });
+  const out = await run(world);
+
+  assert.equal(world.calls.written.length, 0);
+  assert.equal(world.calls.order.length, 0);
+  assert.equal(out.error.message, ORG_OWNER_REPAIR_OFF_REASON);
+});