[Epic] Migrate SCIM from @better-auth/scim 1.7.0-rc.1 to stable 1.7.x — seven-model provision, sys_scim_provider disposition, token reissue coordination, net-new Setup surface

[os-zhuang]

Chartered by maintainer ruling, 2026-08-24, live PM chat on #3653 (「os#3653 立项迁移」). The spec half of #3653's question A is thereby answered implement — the SCIMGroup family becomes true through this migration, not through retirement.

Scope (from the measured chartering input — #3653 comments 5386605190 / 5387582046, the seven-model diff)

1. Platform objects: provision the seven stable models (scimConnectionBinding, scimIdentityTombstone, scimSubject, scimUser, scimProjectionGrant, scimGroup, scimGroupMember); decide whether managedConnections (the conditional trio scimManagedConnection/scimManagedCredential/scimManagedConnectionEvent) is adopted — stable's managed catalog partially restores DB-backed runtime connections, so sys_scim_provider's disposition (retire vs facade vs managed-catalog adoption) is decided INSIDE this epic with that fact on the table.
2. plugin-auth: scim({...}) call gains stable's required options (storeSCIMToken is gone; connections / verifyBearerToken / managedConnections three-way); AUTH_MODEL_TO_PROTOCOL entries for the new models (stable accepts no schema option — adapter bridging remains the only naming route).
3. spec: field-level parity pass between SCIMGroupSchema and stable's group wire shape (unmeasured so far); packages/spec work goes to the spec seat per single-owner rule.
4. Parity gate: restructure better-auth-schema-parity.test.ts per the Fix the SCIM parity gate's constructor call so it actually prints the seven-model diff against @better-auth/scim 1.7.1 #11380/PR fix(plugin-auth): make the SCIM parity gate reach its model diff on stable @better-auth/scim #11429 repair (its constructor fix is a prerequisite — land or absorb it).
5. Setup surface: net-new build (objectui and cloud measured at zero SCIM UI today); stable's serverOnly managed-catalog endpoints are the natural backend seam.
6. ⚠️ Operator coordination: token digests are NOT portable on any path (unsalted SHA-256 → keyed HMAC; stable forces credential expiry) — every SCIM-enabled deployment's IdP reissues its token on migration day. This is a scheduled operational action inside the epic, not a discovery.
7. Scaffold allowedVersions suppressions retire with the pin move (the two presence-ratchet tests must flip in the same stroke); ⛔ the better-auth>better-sqlite3 and @better-auth/utils entries do NOT retire with it.

Discipline

Contract-first decomposition by the owning seat: parent (this card) + sub-issues per surface, spec first, Blocked-by: chains between legs. Standing operational note until the migration lands: SCIM-enabled deployments must not let the IdP push groups.

Refs: #3653 (decision anchor + measurements) · #11380 / PR #11429 (gate repair) · #11372 (workspace comment correction) · ADR-0071.

[os-sam]

Owning seat claimed — domain:services execution seat, PM session session_01APWX2AwT3a4xDcjPCe8bk4. Assigned to me as the decomposing seat, not as an implementer.

⛔ This card is not dispatchable as a unit and I am not dispatching it. Its own Discipline section says so: "Contract-first decomposition by the owning seat: parent (this card) + sub-issues per surface, spec first, Blocked-by: chains between legs." has_children is currently false, so that decomposition has not happened yet. Recording the shape now, before sub-issues are written, so the legs are not cut along the wrong seams.

Three things that must be settled BEFORE the sub-issues can be scoped

1. sys_scim_provider's disposition is a DECISION, not a leg. Scope item 1 says it is "decided INSIDE this epic" with the managed-catalog fact on the table — retire vs facade vs managed-catalog adoption. Several other legs' scope depends on which way it goes (the Setup surface's backend seam in particular). ⇒ It gets a decision card of its own, ruled first, not a task card someone starts and discovers is a fork. ⛔ Not mine to rule.

2. The packages/spec leg is not this seat's. Scope item 3 says it explicitly: "packages/spec work goes to the spec seat per single-owner rule." This lane has zero ownership there. That leg becomes a card in the spec lane with a Blocked-by: pointing at it from the legs that consume the parity result — the same contract-first shape as #10413 → #10576 and #10025 → #11504.

3. Leg 4 has a prerequisite that is not ours to assume. The parity-gate restructure depends on #11380 / PR #11429's constructor fix — "land or absorb it." Whether it lands independently or gets absorbed changes whether leg 4 is one card or two. That needs checking against #11429's current state before the leg is written, not after.

⚠️ Leg 6 is not code and must not be filed as a dev card

token digests are NOT portable on any path (unsalted SHA-256 → keyed HMAC; stable forces credential expiry) — every SCIM-enabled deployment's IdP reissues its token on migration day

That is a scheduled operational action with a human owner, and the epic itself calls it "not a discovery." An os-dev subagent cannot perform it and must not be handed it. It needs to be tracked as a release/operations item with a date, coordinated with whoever owns deployments — and the standing note (SCIM-enabled deployments must not let the IdP push groups until this lands) needs to be visible somewhere operators actually read, not only on this card.

⛔ I am not deciding where that lives; flagging it because a naive decomposition turns all seven scope items into dev cards and this one would silently become a no-op card that never completes.

The ordering I read from the charter

Contract-first, so: spec parity (spec seat) → sys_scim_provider disposition ruled → platform objects + plugin-auth options → parity gate → Setup surface. Leg 6 runs alongside, on the release calendar, not in the dependency chain. Leg 7 (allowedVersions suppressions + the two presence-ratchet tests) must flip in the same stroke as the pin move — so it belongs inside whichever leg moves the pin, never as its own card. ⚠️ And its exclusion is explicit: better-auth>better-sqlite3 and @better-auth/utils do not retire with it.

What happens next

I will file the sub-issues as dev slots free — three are in flight right now (#11343 security, #11386, #11507), and cutting an epic's legs badly is more expensive than cutting them late. The decision card in (1) and the spec-lane card in (2) do not wait on that, since neither is dispatched from here.

Refs: #3653 (decision anchor + the seven-model measurements) · #11380 / PR #11429 · #11372 · ADR-0071

---

Generated by Claude Code

[os-sam]

Decomposition update — blocker 3 resolved by measurement, blocker 1 sharpened

domain:services owning seat (session session_01APWX2AwT3a4xDcjPCe8bk4). Re-measured rather than carried forward from my 10:33Z comment — that note was mine, and a note I wrote is not evidence.

Blocker 3 — RESOLVED. Leg 4 is one card, not two.

My earlier comment said leg 4's shape depended on whether #11380 / PR #11429 "lands independently or gets absorbed", and that this had to be checked before the leg was written. Checked:

PR #11429 is MERGED — 2026-08-23T18:23:39Z, into main, one file, skip-changeset.

It landed independently. So the parity-gate restructure is a single card with its prerequisite already on main, and nothing about leg 4 is conditional any more.

⭐ Blocker 1 is no longer an open-ended fork — the merged gate measured a constraint on it

sys_scim_provider's disposition (retire / facade / managed-catalog adoption) was framed as a choice to be "decided INSIDE this epic". The repaired gate now prints the model diff against published @better-auth/scim@1.7.1, and one line of it bears directly on that choice:

expected [ 'user', 'session', 'account', …(9) ] to include 'scimProvider' — the model the bridge maps is gone on stable.

⇒ The upstream scimProvider model does not exist on the stable line. So this is not a free three-way choice between equally-available shapes: whatever sys_scim_provider becomes, it can no longer be a mirror of an upstream model, because there is nothing upstream to mirror. That is a measured input to your decision, not the decision — ⛔ still not mine to rule.

The full stable-line diff the gate now produces, for whoever takes the decision card:

	models
gained	scimConnectionBinding, scimIdentityTombstone, scimProjectionGrant, scimSubject, scimUser
lost	scimGroupRole, scimGroupRoleGrant
kept	scimGroup, scimGroupMember

(Seven differences, exactly as #3653 predicted the gate would report "the instant you upgrade" — which is what PR #11429 restored, since the pristine gate died in collection and printed Tests no tests.)

Blocker 2 — unchanged

The packages/spec parity leg still belongs to the spec seat per the single-owner rule; this lane has zero ownership there. Unchanged, and not something measurement can move.

What I am filing now, and what I am not

Filing: the sys_scim_provider decision card, carrying the measured constraint above. ⭐ Filing a decision card is not ruling it — it is what stops a dev picking up a task card and discovering a fork three hours in, which is the failure this epic's own Discipline section warns about.

⛔ Not filing: the remaining legs. They stay uncut until the disposition is ruled, because the Setup surface's backend seam is scoped by which way it goes — cutting them now is cutting along the wrong seam.

⚠️ Leg 6 still must not become a dev card. Restating because a later decomposition pass will be tempted: every SCIM-enabled deployment's IdP must reissue its token on migration day (unsalted SHA-256 → keyed HMAC; digests are not portable on any path). That is a scheduled operational action with a human owner. An os-dev cannot perform it, and filed as a dev card it becomes a no-op card that never completes.

---

Generated by Claude Code