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

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 (#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 #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](https://claude.ai/code/session_01KYBqeqPDxig2tPYhHQxYNX)_

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: objectstack-fleet[bot]

.changeset/24343-8b0f-grant-on-first-membership.md

@@ -0,0 +1,14 @@
+---
+"@objectstack/plugin-auth": patch
+---
+
+fix(plugin-auth): the self-registration grant settles on the registrant's first membership, owned by that organization (ADR-0131 D3)
+
+Clause-②: no
+
+The declared self-registration permission set (`auth.audience.selfRegistrationPermissionSet`) is an assignment, and an assignment is an organization row (ADR-0131 D3). It is now written with the registrant's first membership and owned by that membership's organization, under every posture. It is never written without an organization.
+
+- **`single`: unchanged.** The membership reconciler binds the Default Organization in the same `user.create.after` hook, so a sign-up still ends with one grant, owned by the Default Organization.
+- **A wall (`group`, `isolated`).** A self-registrant belongs to no organization at sign-up, so the sign-up writes no `sys_user_permission_set` row. It used to write one with no organization. The grant is held as a pending claim in `sys_verification`, which is deployment-level and survives a restart. The first `sys_member` row written for the user lands exactly one grant, owned by that organization. That row can come from creating an organization (the creator becomes its owner), accepting an invitation, being added by an administrator, or any other membership writer. A later membership writes no second grant.
+- **The claim waits 365 days.** A registrant who first joins an organization after that holds only the deployment's baseline. An engine with no middleware seam cannot settle a claim, so there a registrant with no organization is reported ungranted at `error` at sign-up instead.
+- Grants already written without an organization by earlier walled sign-ups are not touched here.

content/docs/permissions/tenant-audit-census.mdx

@@ -83,7 +83,7 @@ what moved this page's population from 225 to 227; nothing about the two sites
 changed, only whether this instrument could see them.
 
 **The expensive failure direction is a keyword.** Sites whose receiver the author
-typed `any` have no type to read, and there are 38 of them — just under a fifth
+typed `any` have no type to read, and there are 40 of them — just under a fifth
 of the population, concentrated in exactly the seed and bootstrap paths this
 control exists for. Scoring an unreadable receiver as "not an engine" would have
 dropped every one of them silently, with a clean exit and a smaller number that
@@ -122,7 +122,7 @@ are reported as `undecidable` rather than assumed either way.
 
 The same holds twice over for the context. An options argument spelled as a
 literal can be read; one spelled `options`, `{ ...opts }`, or handed through a
-forwarding shim cannot, and **53 of the 229 sites are spelled that way**. A
+forwarding shim cannot, and **52 of the 231 sites are spelled that way**. A
 context resolved from an inline literal or a local `const` can be tested for
 `isSystem`; one arriving from a helper call cannot.
 
@@ -150,8 +150,8 @@ now **0**: nothing on this surface threads a context that provably lacks the fla
 
 **"No tenant context" counted sites it had not read.** An options argument the
 walker could not parse was folded into the same bucket as one it had read and
-found empty. That published **61 sites "carrying no tenant context at all"**
-when 8 said so and 53 were simply unread — an over-claim in the *alarming*
+found empty. That published **60 sites "carrying no tenant context at all"**
+when 8 said so and 52 were simply unread — an over-claim in the *alarming*
 direction, on the very figure this page tells other cards to cite. `carries` is
 now three-valued, and an unreadable argument can never contribute to the
 provable count.
@@ -187,10 +187,10 @@ reproduce them. Where it disagrees, it disagrees on the page:
 
 | carried figure | where it survives | this census |
 | :--- | :--- | ---: |
-| 175 write call sites | quoted in the merged changeset | **229** |
-| 24 carrying no tenant context | quoted in the merged changeset | **2** provable and tenancy-enabled; **32** more whose options argument is unreadable |
-| 127 of 175 statically decidable, 48 runtime-parameter-name sites | restated on the `isSystem`-scoping card | **158 of 229** decidable, **71** undecidable |
-| 135 (77%) silenced by the `isSystem` guard before the posture gate | the lost issue body — **no surviving corroboration** | **not reproduced**: 125 decidably elevated, 0 decidably not, 96 undecidable |
+| 175 write call sites | quoted in the merged changeset | **231** |
+| 24 carrying no tenant context | quoted in the merged changeset | **2** provable and tenancy-enabled; **31** more whose options argument is unreadable |
+| 127 of 175 statically decidable, 48 runtime-parameter-name sites | restated on the `isSystem`-scoping card | **160 of 231** decidable, **71** undecidable |
+| 135 (77%) silenced by the `isSystem` guard before the posture gate | the lost issue body — **no surviving corroboration** | **not reproduced**: 128 decidably elevated, 0 decidably not, 95 undecidable |
 | 141 and 132, two independent re-derivations | the card that filed this work | — |
 
 **The differences are not reconciled, and deliberately so.** The old census's
@@ -200,21 +200,21 @@ be stated is what this instrument counts, which is written above and re-runnable
 at any commit.
 
 Two structural facts do plausibly widen this reading against any hand or regex
-one, and both are counted in the generated tables below: the 38 sites reached
+one, and both are counted in the generated tables below: the 40 sites reached
 through an erased (`any`) receiver, and the 52 that name their object through a
 `const` rather than inline. An instrument that read either the way a person does
 would report a smaller number and would not say so.
 
 The fourth row is the one worth flagging to anyone citing it. **The 135 / 77%
 figure has no surviving corroboration anywhere in the tree.** This census reads
-125 of 229 (55%) as decidably elevated, with 96 more whose elevation is a
+128 of 231 (55%) as decidably elevated, with 95 more whose elevation is a
 run-time fact — so the claim is neither confirmed nor refuted, and the honest
 answer is that a static reading cannot settle it.
 
-⇒ **Cite `2 / 229`, and say what it is**: the sites whose options argument was
+⇒ **Cite `2 / 231`, and say what it is**: the sites whose options argument was
 READ and holds no tenant context, against a decidably tenancy-enabled object.
 That is the control's provable yield surface. ⛔ Do not cite it as "the sites
-without tenant context" — **32 further sites** have an options argument this
+without tenant context" — **31 further sites** have an options argument this
 cannot read, and they are neither in nor out.
 
 {/* BEGIN GENERATED: tenant-audit-census (scripts/tenant-audit-census.mjs) — DO NOT EDIT */}
@@ -223,28 +223,28 @@ cannot read, and they are neither in nor out.
 
 | what | count |
 | :--- | ---: |
-| write call sites on the application surface | **229** |
-| …whose object name is statically decidable | 158 |
+| write call sites on the application surface | **231** |
+| …whose object name is statically decidable | 160 |
 | …whose object name is chosen at run time | 71 |
-| …against an object with tenancy ENABLED | 157 |
+| …against an object with tenancy ENABLED | 159 |
 | …against an object that declares tenancy off | 1 |
-| threading a tenant context | 168 |
+| threading a tenant context | 171 |
 | PROVABLY carrying none (options read, no context key) | **8** |
 | …of those, against a decidably tenancy-enabled object | **2** |
-| options argument UNREADABLE — may or may not carry one | 53 |
-| …of those, against a decidably tenancy-enabled object | 32 |
-| threading a decidably ELEVATED (`isSystem`) context | 125 |
+| options argument UNREADABLE — may or may not carry one | 52 |
+| …of those, against a decidably tenancy-enabled object | 31 |
+| threading a decidably ELEVATED (`isSystem`) context | 128 |
 | threading a context that is decidably NOT elevated | 0 |
-| threading a context whose elevation is a run-time fact | 96 |
+| threading a context whose elevation is a run-time fact | 95 |
 
 | how the instrument reached the site | count |
 | :--- | ---: |
 | receiver carried a readable engine type | 191 |
-| receiver erased, placed by the object NAME | 28 |
+| receiver erased, placed by the object NAME | 30 |
 | receiver erased, placed by an `object: string` PARAMETER | 5 |
 | receiver erased, placed by an `UNTYPED_RECEIVERS` row | 5 |
 
-| object name spelled inline | 106 |
+| object name spelled inline | 108 |
 | object name spelled through a `const` | 52 |
 | object name is an `object: string` parameter | 7 |
 | object name is some other run-time expression | 64 |
@@ -297,13 +297,13 @@ holds still. They are required to be HERE and to say WHEN they were true;
 their values are not compared. The reasoning, and the measurement behind it,
 are in `scripts/check-tenant-audit-census.mjs`.
 
-Measured on 2026-10-16 at `22b217924`.
+Measured on 2026-10-19 at `2623d6d6c`.
 
 | corpus scale (not enforced) | count |
 | :--- | ---: |
-| tracked non-test sources scanned | 657 |
+| tracked non-test sources scanned | 670 |
 | engine-shaped types recognised | 79 |
 | declared objects in the registry | 116 |
-| same-named calls subtracted as non-engine | 165 |
+| same-named calls subtracted as non-engine | 166 |
 
 {/* END GENERATED: tenant-audit-census */}

docs/audits/2026-08-tenant-audit-write-call-sites.counts.md

@@ -33,19 +33,19 @@ silent, and `node scripts/tenant-audit-census.mjs --write` is the resolution.
 
 | Measure | Value |
 |---|---:|
-| Write call sites | 229 |
-| Object name statically decidable | 158 |
+| Write call sites | 231 |
+| Object name statically decidable | 160 |
 | Object name chosen at run time | 71 |
-| Against a tenancy-enabled object | 157 |
+| Against a tenancy-enabled object | 159 |
 | Against an object declaring tenancy off | 1 |
-| Threading a tenant context | 168 |
+| Threading a tenant context | 171 |
 | Provably carrying none | 8 |
 | …and decidably tenancy-enabled | 2 |
-| Options argument unreadable | 53 |
-| …and decidably tenancy-enabled | 32 |
-| Threading a decidably elevated context | 125 |
+| Options argument unreadable | 52 |
+| …and decidably tenancy-enabled | 31 |
+| Threading a decidably elevated context | 128 |
 | Threading a decidably non-elevated context | 0 |
-| Threading a context of undecidable elevation | 96 |
+| Threading a context of undecidable elevation | 95 |
 
 ## Subtractions the census could NOT defend — enforced
 
@@ -90,14 +90,14 @@ holds still. They are required to be HERE and to say WHEN they were true;
 their values are not compared. The reasoning, and the measurement behind it,
 are in `scripts/check-tenant-audit-census.mjs`.
 
-Measured on 2026-10-16 at `22b217924`.
+Measured on 2026-10-19 at `2623d6d6c`.
 
 | corpus scale (not enforced) | count |
 | :--- | ---: |
-| tracked non-test sources scanned | 657 |
+| tracked non-test sources scanned | 670 |
 | engine-shaped types recognised | 79 |
 | declared objects in the registry | 116 |
-| same-named calls subtracted as non-engine | 165 |
+| same-named calls subtracted as non-engine | 166 |
 
 ## Every site
 
@@ -133,7 +133,9 @@ Measured on 2026-10-16 at `22b217924`.
 | `packages/plugins/plugin-auth/src/auth-manager.ts` | `update` | `sys_session` | enabled | options unreadable | 3 |
 | `packages/plugins/plugin-auth/src/auth-manager.ts` | `update` | `sys_two_factor` | enabled | options unreadable | 1 |
 | `packages/plugins/plugin-auth/src/auth-manager.ts` | `update` | `sys_user` | enabled | options unreadable | 8 |
-| `packages/plugins/plugin-auth/src/auth-manager.ts` | `insert` | `sys_user_permission_set` | enabled | options unreadable | 1 |
+| `packages/plugins/plugin-auth/src/auth-manager.ts` | `insert` | `sys_user_permission_set` | enabled | elevated | 1 |
+| `packages/plugins/plugin-auth/src/auth-manager.ts` | `delete` | `sys_verification` | enabled | elevated | 1 |
+| `packages/plugins/plugin-auth/src/auth-manager.ts` | `insert` | `sys_verification` | enabled | elevated | 1 |
 | `packages/plugins/plugin-auth/src/auth-plugin.ts` | `update` | `sys_oauth_application` | enabled | PROVABLY NONE | 1 |
 | `packages/plugins/plugin-auth/src/auth-plugin.ts` | `update` | `sys_user` | enabled | elevated | 1 |
 | `packages/plugins/plugin-auth/src/auth-plugin.ts` | `update` | `SystemObjectName.USER` | undecidable | elevated | 1 |

packages/plugins/plugin-auth/src/audience-posture.test.ts

@@ -122,6 +122,16 @@ const PASSWORD = 'S3cure!Passw0rd-4785';
 const bindRowCatalog = (engine: any) =>
   bindTestSecurityCatalog(engine, () => catalogFromTables({ sys_permission_set: engine.tables.get('sys_permission_set') }));
 
+/**
+ * [ADR-0131 D3] The self-registration grant is written WITH a membership. The
+ * end-of-chain cases that assert the grant lands at sign-up run `single`: the
+ * reconciler binds the Default Organization in the same `user.create.after`
+ * hook, and the grant is owned by it. The walled half (no membership yet, the
+ * grant held as a claim until the first one) is pinned in
+ * `self-registration-grant-first-membership.test.ts`.
+ */
+const SINGLE_TENANCY = () => ({ defaultOrgId: async () => 'org_default' });
+
 const makeManager = (engine: any, config: Record<string, unknown> = {}) =>
   new AuthManager({
     secret: SECRET,
@@ -731,6 +741,7 @@ describe('end of the chain: better-auth pipeline over the memory engine (#11739)
     seedExistingUser(engine);
     seedPermissionSet(engine, 'portal_user');
     const manager = makeManager(engine, {
+      getTenancy: SINGLE_TENANCY,
       audience: {
         posture: 'email_domain',
         allowedEmailDomains: ['acme.com'],
@@ -747,6 +758,8 @@ describe('end of the chain: better-auth pipeline over the memory engine (#11739)
       expect(grants[0].permission_set).toBe('portal_user');
       const created = (engine.tables.get('sys_user') ?? []).find((u: any) => u.email === 'user+tag@acme.com');
       expect(grants[0].user_id).toBe(created?.id);
+      // ADR-0131 D3: owned by the membership it travels with.
+      expect(grants[0].organization_id).toBe('org_default');
     });
 
     const refused = await signUp(manager, 'user@mail.acme.com'); // subdomain: NOT implied
@@ -764,6 +777,7 @@ describe('end of the chain: better-auth pipeline over the memory engine (#11739)
     const engine = createMemoryEngine();
     seedExistingUser(engine);
     const manager = makeManager(engine, {
+      getTenancy: SINGLE_TENANCY,
       audience: { posture: 'open', selfRegistrationPermissionSet: 'portal_user' },
     });
     bindTestSecurityCatalog(engine, { permissions: [{ name: 'portal_user' }] });
@@ -838,6 +852,7 @@ describe('end of the chain: better-auth pipeline over the memory engine (#11739)
     seedExistingUser(engine);
     seedPermissionSet(engine, 'member_default', { active: false });
     const manager = makeManager(engine, {
+      getTenancy: SINGLE_TENANCY,
       audience: { posture: 'open', selfRegistrationPermissionSet: 'member_default' },
     });
     const res = await signUp(manager, 'anyone@anywhere.com');
@@ -852,6 +867,7 @@ describe('end of the chain: better-auth pipeline over the memory engine (#11739)
     seedExistingUser(engine);
     seedPermissionSet(engine, 'member_default');
     const manager = makeManager(engine, {
+      getTenancy: SINGLE_TENANCY,
       audience: { posture: 'open', selfRegistrationPermissionSet: 'member_default' },
     });
     const res = await signUp(manager, 'anyone@anywhere.com');