fix(plugin-auth): settle membership under the auto policy at user creation (ADR-0093 D7)

[objectstack-fleet]

Fixes #21791

Clause-②: yes (widening)

What

Under the auto membership policy, membership is now decided when the user is created (ADR-0093 D7), per the maintainer ruling recorded on the card. Packages: @objectstack/plugin-auth, @objectstack/organizations, @objectstack/types.

• Creation. User creation binds a new user to the default organization, as before, and the first session minted by that same request carries it. The request recognises its own new user from the store adapter's create result, staged per request context; nothing is read back, and nothing outlives the request. Later sign-ins do not decide membership.
• One-time decisions, recorded in the sys_migration ledger.
  • The backfill of users who predate the policy (adr-0093-membership-backfill) scans the user and member tables in full with keyset pages, with no row cap. An incomplete scan binds nobody and records nothing. A multi-org deployment with no default target is recorded as such. A deployment with no organization at all defers, and the pass runs when the default organization is first created.
  • The default-organization owner bind (adr-0093-default-org-owner-bind) runs once. One shared gate (createEnsureDefaultOrganizationOnce) is used by both the single-organization wiring and the walled @objectstack/organizations wiring. Once decided, a missing default organization is recreated with nobody bound and no seed-ownership handoff. On a kernel without the ledger, the owner is bound only when the bootstrap creates the organization; if the ledger exists but cannot be read, that call binds nobody and the next trigger decides.
  • Each decision is latched in-process once acted on, even if writing its record fails (that failure is logged at error).
• keysetWalk (@objectstack/types) detects a stalled cursor by key equality or a repeated page, never by string order.
• Showcase. The approval-demo seed writes its demo personas' membership when it creates them.
• New public surface of @objectstack/plugin-auth (additive, minor): createEnsureDefaultOrganizationOnce and EnsureDefaultOrganizationOnceOptions; ObjectQLAdapterFactoryOptions.onRecordCreated via the new optional second argument of createObjectQLAdapterFactory; bindOnlyOnCreate / bindOwner on EnsureDefaultOrganizationOptions; reason members 'owner_bind_decided' and 'scan-incomplete'. @objectstack/organizations and @objectstack/types add no public export (patch).
• Deprecated, not removed: the ungated ensureDefaultOrganization (plugin-auth helper and the organizations wrapper), in favour of the gated factory.
• Recovery: after a default organization is recreated with nobody bound, an administrator re-adds members, including themselves, through member management.
• Unchanged. invite-only binds nobody; multi-org has no automatic binding; the creation paths (sign-up, admin create, import, SSO JIT) still bind under auto.
• Derived artefacts, regenerated with their tools: the tenant-audit census (one new engine write site) with its prose figures, the engine test-double ledger, the durability gate vocabulary (persistLedgerDecisionRow) and its swallow-census copy.

Tests

Measured at 3ed15b1836:

• @objectstack/plugin-auth: typecheck green; 121 files, 2541 passed, 10 skipped.
• @objectstack/organizations: typecheck green; 9 files, 131 passed.
• @objectstack/types: typecheck green; 23 files, 706 passed (--project local).
• Dogfood (real showcase boot): membership decided at creation; demo personas hold an organization; neighbouring persona, approval-override and membership-revoke suites — 5 files, 10 passed.
• New coverage: the one-time ledger (first pass, recorded verdict, multi-org refusal, deferral, pagination past one page, incomplete scan, unreadable ledger, failed record then later triggers), creation recognised only within its own request (including a different pre-existing user in a creating request), restart after a membership change, the walled owner-bind gate, recreate-without-bind, and keyset stall detection under non-JS collations.
• Ablations through scripts/ablation-replace.mjs, each restored to HEAD: the request-scoped creation check, the in-process latches (owner bind, backfill), the keyset equality check, and the persona membership write each turned their test red.
• pnpm gates via dispatch-gates: 121 derived, 121 run, all exit 0 (including the changeset gates against origin/main); CI-environment jobs (shards, test completeness, workspace type-check lanes) left to CI.

Acceptance notes

