fix(plugin-auth): adopt the existing membership when accepting an invitation instead of colliding on the unique index

[os-help]

Fixes #7725

The defect

POST /api/v1/auth/organization/accept-invitation returned HTTP 500 with an empty body and left the sys_invitation row pending forever. On a single-organization deployment the documented flow — invite a fresh email, invitee signs up through the link, invitee accepts — could never complete, and the invitation was unrecoverable through the UI (re-inviting an address that is already a member is refused too).

Premise re-verified on origin/main by symbol, and it holds exactly as filed. Two individually-correct platform decisions collide:

• every user is auto-bound to the deployment's default organization at sign-up, by the membership reconciler (reconcile-membership.ts, composed into user.create.after, ADR-0093 D1/D2);
• sys_member declares { organization_id, user_id } unique.

better-auth 1.7.0-rc.2's built-in accept-invitation route (plugins/organization/routes/crud-invites.mjs) assumes an invitee is never already a member: after flipping the invitation to accepted it calls adapter.createMember(...) unconditionally, inside a runWithTransaction whose .catch sets the invitation back to pending and rethrows. The invitee's auto-bound row made the insert fail, and the rollback erased the only evidence that acceptance had been attempted. The reconciler yields to a pre-existing row; better-auth's insert does not go through that seam.

The seam, and why this one

The three seams the framework already owns on this route were each evaluated against better-auth's actual code and rejected — the reasoning is recorded in full in the new module's header, in short:

• organizationHooks.beforeAcceptInvitation fires before createMember and can only throw or mutate. The one mutation that would let the insert succeed is deleting the pre-existing row, which destroys the membership's created_at and history, opens a window in which the invitee belongs to nothing, and reaches into sys_member's deleteBehavior — another card's decision surface (admin-lifecycle: remove-user is non-atomic and can never succeed — 409 leaks as a bodyless HTTP 500, credential rows deleted without rollback #7724).
• hooks.before (the global route-boundary middleware in auth-manager.ts) has the endpoint ctx, but ctx.context is the shared AuthContext singleton (to-auth-endpoints.mjs passes the awaited instance-wide context), so per-request state parked there leaks across concurrent requests — an adapter swap most of all.
• Owning the "already a member" branch at the route boundary would duplicate better-auth's recipient / expiry / status / membership-limit / email-verification checks. Duplicated security checks are where bypasses live.

The fix therefore lands in the better-auth to ObjectQL adapter's create for sys_member — the layer that already reconciles better-auth's model with the platform's object (model and field names, dates, identifier normalisation). It is stated as the platform's own rule rather than as leniency: the declared unique pair IS the identity of a membership, so a create naming an existing pair is that membership.

Blast radius measured against better-auth 1.7.0-rc.2 rather than assumed — accept-invitation is the only member create that can reach an existing pair:

• POST /organization/add-member pre-checks and refuses first (findMemberByEmail produces USER_IS_ALREADY_A_MEMBER_OF_THIS_ORGANIZATION, a 400);
• POST /organization/create-organization mints a fresh organization id, so no pair can pre-exist;
• the reconciler and its backfill write through engine.insert directly, not through this adapter, and already yield.

Role and attribution on adoption

Not throwing is the smaller half. Adoption writes the invitation's role onto the adopted row, so an invitation's intent is not silently replaced by the reconciler's default member — accepting an admin invitation makes you an admin even if you signed up first. A grade-flat move is applied too (member to delegated_admin), since dropping it is exactly the "silently keep the default" failure.

One deliberate exception, pinned in both the unit and the end-to-end suites: adoption never lowers a grade. If the existing membership already outranks the invitation's role, the existing role is kept. Acceptance is an admission instrument — invitation-role-cap.ts states the same posture from the issuance side — while demotion has its own governed route, POST /organization/update-member-role, which is where last-admin-guard.ts stands. Without this exception, inviting an organization's sole owner as a member and having them accept would have demoted them past that guard, taking the organization's last owner with it and reporting success.

