finding: three source comments claim `teamId` on `organization/add-member` defaults to the caller's active team — better-auth 1.7.1 has no such fallback

[os-zhuang]

Found while documenting POST /organization/add-member for #10050. Not ridden into that PR — it is a source-comment defect in two other packages, and the docs PR is content/docs only.

The claim

packages/platform-objects/src/identity/sys-member.object.ts (the add_member action):

// organizationId/teamId default to the caller's active org/team when
// omitted, so we leave them as optional params.

The same sentence is repeated, as the authority for the mount's behaviour, in:

• packages/plugins/plugin-auth/src/organization-add-member.ts — module header, organizationId default section: "the behaviour the sys_member action metadata documents ("organizationId/teamId default to the caller's active org/team when omitted")"
• packages/plugins/plugin-auth/src/auth-plugin.ts — the comment above the mount cites the same action metadata.

What the vendor actually does

Measured on the installed better-auth 1.7.1, dist/plugins/organization/routes/crud-members.mjs, inside addMember's handler:

const orgId = ctx.body.organizationId || session?.session.activeOrganizationId;
if (!orgId) throw APIError.from("BAD_REQUEST", ORGANIZATION_ERROR_CODES.NO_ACTIVE_ORGANIZATION);
const teamId = "teamId" in ctx.body ? ctx.body.teamId : void 0;

The organizationId half is correct — it falls back to session.activeOrganizationId, which is why the mount forwards request headers and why the omitted-org case yields 400 NO_ACTIVE_ORGANIZATION.

The teamId half is wrong. There is no activeTeamId fallback anywhere in that handler: an omitted teamId stays undefined, and the member is created with no team association at all. Nothing later in the handler re-resolves it — the if (teamId) branches (team lookup, TEAM_NOT_FOUND, maximumMembersPerTeam) are all simply skipped.

Why it is worth fixing rather than shrugging at

The sentence is not decoration — it is cited by the mount as the justification for forwarding headers, so the next author reading organization-add-member.ts inherits a false premise about what header forwarding buys. It also reads as a promise the action deliberately declines to make: the add_member action's params list does not include teamId at all, so the toolbar never sends it and the claim has never been exercised.

No behaviour is wrong today — this is a wrong citation, not a bug. The teamId forwarding itself is correct (pass it and it works; omit it and you get no team, which is what the code does).

Suggested fix

Correct the sentence in all three sites to say that organizationId falls back to the caller's active organization and teamId has no fallback. Worth a pin: the docs written for #10050 now state the asymmetry, so a future vendor bump that adds an active-team fallback would put docs and vendor out of sync with nothing watching.

Refs

#10050 (the docs card this surfaced under) · #9941 / PR #10049 (the mount) · better-auth 1.7.1

[os-zhuang]