• Upgrade boot. The first boot of this version has no record, so both one-time passes run once; after that they are recorded.
• Users inserted directly through the data engine (including seeds that finish after their budget) never cross user creation and stay unbound once the backfill is recorded. Seeds should create users through the creation seam or write membership themselves, as the showcase seed now does.
• ADR-0093 D6's text still describes the recurring app:seeded re-run; amending it is a governed (Tier H) edit left to the maintainer.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 3 package(s): @objectstack/organizations, @objectstack/plugin-auth, @objectstack/types, touching 55 documentable anchor(s). ⚠️ 2 changed file(s) yielded no anchor (packages/plugins/organizations/src/ensure-default-organization.ts, packages/plugins/plugin-auth/src/index.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

30 hand-written doc(s) name something this change touched — list omitted above 15 rows. Re-derive on the tree named below: node scripts/docs-audit/affected-docs.mjs --json 9f9510f25e6aa65aa61ce3effb42706fabcab92e.

⛔ 11 release-owned page(s) also affected — read-only, see AGENTS.md Documentation Guardrails.

What this run could not see

• 2 changed file(s) yielded no anchor (packages/plugins/organizations/src/ensure-default-organization.ts, packages/plugins/plugin-auth/src/index.ts) — pages documenting those are invisible to this run
• 1 anchor(s) matched too much of the corpus to be a work list: sys_user (literal, 37 pages)
• 8 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 — 21 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 9f9510f25e6aa65aa61ce3effb42706fabcab92e → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 2a800159759cab12a8abd8faf01528c74b4be097 — the merge of head 5c52ad32f1ce53f9985a4a7107c6270751596ce0 into base 9f9510f25e6aa65aa61ce3effb42706fabcab92e, 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 2a800159759cab12a8abd8faf01528c74b4be097 && git checkout 2a800159759cab12a8abd8faf01528c74b4be097
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 9f9510f25e6aa65aa61ce3effb42706fabcab92e 5c52ad32f1ce53f9985a4a7107c6270751596ce0 && git checkout -B drift-repro 9f9510f25e6aa65aa61ce3effb42706fabcab92e && git merge --no-ff 5c52ad32f1ce53f9985a4a7107c6270751596ce0

node scripts/docs-audit/affected-docs.mjs --json 9f9510f25e6aa65aa61ce3effb42706fabcab92e

⚠️ 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 9f9510f25e6aa65aa61ce3effb42706fabcab92e → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 3ed15b1836de49ed4405298196b64199dd7a6f90
Local-runs: none

Inputs read: card #21791 (body and all 5 comments, including the Ruled: on ADR-0093 D7 and three os-dev-reports), the PR body, the file list and the net diff origin/main...3ed15b1836 (28 files), and the check-runs on this head. Class level only. The held detail is not restated.

① Derived judgments

Measured against the ruling: under auto, membership is decided when the user is created, plus one one-time backfill of users who predate the policy. Nothing re-binds a user whose membership was removed.

• Sign-in seam (accept set narrowed to the ruling): RIGHT. The session-create settle now runs only for a user that the same request created. That user is staged from the adapter's own create result, keyed by request context in a WeakMap, so nothing outlives the request and the store is not read back. A member-less user who signs in later is not re-decided. The dogfood test on a real boot covers both directions: the first session after sign-up carries the organization, and sign-in after removal carries none.

• Backfill becomes one-time and is recorded in sys_migration as adr-0093-membership-backfill: RIGHT. The latch holds even when the record write fails. An incomplete scan, a deployment with no organization, or an unreadable ledger records nothing. A multi-org refusal is recorded. All of this matches the literal "one-time backfill" in the ruling.

• Default-org owner bind decided once (adr-0093-default-org-owner-bind), one gate for both postures: RIGHT. The single-org AuthPlugin and walled OrganizationsPlugin both call createEnsureDefaultOrganizationOnce. After the decision, a missing organization is recreated with nobody bound. With no ledger, the owner is bound only on the call that creates the organization. With an unreadable ledger, that call binds nobody. A walled pin test confirms the bind is not repeated.

