fix(plugin-auth): the self-registration grant settles on the registrant's first membership (ADR-0131 D3, C8 8b-0f)

[objectstack-fleet]

Part of #24343
Part of #15212
Clause-②: no

C8 stage 8b-0f. It carries ruling Q1 A on #24377 (record 6257510973, item 1): the self-registration grant settles on the first membership. The card stays open because Q2 (stage 8b-0d) still lands on it.

What changed

The declared self-registration set (auth.audience.selfRegistrationPermissionSet) is an assignment, and ADR-0131 D3 makes an assignment an organization row. So the grant is now written with the registrant's first membership and owned by that membership's organization, under every posture. Nothing is written to sys_user_permission_set without an organization.

All runtime changes are in packages/plugins/plugin-auth/src/auth-manager.ts:

• settleSelfRegistrationGrant (user.create.after). It consumes the admission stage as before, then reads the registrant's membership.
  • The registrant holds one (under single, the reconciler bound the Default Organization a moment earlier in the same hook; or a host hook provisioned an organization first). The grant lands now, owned by that organization.
  • The registrant holds none (a wall). No grant is written. A pending claim is persisted instead.
• The pending claim is a sys_verification row. Its identifier is self-registration-grant: plus the user id, its value is the set name, and it waits 365 days.
  • sys_verification is the auth layer's existing store of one-shot claims keyed on an identifier with an expiry. It survives a restart, and it has no organization column (ADR-0131 D1 fate 1, inventory noColumn).
  • No new object, no new column, no new field.
• The first-membership seam. observeFirstMemberships is registered once per engine, from the constructor. It is a middleware on sys_member inserts, the same seam plugin-security's organization_admin auto-grant uses. Every membership writer inserts through the engine: better-auth's organization create (the creator as owner), invitation acceptance and server-side add-member, the membership reconciler, the Default Organization bootstrap, and host hooks. One seam therefore covers all of them, with no hook per path.
• settleDeferredSelfRegistrationGrant consumes the claim first (read, delete by id), then writes the grant owned by that membership's organization. A later membership finds no claim and writes no second grant. The existing by-name check also holds.
• An engine with no middleware seam could never settle a claim. There, a registrant with no organization is reported ungranted at error at sign-up, and no claim is parked.
• Helper pair, a minimal edit (named as the dispatch asks). The doc comment on derivableWriteOrganizationId no longer lists the self-registration grant among its readers, because the grant does not read it any more. Its code and authMailOrganizationArg are unchanged, and no identity-mail send site was touched.

Measured (A1–A5)