Attribution needs nothing extra, and that is deliberate: the adoption writes through the same withSystemContext-wrapped engine as every other adapter write, whose update carries attributedUserId (#4586) — here the invitee who accepted — and sys_member is trackHistory: true, so the adoption lands in history attributed to the acceptor. created_at is not rewritten: the membership really did begin at sign-up.

Verification

New end-to-end suite drives the real better-auth pipeline through a real AuthManager (organization plugin, the framework's beforeCreateInvitation role cap, the reconciler on user.create.after, the ObjectQL adapter). The engine double enforces sys_member's declared unique index and throws in the driver's own words — without that, the defect is invisible on an in-memory fake and the whole suite would be theatre.

Ablation (revert only the adapter wiring, keep the module and every test), direction predicted before running:

test	predicted	observed
acceptance returns 2xx / invitation accepted / exactly one membership	red	red, expected 500 to be 200
adopted row carries the invitation's role	red	red, expected 500 to be 200
adoption never demotes	red (same collision, not the demotion)	red, expected 500 to be 200
invitee NOT yet a member still gets a membership created	green	green
delegated_admin can invite a member	green	green
delegated_admin cannot invite an admin (403, ADR-0090 D12, zero orphan rows)	green	green
12 unit pins on the adoption decision	green (module untouched)	green

The ablated stack trace is the reported failure verbatim: insert into sys_member ... UNIQUE constraint failed: sys_member.organization_id, sys_member.user_id, through createMember at crud-invites.mjs:324, surfacing as [AuthManager] better-auth returned error: 500 with an empty body.

Suites, all on top of a merged origin/main and a fully built workspace:

• @objectstack/plugin-auth — 43 files / 1039 tests green after the merge described below. That total is exactly the union of the two parents: 1015 (this branch) + 18 (session-tombstone.test.ts, new from fix(plugin-auth): tombstone interactive session revocations instead of deleting the row #7825) + 6 (managed-extension-fields.test.ts, grown 6 to 12 by test(plugin-auth): fail the D7 collision guard on unmapped better-auth-managed objects #7822). The merged test-file set is the union of both parents' sets with nothing dropped — 40 shared + 2 from this branch + 1 from main. typecheck green.
• @objectstack/rest (the HTTP surface the auth routes mount on) — 91 files / 1462 tests green.
• The two dogfood suites that drive the organization routes over a real stack — membership-actor-attribution.dogfood.test.ts (which exercises the real accept-invitation) and delegated-admin-invite.dogfood.test.ts — 10 tests green.
• Downstream consumer sweep green: pnpm --filter '...@objectstack/plugin-auth' typecheck, the prefix direction (the packages that DEPEND ON plugin-auth, not its dependencies). 14 consumers ran a typecheck script, all Done; @objectstack/hono and @objectstack/cloud-connection are in the set but declare no typecheck script.
• Gates for this surface: check:nul-bytes OK, check:engine-double-contract OK. The latter earned its keep — it caught the new engine double pinning delete but not update, and update is the verb adoption actually writes through. Fixed in 530b760e4 rather than baselined.

Merge with main — coexistence with #7825

The merge queue ejected this PR with MERGE_CONFLICT after #7825 (session tombstoning) landed as 3f296bf. Resolved by merging origin/main into the branch — no rebase, no force-push.

Exactly one file conflicted, and only in its import block: packages/plugins/plugin-auth/src/objectql-adapter.ts, where #7825's session-tombstone imports and this PR's adoptExistingMembership import landed on the same line. Resolved as the union of both imports; neither side was taken wholesale. There was no semantic reconciliation to make, because the two features hook disjoint adapter methods — adoption on create, tombstoning on findOne / findMany / delete / deleteMany. index.ts auto-merged carrying both exports.

A clean merge is not a working merge, and both features hook the same adapter dispatch, so coexistence was proved rather than assumed. Both end-to-end suites drive the same merged adapter through AuthManager calling createObjectQLAdapterFactory, so an ablation on the merged file is visible to both:

ablation applied to the merged adapter	adoption suites (12 unit + 6 e2e)	#7825 session-tombstone.test.ts (18)
none — the state pushed here	18 green	18 green
adoption seam removed from create	3 red (the e2e cases), 15 green	18 green
reconcileSessionDelete removed from delete	18 green	4 red, 14 green

Each feature's suite goes red only under its own ablation, so neither is passing vacuously on the merged dispatch, and both features still fire.

Also re-run after the merge: pnpm --filter @objectstack/plugin-auth typecheck green, the prefix-direction consumer sweep green across all 16 selected packages, check:engine-double-contract OK (161 pinned / 133 DEBT / 2 exempt) and check:nul-bytes OK. Rebuilding packages/spec on the merged sources produced no artifact drift, so the merged generated files reproduce exactly. The @objectstack/rest and dogfood numbers above are from the pre-merge round and were not re-run; nothing in the merge touches that surface.

main has since advanced two further commits (3bb9340, bf8fd8a — docs, QA checklists, and a packages/spec doc comment). git merge-tree against them reports no conflict, and the merge queue rebuilds onto live main regardless, so they are deliberately not chased here.

Scope

Both family non-goals held — confirmed by the diff's file list, which touches neither:

• packages/platform-objects/src/identity/sys-member.object.ts (FK / deleteBehavior / indexes) is not in the diff — that stays admin-lifecycle: remove-user is non-atomic and can never succeed — 409 leaks as a bodyless HTTP 500, credential rows deleted without rollback #7724's decision surface. The unique index is honoured here, not changed.
• The shared better-auth to REST error mapping (packages/rest/src/rest-server.ts) is not in the diff.

Bodyless-500 residue, for #7724's benefit: the success path is fixed, but the mapping is not, and a fault on this path still surfaces bodyless. Anything that makes better-auth's accept-invitation transaction throw a non-APIError — an engine outage, a driver error, a constraint this fix does not cover — still reaches the client as a 500 with an empty body and still rolls the invitation back to pending. That is the shared mapping class, deliberately left alone here.

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 11, 2026 8:48pm

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/plugin-auth.

8 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/deployment/cli.mdx (via @objectstack/plugin-auth)
• content/docs/deployment/production-readiness.mdx (via @objectstack/plugin-auth)
• content/docs/kernel/contracts/cache-service.mdx (via @objectstack/plugin-auth)
• content/docs/kernel/services-checklist.mdx (via @objectstack/plugin-auth)
• content/docs/permissions/authentication.mdx (via @objectstack/plugin-auth)
• content/docs/permissions/sso.mdx (via @objectstack/plugin-auth)
• content/docs/plugins/index.mdx (via @objectstack/plugin-auth)
• content/docs/plugins/packages.mdx (via @objectstack/plugin-auth)

⛔ 2 release-owned page(s) also reference the affected code. These are read-only:

• content/docs/releases/implementation-status.mdx (via @objectstack/plugin-auth)
• content/docs/releases/v9.mdx (via @objectstack/plugin-auth)

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.

[github-actions]

⛔ merge queue 构建失败 — 先分诊，再决定要不要重排

队列构建 31506352658 红了。队列跑的是全量套件（PR 侧 CI 只跑 affected 子集），
所以失败的测试可能在本 PR 没碰过的包里 —— 那不是重排能修的。每次盲目重排都会让排在后面的所有 PR 重建一轮。

失败的 job（日志抽取，best effort）：

• Test Core (1/3) — 失败步骤: Run this shard's tests

  �[41m�[1m FAIL �[22m�[49m src/data/api-methods-batch-conformance.test.ts�[2m > �[22mapiMethods conformance — single-record writes imply batch (#3026)�[2m > �[22mgrants bulk wherever it grants create /
  

历史信号：

• 本 PR 过去 24h 无队列失败记录（首次）。
• 过去 24h 队列共有 10 个失败构建（不含本次）。

分诊清单：

1. 失败测试在本 PR 改动的包里 → 真回归，修 PR。
2. 失败测试与本 PR 无关 → 在其他 PR 的同类评论里搜同名测试；出现过 ⇒ flaky 实锤，开 issue 修/隔离那条测试。修好前重排只会再烧一轮全队列。
3. 两者都不是 → 可能与同组 PR 语义冲突；等前面的 PR 落地或失败出队后再重排一次即可，不要连续重排。

---

Generated by Claude Code · merge-queue-triage workflow (#4859)

[github-actions]

⛔ merge queue 构建失败 — 先分诊，再决定要不要重排

队列构建 31506300231 红了。队列跑的是全量套件（PR 侧 CI 只跑 affected 子集），
所以失败的测试可能在本 PR 没碰过的包里 —— 那不是重排能修的。每次盲目重排都会让排在后面的所有 PR 重建一轮。

失败的 job（日志抽取，best effort）：

• Test Core (1/3) — 失败步骤: Run this shard's tests

  �[41m�[1m FAIL �[22m�[49m src/data/api-methods-batch-conformance.test.ts�[2m > �[22mapiMethods conformance — single-record writes imply batch (#3026)�[2m > �[22mgrants bulk wherever it grants create /
  

历史信号：

• ⚠️ 本 PR 过去 24h 已在队列失败 1 次（不含本次）。 内容未变而反复失败 ⇒ 高度怀疑 flaky 测试或与同组 PR 的语义冲突，重排不解决。
• 过去 24h 队列共有 11 个失败构建（不含本次）。

分诊清单：

1. 失败测试在本 PR 改动的包里 → 真回归，修 PR。
2. 失败测试与本 PR 无关 → 在其他 PR 的同类评论里搜同名测试；出现过 ⇒ flaky 实锤，开 issue 修/隔离那条测试。修好前重排只会再烧一轮全队列。
3. 两者都不是 → 可能与同组 PR 语义冲突；等前面的 PR 落地或失败出队后再重排一次即可，不要连续重排。

---

Generated by Claude Code · merge-queue-triage workflow (#4859)

[github-actions]

⛔ merge queue 构建失败 — 先分诊，再决定要不要重排

队列构建 31507847145 红了。队列跑的是全量套件（PR 侧 CI 只跑 affected 子集），
所以失败的测试可能在本 PR 没碰过的包里 —— 那不是重排能修的。每次盲目重排都会让排在后面的所有 PR 重建一轮。

失败的 job（日志抽取，best effort）：

• Test Core — 失败步骤: Verify test shard results（日志不可读，点进 job 看）

历史信号：

• ⚠️ 本 PR 过去 24h 已在队列失败 2 次（不含本次）。 内容未变而反复失败 ⇒ 高度怀疑 flaky 测试或与同组 PR 的语义冲突，重排不解决。
• 过去 24h 队列共有 16 个失败构建（不含本次）。

分诊清单：

1. 失败测试在本 PR 改动的包里 → 真回归，修 PR。
2. 失败测试与本 PR 无关 → 在其他 PR 的同类评论里搜同名测试；出现过 ⇒ flaky 实锤，开 issue 修/隔离那条测试。修好前重排只会再烧一轮全队列。
3. 两者都不是 → 可能与同组 PR 语义冲突；等前面的 PR 落地或失败出队后再重排一次即可，不要连续重排。

---

Generated by Claude Code · merge-queue-triage workflow (#4859)

[github-actions]

⛔ merge queue 构建失败 — 先分诊，再决定要不要重排

队列构建 31511205705 红了。队列跑的是全量套件（PR 侧 CI 只跑 affected 子集），
所以失败的测试可能在本 PR 没碰过的包里 —— 那不是重排能修的。每次盲目重排都会让排在后面的所有 PR 重建一轮。

失败的 job（日志抽取，best effort）：

• Test Core (1/3) — 失败步骤: Run this shard's tests

  �[41m�[1m FAIL �[22m�[49m src/data/api-methods-batch-conformance.test.ts�[2m > �[22mapiMethods conformance — single-record writes imply batch (#3026)�[2m > �[22mgrants bulk wherever it grants create /
  

历史信号：

• ⚠️ 本 PR 过去 24h 已在队列失败 3 次（不含本次）。 内容未变而反复失败 ⇒ 高度怀疑 flaky 测试或与同组 PR 的语义冲突，重排不解决。
• 过去 24h 队列共有 23 个失败构建（不含本次）。

分诊清单：

1. 失败测试在本 PR 改动的包里 → 真回归，修 PR。
2. 失败测试与本 PR 无关 → 在其他 PR 的同类评论里搜同名测试；出现过 ⇒ flaky 实锤，开 issue 修/隔离那条测试。修好前重排只会再烧一轮全队列。
3. 两者都不是 → 可能与同组 PR 语义冲突；等前面的 PR 落地或失败出队后再重排一次即可，不要连续重排。

---

Generated by Claude Code · merge-queue-triage workflow (#4859)

[huangyiirene]

Ejected from the merge queue: MERGE_CONFLICT (github-merge-queue[bot], ~20:35Z). Not a flake, not a CI failure — diagnosed and being resolved. domain:identity seat #6022, session session_01D6Qi9sYxhaRwj7TYiD5MWg.

What happened

This is the collision the seat's hot-file serial queue predicted, resolved in the opposite order from the one recorded. Both this PR and #7825 (#7732, session tombstoning) touch packages/plugins/plugin-auth/src/objectql-adapter.ts. #7825 reached the front of the queue first and landed as 3f296bf; this PR's base is still 098b629, so it now conflicts.

Recorded plainly because the serial-queue note had the order as #7796 → #7825 and reality went the other way. The queue arbitrated, which is correct — ⛔ PM does not hand-order the queue. The cost is one merge resolution here.

Conflict scope, measured read-only (git merge-tree against origin/main @ 3f296bf)

Exactly one file, exactly one hunk — and it is an import-block collision, nothing deeper:

Auto-merging  packages/plugins/plugin-auth/src/index.ts          ← clean
CONFLICT      packages/plugins/plugin-auth/src/objectql-adapter.ts

<<<<<<< origin/main
import { filterRevokedSessionRows, hideRevokedSessionRow, reconcileSessionDelete } from './session-tombstone.js';
=======
import { adoptExistingMembership } from './adopt-membership.js';
>>>>>>> pr-7796

Both sides are additive and disjoint in intent: #7825 owns delete on sys_session, this PR owns create on sys_member. The resolution is a union of the two import statements.

⛔ But a clean merge is not a working merge

The rest of the file auto-merged, and that is exactly the situation AGENTS.md §10 warns about. Both changes hook the same adapter dispatch, so their coexistence has to be demonstrated, not inferred from git exiting 0:

• create / sys_member (adoption) and delete / sys_session (tombstone reconcile) must both still fire after the merge;
• ⛔ do not mechanically take either side of the hunk — taking one drops the other's feature entirely, and both halves are already reviewed and ACCEPTed;
• the full @objectstack/plugin-auth suite is the gate, not the two new suites alone.

Re-queued once the resolution is pushed and verified. Nothing about this PR's review verdict changes — it stays ACCEPTed; this is a rebase-class patch round, not rework.

---

Generated by Claude Code