• invite-only verdict is recorded as final: RIGHT under D7, noted. A pass under invite-only records reason: policy. A later switch to auto therefore never backfills the users who existed under invite-only. Before this change, the next boot did. This follows from "decided at creation" (those users were decided unbound), and the changeset's "once per deployment" covers it. It is not spelled out, so it is noted for the maintainer in ③ and does not block.

• Kernel with no ledger: the backfill no longer runs (narrowed): RIGHT, documented. The pass logs a warning and binds nobody. The changeset states this.

• Public surface of @objectstack/plugin-auth, additive: RIGHT. New exports createEnsureDefaultOrganizationOnce and EnsureDefaultOrganizationOnceOptions. New optional second argument ObjectQLAdapterFactoryOptions.onRecordCreated (a throw inside it is swallowed after the row lands). New options bindOnlyOnCreate and bindOwner. New output-union members 'owner_bind_decided' and 'scan-incomplete'. ensureDefaultOrganization is @deprecated, not removed. Nothing is removed or renamed.

• Public surface of @objectstack/plugin-auth, backfillMemberships (exported through reconcile-membership.js): WRONG, in what the changelog says. The diff publishes two things here that the changeset does not state:

  1. The limit option used to be a row cap (default 5000). It is now the keyset page size, and the scan is uncapped (default page 500).
  2. The function now needs a reader that honours keyset seek. A reader that cannot seek stalls the walk, and the function returns scan-incomplete and binds nobody. Before, it bound.

  In addition, a direct call to this export is still ungated and re-decides membership on every call. This is the same property for which ensureDefaultOrganization got its @deprecated note, but backfillMemberships carries no such note. The behaviour is correct; the published text is incomplete.

• @objectstack/organizations: RIGHT. No new export. The wrapper is deprecated by JSDoc. The walled behaviour change is the ruling's.

• @objectstack/types keysetWalk: RIGHT. A stall is now detected by key equality or a repeated page instead of JS string order. This removes false truncations under database collations and still catches a reader that ignores the predicate. A collation test covers it.

• Derived artefacts: RIGHT. The census (one new write site), the engine-double ledger, and the durability vocabulary plus its swallow-census copy were all regenerated with their tools. The showcase seed (@objectstack/example-showcase, private) writes persona membership at creation and publishes nothing.

② Semver level

• The changeset sets @objectstack/plugin-auth to minor, and @objectstack/organizations and @objectstack/types to patch. These levels match what the diff publishes: an additive public surface in plugin-auth, and fixes with no new export in the other two. Nothing is removed, so no (narrowing) or BREAKING arm is owed. The behavioural narrowings are the ruled fix of off-contract re-binding, not a removed author-writable key, export or config field.

• Clause-②: yes (widening). This is correct, and the changeset and PR body both carry it. yes takes at least minor, and minor is given.

• The changeset text is short by one surface (blocking). It must state the backfillMemberships change from ①. Suggested Narrowed / public-surface lines:

  • limit is now the page size of an uncapped keyset scan, where it used to be a row cap.
  • The function needs a reader that can seek on id, and a reader that cannot gets scan-incomplete with no binds.
  • A direct call is not gated and re-decides membership. One-time behaviour comes only through the plugin's own wiring.

  The function's JSDoc should say the same about the direct call, as ensureDefaultOrganization's now does.

③ Boundary flags

• open_questions, round 0, Q1 (rows inserted raw through the engine are no longer bound once the backfill is recorded): answered A, consistent with the recorded ruling. Such a row never passes user creation, and the ruling allows one backfill only. The changeset Narrowed line states this, and the in-tree producer (the showcase personas) now writes its own membership. The card holds no separate Ruled: for Q1 or Q2. The round-1 report's "ruled A" has no record on the card, so this seat answers both on the D7 text, not on that report.
• open_questions, round 0, Q2 (on upgrade, the first boot runs the backfill once): answered A, consistent with the recorded ruling. This is the literal one-time backfill, and it fails toward the documented D6 behaviour. The changeset Upgrade line states it.
• Rounds 1 and 2: open_questions is empty. The round-1 out-of-scope item (the walled bootstrap copy) is resolved in this diff, because the walled wiring now uses the shared gate.
• Escalated to the maintainer (Tier H), not blocking:
  • ADR-0093 D6 still describes the recurring app:seeded re-run. Amending it is a governed edit.
  • The invite-only to auto switch semantics from ① could go in the same amendment.