• A1, the membership paths. The writers of a user's sys_member row on this tree are: better-auth organization/create (owner) and accept-invitation, better-auth add-member, reconcileMembership (user.create.after, session.create.before, the one-time backfill), ensureDefaultOrganization's owner bind, and host user.create.after hooks. All of them write through the data engine, so the sys_member insert middleware sees each one (plugin-auth 的 databaseHooks 文档注释断言「better-auth 的适配器绕过 ObjectQL 中间件链」——已过时，今天 dataEngine 与 ql 是同一个实例 #4802's corrected mechanism, quoted in auth-manager.ts). The walled dogfood pin drives the real better-auth organization create through it. Under single, the census pin shows the sign-up still ends with exactly one grant, owned by the Default Organization.
• A2, persistence. Admission decides "self-registrant" from the request: the creation class, the bootstrap probe and the pending-invitation lookup. None of those is stored. sys_user.source separates only idp_provisioned from env_native, and sys_account.provider_id is credential for admin-created users too. So no existing user or account field marks a self-registrant, and a persisted claim is needed. sys_verification is the narrowest existing store that fits: deployment-level, durable, and with an expiry better-auth already sweeps (findVerificationValue deletes expired rows). The value column is internal, so it is read back through recoverInternalFieldsForSystemRead.
• A3, existing NULL grants. Untouched here (the ceremony is 8b-0c's). Measurement and recommendation are in the report on ADR-0131 D9 on a walled control plane: three framework writers land NULL organization_id rows on every sign-up (the self-registration grant, the verification mail, activity about org-less records) #24343.
• A4, pins. See Tests.
• A5, Clause-②. no. No spec, schema, export or route changes. AudienceConfigSchema.selfRegistrationPermissionSet describes "the permission set granted to each self-registrant", and the settings manifest and its translations say the same. None of them promises the grant at sign-up time, and the generated reference page carries only that describe. No packages/spec byte moved.

Tests (head 29b223ed3)

• New: plugin-auth/src/self-registration-grant-first-membership.test.ts, 9 cases.
  • Under single: one grant, owned by the Default Organization, no claim.
  • Walled sign-up: 0 grants, 1 claim with no organization column.
  • The first membership: exactly 1 grant, owned by that organization, and the claim is consumed.
  • A second membership: no second grant.
  • A restart: a fresh manager over the same store settles the claim.
  • No claim (an invited user): no grant. An expired claim: no grant.
  • No middleware seam: reported at error, nothing parked.
  • Two managers on one engine: the seam is registered once.
• New: dogfood/test/self-registration-grant-first-membership-walled.dogfood.test.ts, 3 cases, real stack, isolated (posture-only), open audience. The sign-up writes no grant. POST /auth/organization/create lands exactly one, owned by the new organization. A second organization lands none.
• Changed:
  • audience-posture.test.ts: the four end-to-end "grant lands" cases now run single (a tenancy service), so the reconciler binds a membership, and one of them asserts the owner.
  • find-envelope-limb-removal.test.ts: the D4 grant-by-name case binds the membership first.
  • producers-name-organization.test.ts: its two grant cases are removed. The single one is re-pinned in the new file. The walled one asserted the behaviour this stage retires (a grant with no organization), and the new walled pins assert the opposite.
• Ablation (scripts/ablation-replace.mjs, EXIT trap). The claim write was mutated back to a sign-up grant with no organization (marker ups_ABLATED_, anchor 1→0, blob debc7651→624afb11). After the rebuild, ablation-dist-preflight found the marker in dist/index.js and dist/index.mjs. The DTS step failed on TS6133 (the now-unused claim method), but the JS that the suite consumes was emitted.
  • The walled dogfood pin went red, 2 failed / 1 passed: the sign-up wrote a grant, and the organization grant read null.
  • The unit file went red, 5 failed / 4 passed.
  • Restore: blob == HEAD, git diff HEAD empty, rebuild, preflight --absent exit 0, dogfood 3/3 green.
• Suites, at 29b223ed3: @objectstack/plugin-auth test, 165 files, 3165 passed, 10 skipped; typecheck exit 0. Dogfood, after a plugin-auth rebuild: the walled pin, signup-organization-census (single) and org-create-default-team (walled), 3 files / 7 passed.
• Gates, at 29b223ed3: dispatch-gates.mjs --commands (no paths), 108 families plus the 51-row artifact roster, each exit code captured before any pipe. --ran reads: 108 derived, 108 run, 0 NOT-MEASURED.
  • Fixed on the way: check-tenant-audit-census (the riders below), check:engine-double-contract (ledger row), and check:where-matcher (the new double now refuses WHERE combinators).
  • Roster rows that need a PR context exited 2 (NOT WIRED) locally: check-closing-target-claim, check-single-claim-paths, and check-governed-queue-guard (no event payload, exit 1). CI's reading counts for those. check-partof-closing-keyword, run with this body as PR_BODY, exits 0.

Riders

• content/docs/permissions/tenant-audit-census.mdx and docs/audits/2026-08-tenant-audit-write-call-sites.counts.md. These were regenerated (node scripts/tenant-audit-census.mjs --write) and the page's prose figures updated, because check-tenant-audit-census holds them to the census and this stage moves the write-call-site population from 229 to 231. The three plugin-auth writes state { context: { isSystem: true } } at the call, so they count as elevated. The "cite 2 / N" provable-yield figure stays 2.
• scripts/engine-double-contract.pinned.json: one row for the new test's delete double (check-engine-double-contract --write).

Acceptance notes

• The claim waits 365 days. A registrant who first joins an organization later holds only the deployment's baseline. Cloud's report (cloud#3051) shows its self-registration set is also its isDefault baseline, so nothing changes there.
• Under single with membershipPolicy: 'invite-only', a self-registrant gets no membership at sign-up, so the grant now waits for the first membership there too, as the ruling's "under every posture" says. Under auto (the default), single is unchanged.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/plugin-auth, touching 13 documentable anchor(s).

12 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/data-modeling/objects.mdx (via sys_user_permission_set (literal, a string literal in landSelfRegistrationGrant; a string literal in settleSelfRegistrationGrant))
• content/docs/deployment/environment-variables.mdx (via sys_member (literal, a string literal in observeFirstMemberships; a string literal in settleSelfRegistrationGrant), sys_user_permission_set (literal, a string literal in landSelfRegistrationGrant; a string literal in settleSelfRegistrationGrant))
• content/docs/deployment/tenancy-modes.mdx (via sys_member (literal, a string literal in observeFirstMemberships; a string literal in settleSelfRegistrationGrant))
• content/docs/kernel/contracts/auth-service.mdx (via AuthManager (symbol, a top-level class))
• content/docs/kernel/services-checklist.mdx (via AuthManager (symbol, a top-level class))
• content/docs/permissions/authentication.mdx (via AuthManager (symbol, a top-level class), sys_member (literal, a string literal in observeFirstMemberships; a string literal in settleSelfRegistrationGrant), sys_verification (literal, a string literal in persistSelfRegistrationGrantClaim; a string literal in settleDeferredSelfRegistrationGrant))
• content/docs/permissions/authorization.mdx (via sys_user_permission_set (literal, a string literal in landSelfRegistrationGrant; a string literal in settleSelfRegistrationGrant), sys_verification (literal, a string literal in persistSelfRegistrationGrantClaim; a string literal in settleDeferredSelfRegistrationGrant))
• content/docs/permissions/delegated-administration.mdx (via sys_member (literal, a string literal in observeFirstMemberships; a string literal in settleSelfRegistrationGrant), sys_user_permission_set (literal, a string literal in landSelfRegistrationGrant; a string literal in settleSelfRegistrationGrant))
• content/docs/permissions/permission-sets.mdx (via sys_member (literal, a string literal in observeFirstMemberships; a string literal in settleSelfRegistrationGrant), sys_user_permission_set (literal, a string literal in landSelfRegistrationGrant; a string literal in settleSelfRegistrationGrant))
• content/docs/permissions/positions.mdx (via sys_member (literal, a string literal in observeFirstMemberships; a string literal in settleSelfRegistrationGrant))
• content/docs/permissions/system-context.mdx (via sys_member (literal, a string literal in observeFirstMemberships; a string literal in settleSelfRegistrationGrant), sys_user_permission_set (literal, a string literal in landSelfRegistrationGrant; a string literal in settleSelfRegistrationGrant))
• content/docs/ui/setup-app.mdx (via sys_verification (literal, a string literal in persistSelfRegistrationGrantClaim; a string literal in settleDeferredSelfRegistrationGrant))

⛔ 10 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/implementation-status.mdx (via sys_member (literal, a string literal in observeFirstMemberships; a string literal in settleSelfRegistrationGrant), sys_user_permission_set (literal, a string literal in landSelfRegistrationGrant; a string literal in settleSelfRegistrationGrant))
• content/docs/releases/v13.mdx (via sys_user_permission_set (literal, a string literal in landSelfRegistrationGrant; a string literal in settleSelfRegistrationGrant))
• content/docs/releases/v14.mdx (via sys_user_permission_set (literal, a string literal in landSelfRegistrationGrant; a string literal in settleSelfRegistrationGrant))
• content/docs/releases/v16.mdx (via sys_member (literal, a string literal in observeFirstMemberships; a string literal in settleSelfRegistrationGrant), sys_user_permission_set (literal, a string literal in landSelfRegistrationGrant; a string literal in settleSelfRegistrationGrant))
• content/docs/releases/v17/17-0.mdx (via sys_member (literal, a string literal in observeFirstMemberships; a string literal in settleSelfRegistrationGrant))
• content/docs/releases/v17/17-1.mdx (via sys_member (literal, a string literal in observeFirstMemberships; a string literal in settleSelfRegistrationGrant), sys_user_permission_set (literal, a string literal in landSelfRegistrationGrant; a string literal in settleSelfRegistrationGrant))
• content/docs/releases/v17/17-3.mdx (via sys_member (literal, a string literal in observeFirstMemberships; a string literal in settleSelfRegistrationGrant))
• content/docs/releases/v17/17-5.mdx (via sys_verification (literal, a string literal in persistSelfRegistrationGrantClaim; a string literal in settleDeferredSelfRegistrationGrant))
• content/docs/releases/v17/17-6.mdx (via sys_member (literal, a string literal in observeFirstMemberships; a string literal in settleSelfRegistrationGrant))
• content/docs/releases/v17/17-7.mdx (via sys_verification (literal, a string literal in persistSelfRegistrationGrantClaim; a string literal in settleDeferredSelfRegistrationGrant))

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.

What this run could not see

• 1 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 54 of 206 client-bound route-ledger rows — the other 152 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 152: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 97 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 16 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json fa26308bb0332152a359335be27ba1a7f18574de → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 0beeeb170030eacc3869aca88930a60c96fc54fa — the merge of head 29b223ed33d3a3e7181d9c3fb87e75e7392d661d into base fa26308bb0332152a359335be27ba1a7f18574de, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 0beeeb170030eacc3869aca88930a60c96fc54fa && git checkout 0beeeb170030eacc3869aca88930a60c96fc54fa
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin fa26308bb0332152a359335be27ba1a7f18574de 29b223ed33d3a3e7181d9c3fb87e75e7392d661d && git checkout -B drift-repro fa26308bb0332152a359335be27ba1a7f18574de && git merge --no-ff 29b223ed33d3a3e7181d9c3fb87e75e7392d661d

node scripts/docs-audit/affected-docs.mjs --json fa26308bb0332152a359335be27ba1a7f18574de

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs fa26308bb0332152a359335be27ba1a7f18574de → pass the list as
args.docs, on the commit named under Which tree this was computed on.