Triage (first-touch grading): promoted finding → pm:queue, domain:services via the cross-domain single-PR exception (2 of 3 sites in packages/plugins/plugin-auth, 1 in packages/platform-objects — the origin sentence; one small PR, claim must declare the full three-file surface and clear the engine lane's in-flight claims on sys-member.object.ts).

Type Task — no runtime behavior is wrong; three source comments assert a vendor fallback better-auth 1.7.1 does not implement, and the mount cites them as authority. Scope: correct the sentence at all three sites (organizationId falls back to active org; teamId has no fallback), plus the suggested pin against a future vendor bump adding an active-team fallback (docs from #10050 now state the asymmetry; the pin is what watches it).

---

Generated by Claude Code

[os-warren]

Claim: PM domain:services 派发

• Session: 0f14f70b-575c-5f2b-a235-4000a55db042
• Branch: claude/issue-10532-add-member-teamid-no-fallback
• Worktree: ../objectstack-10532（per-repo；⛔ 不在共享主检出上编辑；⛔ 不用 git stash）
• File surface（按 triage 的跨域单 PR 例外，三处必须一次改完并在此声明）：
  1. packages/platform-objects/src/identity/sys-member.object.ts —— 源句
  2. packages/plugins/plugin-auth/src/organization-add-member.ts —— 模块头引用它作为权威
  3. packages/plugins/plugin-auth/src/auth-plugin.ts —— 挂载点上方的注释引用同一句
  • 承载 pin 的同包测试。⛔ 零 packages/spec 所有权；⛔ 不碰 content/docs/releases/。
• Container & model: claude-opus-5
• Clause-②: no —— 卡面自己写明「今天没有任何行为是错的」，改的是三处源码注释的事实陈述加一条 pin，不动挂载、不动接受/拒绝集、不扩公开面。
  ⚠️ 若你在实现中发现它其实改到了任何对外可观测的行为 —— 停下并说出来，不要自行降级处理。

文件占用（已替你查过，可推翻）

triage 要求「clear the engine lane's in-flight claims on sys-member.object.ts」。我查了当前全部 25 张 pm:dispatched 卡与 13 个开着的 PR：没有一张/一个占用 sys-member.object.ts（engine 车道在飞的是 #10551 registry mock、#10462 publishPackageDrafts、#7826 sys_session——都不是这个文件）。⚠️ 这是我在 GitHub 层面的读数，不是文件锁。建分支后请自己再跑一次 node scripts/check-single-claim-paths.mjs（或等价核对），若发现冲突占用就停下上报，不要硬上。

实现要求

1. 先自己复测供应商行为，不要采信卡面。卡面给的读数是 better-auth 1.7.1 dist/plugins/organization/routes/crud-members.mjs 里 addMember 的处理函数：organizationId 回落到 session.activeOrganizationId，而 teamId 是 "teamId" in ctx.body ? ctx.body.teamId : void 0 —— 无回落。
   • 在你的树上确认安装的版本号与该文件内容。⚠️ 若安装的不是 1.7.1，以你测到的为准并在报告里说明卡面与实测的差异。
   • 这是一次零命中式判断（「找不到 activeTeamId 回落」）—— 零结果不是发现，除非邻近的已知存在词证明搜索本身有效：用同一次 grep 证明 activeOrganizationId 能在同一文件命中。
2. 三处都要改，而且要改成同一句话。半途而废（只改源句、留下两处引用）等于把假前提留在被引用的位置上——那正是本卡存在的原因。
3. 那条 pin 是本卡的实质交付，不是附赠：卡面点名了它要看住什么 —— 未来某次 vendor bump 加上 active-team 回落时，docs（docs: the newly mounted POST /organization/add-member is undocumented — and it is the ONLY multi-org path to attach an existing user #10050 已写明这个不对称）与 vendor 会失步而无人看守。
   • pin 必须从安装的 vendor 产物读出事实（例如断言 addMember 处理函数里不存在 activeTeam 回落），而不是断言我们自己的注释文本——断言注释只会证明「我们写了我们写的东西」。
   • ⛔ 禁止 const 提升式规避：把字面量提到 const 再传标识符、好让只读字面量的计数器变绿而 wire 毫无变化，是 2026-08-21 维护者裁决点名的禁招。这里的同类形态是「把 vendor 断言写成对我们自己常量的断言」。
   • pin 必须双向：既要在今天的 vendor 上绿，也要能证明它在「vendor 真加了回落」时会红。做一次消融（临时把被读的 vendor 事实改成有回落的形态）来证明这一点，预测签名先写下来再跑，git hash-object 证明恢复逐字节一致。
4. add_member action 的 params 里本就没有 teamId（卡面所述），所以这条声明从未被行使过——如实说明它是「错误引用」而非「已在生产中误导过用户」。
5. 门禁并集在最终提交之后、干净工作树上由 node scripts/pm/dispatch-gates.mjs 不带路径参数推导后跑；退出码在任何管道之前捕获。
   ⚠️ class [finding] Every PM dispatch list is short by the same ~5 changeset-triggered gate families — they are path-derivable, but the changeset does not exist yet when the list is derived #10309：推导出的并集已知会短。改到 plugin-auth / platform-objects 时请显式补跑 check:route-envelope 与 check:dispatcher-error-vocabulary，并在报告里说明推导是否点名了它们。
6. @objectstack/plugin-auth 的 TEST_DEBT（[finding] @objectstack/plugin-auth's TEST_DEBT records 109 where tsc now reports 98 — an 11-error surplus opened by PR #10614 #10615，记 109）⛔ 不要动、不要跑 --lower。

⚠️ CI 上一个不是你的红

check-query-options-erasure-ratchet 在 packages/spec/src/migrations/registry.ts:0:0 — Parsing error: Maximum call stack size exceeded 上可能红。这是 #10449，与你的 diff 无关。⛔ 不要为它改代码；重跑不超过一次；仍红就在报告里注明并指向 #10449。

---

Generated by Claude Code