• Escalated to the PM seat, a landing precondition outside the diff: the card's claim comment says Clause-②: no, and the round-2 report repeats it. This head declares yes (widening) and adds exports. check-widening-tells reads the claim's line at enqueue. The claim should be revised to Clause-②: yes (widening) before the PR enters the queue.
• CI on this head is NOT complete. Completed: the claim / single-writer / same-issue / Part-of guards and the Governed Surface Queue Guard, all success. In progress: Build Core, Test Core 1–6, Dogfood Regression Gate 1–3, Dogfood Verify CLI, Build Docs, Temporal Conformance, the Type Check lanes, Lint & Repo Gates, and Check Changeset. This verdict is on the diff. Landing waits for green whatever the verdict.
• The dev's declared NOT MEASURED item (check:dual-build-cjs-loads, prerequisite not met) is left to CI. It is part of the in-progress set above.

Required to flip to PASS: add the backfillMemberships lines from ② to the changeset, plus the JSDoc note on direct calls. Nothing else in the diff needs to change.

Implemented-by: claude/issue-21791-membership-create-time
Reviewed-by: session_018zT8d8NpiQ1ExhuNd5TxY6

VERDICT: FAIL

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 5c52ad32f1ce53f9985a4a7107c6270751596ce0
Local-runs: none

Inputs read: card #21791 (body and all 6 comments: the triage, the claim with its Ruled: on ADR-0093 D7, three os-dev-reports, and the PM claim correction 5993329356 with its two Ruled: lines), the PR body, the file list and the net diff origin/main...5c52ad32f1 (28 files), the earlier record 5993275120 (FAIL on 3ed15b1836), and the check-runs on this head. The only commit since 3ed15b1836 is 5c52ad32f1 (changeset +2 lines, one JSDoc block in reconcile-membership.ts); the rest of the net diff was re-read on this head. Class level only. The held detail is not restated.

① Derived judgments

Measured against the ruling: under auto, membership is decided when the user is created, plus one one-time backfill of users who predate the policy; nothing re-binds a user whose membership was removed.

• Sign-in seam (accept set narrowed to the ruling): RIGHT. The session-create settle runs only when isCreatedInThisRequest(ctx, userId) holds. The id is staged from the adapter's own create result into a WeakMap keyed by the endpoint context, so nothing outlives the request and nothing is read back. A member-less user signing in later stops at an in-memory lookup. The dogfood test on a real boot covers both directions, and the dev's adapter-staging ablation turned it red.
• Backfill one-time, recorded as adr-0093-membership-backfill: RIGHT. Latched in-process even if the record write fails; an incomplete scan, a deployment with no organization, or an unreadable ledger records nothing; a multi-org refusal is recorded. Matches the ruling's literal one-time backfill.
• Default-org owner bind decided once (adr-0093-default-org-owner-bind), one gate for both postures: RIGHT. AuthPlugin and OrganizationsPlugin both call createEnsureDefaultOrganizationOnce; the walled wiring injects claimOrgSeedOwnership directly, the same handoff its old wrapper injected. Once decided, bindOwner: false recreates a missing organization with nobody bound and no handoff. unavailable ledger binds only on the creating call (bindOnlyOnCreate); unreadable binds nobody that call. Only memberCreated or admin_already_in_org latches; no_admin and failed writes stay open.
• invite-only verdict recorded as final: RIGHT under D7, now stated. The changeset's new Policy switch line says a later switch to auto does not backfill the users who existed under invite-only. This closes the note the earlier record raised.
• Kernel with no ledger: the backfill does not run (narrowed): RIGHT, documented in the changeset (warn, binds nobody).
• Public surface of @objectstack/plugin-auth, additive: RIGHT. New exports createEnsureDefaultOrganizationOnce / EnsureDefaultOrganizationOnceOptions (via the new export * in index.ts); ObjectQLAdapterFactoryOptions.onRecordCreated through a new optional, defaulted second argument of createObjectQLAdapterFactory (a throw is swallowed after the row lands); bindOnlyOnCreate / bindOwner options; output-union members 'owner_bind_decided' and 'scan-incomplete'. ensureDefaultOrganization is @deprecated, not removed. Nothing removed or renamed.
• Public surface of @objectstack/plugin-auth, backfillMemberships: RIGHT (was WRONG on 3ed15b1836). The changeset now states all three changes the diff publishes: limit turns from a row cap (default 5000) into the page size of an uncapped scan; a reader that cannot page by id gets scan-incomplete and binds nobody, where it used to bind; a direct call is not gated by the ledger and re-decides on every call. The JSDoc now says the same and points at runOneTimeMembershipBackfill. This is exactly what the earlier FAIL required.
• @objectstack/organizations: RIGHT. No new export; the wrapper is @deprecated with the gated replacement named; the walled behaviour change is the ruling's.
• @objectstack/types keysetWalk: RIGHT. A stall is detected by cursor-key equality or a repeated first row, never by JS string order. This removes false truncation under database collations and still catches a reader that ignores the predicate (it returns the same page). No export changes.
• Derived artefacts: RIGHT. Tenant-audit census (one new write site) with its prose figures, the engine-double ledger, the durability vocabulary (persistLedgerDecisionRow) and its swallow-census copy, regenerated with their tools. The showcase seed (private package) writes persona membership at creation and publishes nothing.

② Semver level

• The changeset sets @objectstack/plugin-auth to minor, @objectstack/organizations and @objectstack/types to patch. These match what the diff publishes: additive public surface in plugin-auth, fixes with no new export in the other two. Nothing is removed, so no (narrowing) or BREAKING arm is owed; the behavioural narrowings are the ruled fix of off-contract re-binding, each now stated in the changeset.
• Clause-②: yes (widening). Correct. The changeset and the PR body both carry it, and the card's claim is now corrected to the same value (5993329356), which resolves the claim mismatch the earlier record escalated. yes takes at least minor; minor is given.
• The changeset text now covers every published surface the diff changes. No change owed.

③ Boundary flags

• open_questions, round 0, Q1 (rows inserted raw through the engine stay unbound once the backfill is recorded): answered, A. The card now carries a Ruled: for it (5993329356). The changeset Narrowed line states it, and the one in-tree producer (the showcase personas) writes its own membership.
• open_questions, round 0, Q2 (the first boot of an upgraded deployment runs the backfill once): answered, A. Ruled: on the card (5993329356); the changeset Upgrade line states it.
• Rounds 1 and 2: open_questions empty. The round-0 out-of-scope item on DURABILITY_CRITICAL_CALLEES and the round-1 item on the walled bootstrap copy are both resolved inside this diff.
• Escalated to the maintainer (Tier H), not blocking: ADR-0093 D6 still describes the recurring app:seeded re-run; amending it to the D7 one-time semantics, the invite-only to auto switch included, is a governed edit outside this PR.
• The earlier PM-seat escalation is closed: the card's claim now reads Clause-②: yes (widening).
• CI on this head is NOT complete. Completed with success: Check Changeset, Governed Surface Queue Guard, both same-issue / single-writer guards, Spec property liveness, Type Check · source gates, Check Documentation Links, Check PR Size, docs-affected flag, Auto Label, filter. Skipped: Console Pin Gate, Packed-tarball smoke (opt-in). In progress: Build Core, Test Core 1–6, Dogfood Regression Gate 1–3, Dogfood Verify CLI, Build Docs, Temporal Conformance, Type Check · workspace / debt ledger / consumer gates, Lint & Repo Gates. The dev's NOT MEASURED check:dual-build-cjs-loads falls inside that set. This verdict is on the diff; landing still waits for every check to go green.

Implemented-by: claude/issue-21791-membership-create-time
Reviewed-by: session_018zT8d8NpiQ1ExhuNd5TxY6

VERDICT: PASS