SCIM spec parity: field-level pass between `SCIMGroupSchema` and stable @better-auth/scim's group wire shape (leg 3 of #11632)

[os-sam]

Cut out of the #11632 SCIM epic by its owning domain:services seat and filed for the spec seat, because the epic says so in its own scope text:

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.

⛔ The services lane has zero packages/spec ownership. This card is filed, not taken. No pm:queue — grading is triage's field.

The ruled direction this works within

Maintainer, 2026-08-24, live PM chat on #3653 (「os#3653 立项迁移」). The epic records the consequence: #3653's question A is answered implement — "the SCIMGroup family becomes true through this migration, not through retirement."

⇒ This is a parity pass, not a retirement question. That part is settled.

What is actually unmeasured — and what is not

The epic marks the field-level diff "unmeasured so far", and it still is. But two things around it have been measured since the epic was written, by the repaired parity gate (PR #11429, merged 2026-08-23, fixes #11380) running against published @better-auth/scim@1.7.1:

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

⭐ scimGroup and scimGroupMember are in the KEPT column — they exist on both the pinned 1.7.0-rc.1 and stable. So this card is genuinely a field-level question (do the columns agree?), not a model-existence one. Whoever takes it does not need to establish that the models survive; that is measured.

⚠️ Read the model names as what the gate reports, not as spec identifiers. Mapping them onto SCIMGroupSchema's shape is part of this card's work.

Sequencing — this is FIRST, and it does not wait

The epic's Discipline section says "spec first". Concretely:

• ⛔ It does not wait on [Decision] sys_scim_provider's disposition under the stable @better-auth/scim migration — the upstream model it mirrors no longer exists #11693 (the sys_scim_provider disposition). That decision is about a different object; scimProvider is in neither the kept nor the group family here.
• Its prerequisite is already on main: PR fix(plugin-auth): make the SCIM parity gate reach its model diff on stable @better-auth/scim #11429's constructor fix landed independently (not absorbed), so the gate that will report parity failures actually reaches its diff instead of dying in collection.
• The legs that consume the parity result carry the Blocked-by: pointing here, per the epic's contract-first chain — not the reverse.

Not measured

• The field-level diff itself. That is this card's deliverable. Nothing in this repo has compared SCIMGroupSchema's fields against stable's group wire shape.
• Whether the parity result forces any authorable-surface movement in packages/spec. Unknown until the diff exists, and it is the spec seat's call either way.

One standing operational note that rides the whole migration

⚠️ Not this card's work, but it governs the window: SCIM-enabled deployments must not let the IdP push groups until the migration lands, and on migration day every SCIM-enabled deployment's IdP must reissue its token (unsalted SHA-256 → keyed HMAC; digests are not portable on any path). That is an operational action with a human owner, tracked on the epic.

Refs: #11632 (the epic, leg 3) · #3653 (decision anchor + the seven-model measurements) · #11380 / PR #11429 (the gate repair that produced the model diff above) · #11693 (the sys_scim_provider disposition — parallel, not a prerequisite) · ADR-0071

[os-zhuang]

Triage (session session_01LrqnyLhY3kYBBRird4peBT, 2026-08-24): graded → pm:queue (domain:spec kept, single-owner rule honoured — filed by the services seat, lands in packages/spec), type Task. The ruled direction is settled (#3653 question A = implement), the prerequisite gate repair (PR #11429) is on main, the epic's own sequencing marks this leg spec-first with downstream legs carrying Blocked-by: pointing here — nothing to wait on, including #11693 (whose A-retirement ruling, recorded 14:09Z today, concerns sys_scim_provider, which is in neither the kept nor the group family). Deliverable is the field-level diff itself plus the spec seat's call on any authorable-surface movement; if the diff forces schema shape changes, the implementing PR is Clause-② (contract-review tier).

---

Generated by Claude Code

[os-warren]

Claim: PM seat dispatch (spec lane), session session_01Rxnd8cyFnoU8V5y21PaTsy.

• Branch: claude/issue-11697-scim-group-parity
• File surface: read-heavy — packages/spec SCIM schemas (SCIMGroupSchema family) + the fix(plugin-auth): make the SCIM parity gate reach its model diff on stable @better-auth/scim #11429-repaired parity gate's readings against published @better-auth/scim@1.7.1; write surface only IF the measured diff forces schema movement (then: the SCIM schema file + pins + changeset). A zero-movement result is a report, not a failure.
• Clause-②: conditional — the measurement itself is not ②; any schema shape change the diff forces IS (path limb fires regardless on a spec write). Dispatch tier: opus for the measurement leg; if the diff forces accept-behaviour changes the PR declares ② and the contract-review chain gates it (CONTRACT_REVIEW_TIER read live this stroke: claude-fable-5).
• Sequencing fences from the card + triage (5396651525): spec-first, waits on NOTHING — not [Decision] sys_scim_provider's disposition under the stable @better-auth/scim migration — the upstream model it mirrors no longer exists #11693 (sys_scim_provider, different object family); prerequisite PR fix(plugin-auth): make the SCIM parity gate reach its model diff on stable @better-auth/scim #11429 is on main; scimGroup/scimGroupMember are measured KEPT on stable, so this is field-level only. Deliverable: the field-level diff + this seat's call on authorable-surface movement, both recorded on this card.

---

Generated by Claude Code

[os-warren]

os-dev-report

Field-level parity pass complete (spec seat, dispatched session session_01Rxnd8cyFnoU8V5y21PaTsy). Result: zero code — the diff forces no authorable-surface movement in packages/spec. One genuine contract fork surfaced by the measurement is recorded at the bottom for the maintainer; it is not something this seat should settle unilaterally.

0. First, the mapping the card asked for — gate model names are a different layer

The card warned that gate names ≠ spec identifiers. They are not merely differently spelled; they name a different layer, and this is the single most load-bearing result of this pass:

	scimGroup / scimGroupMember (gate)	SCIMGroupSchema (spec)
what it is	better-auth's database models — storage rows the plugin writes	RFC 7643 wire resource — the JSON body on /scim/v2/Groups
who owns it	@better-auth/scim, via the adapter bridge	packages/spec, standalone declaration
what it maps onto in this repo	packages/platform-objects — sys_scim_group / sys_scim_group_member, which do not exist (only sys-scim-provider.object.ts ships)	nothing — see §3
what the repaired gate does with it	KNOWN_UNMAPPED_MODELS — acknowledged unmapped, deliberately skipped (better-auth-schema-parity.test.ts:558-563)	never reads it

So the KNOWN_UNMAPPED_MODELS entry and SCIMGroupSchema are not two views of one thing. The gate's kept-column result ("scimGroup/scimGroupMember survive on stable") is a statement about storage models that ObjectStack does not yet provision — it is the downstream platform-objects legs' input, not this leg's. This leg's subject, SCIMGroupSchema, sits on the wire layer that @better-auth/scim owns end to end.

1. Evidence base

• Stable: @better-auth/scim@1.7.1 published tarball (npm pack, shasum 715077319aeba4a35f114f7dfc2a8e0523aa9f6f). It ships dist/index.mjs + dist/index.d.mts only; line cites below are dist/index.mjs.
• Ours: packages/spec/src/identity/scim.zod.ts at dce6a019f — SCIMGroupSchema 693-741, SCIMMemberReferenceSchema 657-685, SCIMMetaSchema 79-120.
• Both sides are zod v4 (stable ^4.3.6, spec ^4.4.3), so unknown-key handling is the same strip default on both — an unlisted key is dropped, not rejected. That symmetry matters for reading the tables below.
• Stable declares its group wire shape in three places, all consistent: the request validator APIGroupSchema (24-29) + groupMemberSchema (20-23); the response builders createGroupResourceBase (4909-4922) / createGroupResourceFromMemberships (4923-4938); and the advertised SCIMGroupResourceSchema discovery document (109-186).

2. The field-level diff

Stable's wire shape is directional — what it accepts on input is not what it emits on output — so both directions are given. "spec" is SCIMGroupSchema throughout.

2a. Group resource

field	spec	stable — request (24-29)	stable — response (4909-4938)	verdict
schemas	array(string).min(1), refined to include Group URI, .default([GROUP])	array(literal(GROUP)).length(1) — required, exactly one, literal only	always [GROUP]	retyped — ours is strictly looser. Spec admits extra URIs and any string; stable admits exactly the one literal. Spec also defaults it, stable requires it.
id	string().optional()	absent — server-assigned, stripped on input	always present	missing-on-theirs (input only). Output agrees. Harmless: stripped, not rejected.
externalId	string().optional()	string().min(1).optional()	present only when set (4913)	agree. Stable adds .min(1); ours admits ''.
displayName	string() — required	string().trim().min(1) — required	always present	agree. Stable adds trim + non-empty, and enforces per-connection uniqueness at runtime (assertDisplayNameAvailable); neither is a shape difference.
members	array(SCIMMemberReference).optional()	array(groupMemberSchema).max(1000).optional()	always an array ([] when empty)	agree on presence/optionality; stable caps at SCIM_MAX_GROUP_MEMBERS = 1000 (19). Element shape diverges — §2b.
meta	SCIMMetaSchema.optional()	absent — stripped on input	{resourceType, created, lastModified, location} (4915-4920)	input: missing-on-theirs (stripped, harmless). Output: meta.version is missing-on-theirs — spec declares an ETag field stable never emits, and stable's OpenAPI meta (87-101) omits it too.

2b. Group member

field	spec SCIMMemberReferenceSchema	stable — request groupMemberSchema (20-23)	stable — response (4925-4933)	verdict
value	string() — required	string().min(1) — required	present	agree.
$ref	string().url().optional()	absent — stripped	always emitted (Users URL)	missing-on-theirs (input only). Output agrees.
display	string().optional()	absent — stripped	always emitted	missing-on-theirs (input only). Output agrees.
type	enum(['User','Group']).optional()	string().refine(lower === 'user').optional()	always 'User'	⚠️ DIVERGENT — the one material row. Ours accepts 'Group'; stable rejects it.

2c. The type: 'Group' divergence is deliberate on stable, and doubly enforced

Not an oversight in the vendor's validator — stable guards it twice, on independent paths:

• groupMemberSchema.type — z.string().refine((type) => type.toLowerCase() === "user") (22).
• normalizeGroupMemberIds — re-checks after validation and throws BAD_REQUEST / scimType: "invalidValue", detail "Group members must reference a SCIM User" (4591-4601).
• Its advertised discovery schema agrees: members.type carries canonicalValues: ["User"] (175), and $ref carries referenceTypes: ["User"] (148).

RFC 7643 §4.2 defines members.type canonical values as "User" and "Group". So ours is RFC-faithful and stable deliberately narrows the RFC. Nested groups are a capability stable does not implement, not a field it forgot.

3. Executed, not just read

The stable half is an executed measurement, not an inference off the source. Payloads that are valid under SCIMGroupSchema were run through the body schema stable actually enforces on POST /scim/v2/Groups, reached via the real constructed plugin (plugin.endpoints.createSCIMGroup.options.body) on a standalone @better-auth/scim@1.7.1 install:

endpoint path: /scim/v2/Groups
body schema keys: schemas, externalId, displayName, members
declared models: scimConnectionBinding, scimIdentityTombstone, scimSubject, scimUser,
 scimProjectionGrant, scimGroup, scimGroupMember
---
A. minimal spec-valid group (displayName only) => ACCEPTED
B. spec members[].type "User" + $ref + display => ACCEPTED
 members[0] keys STRIPPED: $ref, display
C. spec-valid NESTED GROUP (members[].type: "Group") => REJECTED
 members.0.type: Invalid input
D. spec-valid extra schema URI ([Group, EnterpriseUser]) => REJECTED
 schemas.1: Invalid input: expected "...core:2.0:Group"
 schemas: schemas must contain only the core SCIM Group schema
E. spec-valid server-assigned fields on input (id + meta) => ACCEPTED
 top-level keys STRIPPED: id, meta

Cases C and D are the only two where a spec-valid payload is rejected rather than quietly trimmed. The ours-side half of C needs no new probe: it is already pinned green on main by packages/spec/src/identity/scim.test.ts:380 "should support nested groups", which asserts SCIMGroupSchema.parse accepts type: 'Group'.

Card premise confirmed: scimGroup and scimGroupMember are both present in stable's declared model list above — the kept-column reading holds.

⚠️ Byproduct, already tracked, filed nowhere new: scimProvider is absent from stable's seven declared models. The card's table lists only scimGroupRole/scimGroupRoleGrant as lost, but scimProvider is measurably gone from stable's schema too. That is #11693's object and its A-retirement ruling already covers it — recorded here only because this probe measured it directly and the epic's table reads as if it survived.

4. The spec seat's call — no movement

Does the diff force authorable-surface movement in packages/spec? No. Four reasons, in the order that decided it:

1. SCIMGroupSchema is not on any wire path. Repo-wide, its only references outside packages/spec itself are two documentation pages (content/docs/references/identity/scim.mdx, getting-started/quick-reference.mdx). Zero runtime consumers here, zero in objectui. Nothing in ObjectStack parses or emits a SCIM group payload through it; @better-auth/scim owns request validation, response serialization, OpenAPI and discovery end to end.
2. The two rejecting rows (C, D) are ours-looser-than-theirs. A looser declaration cannot break a stricter implementation — it can only fail to warn. No payload that ObjectStack produces today goes anywhere near either.
3. The remaining rows are input/output asymmetries, not disagreements. id, meta, $ref, display are all "present in ours, stripped on their input, emitted on their output" — the normal shape of a resource schema that describes both directions at once. Narrowing any of them would make the spec less able to describe a stable response, not more.
4. Nothing in the migration chain is blocked on a spec edit. The downstream legs need sys_scim_group / sys_scim_group_member platform objects (the storage layer §0 identified). That work reads better-auth's model shape, not SCIMGroupSchema.

A field add/rename with an obvious canonical answer would have been implemented in this PR per the dispatch contract. There isn't one: the only substantive row is a capability question, below.

5. The one fork — for the maintainer, not for this seat

Should SCIMMemberReferenceSchema.type keep accepting 'Group'?

The reason this is not a small unambiguous fix: it turns on what packages/spec's SCIM schemas are for, and the two readings give opposite answers.

• Option A — keep 'User' | 'Group' (status quo). Reads packages/spec as an RFC 7643 declaration: faithful to the standard, portable across any SCIM peer, and correct if ObjectStack ever fronts a different SCIM implementation. Cost: our published docs advertise a capability our own deployment answers with a 400.
• Option B — narrow to 'User'. Reads packages/spec as the contract our implementation honours: declared = enforced, and an author who writes a nested group is stopped at authoring time rather than at the IdP. Cost: a knowing divergence from RFC 7643 §4.2, plus retiring the pinned scim.test.ts:380 nested-group case, on a schema that is currently a pure declaration.

Four-axis read, since this is contract-shaping:

• Real business need — thin on both sides, and this is the axis that keeps the fork from being urgent. Measured: zero runtime consumers, zero example-app usage, docs-only exposure. Nobody is writing nested groups through this schema today because nobody is writing anything through it.
• Long-term soundness — favours B if the family is heading toward being the enforced contract, which SCIM: 停在 @better-auth/scim rc.1,等正式版再整体迁移 —— rc.2 换掉了整套模型 #3653's implement ruling suggests; favours A if spec stays a standards mirror. Genuinely undecided by anything on record.
• Making AI-authored metadata hard to get wrong — the strongest pull, and it favours B. SCIMGroup is published API surface with a rendered docs page; a generated app that reads type: 'User' | 'Group' will author nested groups and get invalidValue from the real endpoint. That is exactly the consumer-side tolerance that lets a generated error hide and spread.
• Startup scope discipline — favours deferring, not deciding. An unconsumed declaration is not earning the cost of a contract-review round today.

Recommendation: defer — take neither option in this leg. The divergence is latent, not live: it cannot bite until something routes group payloads through packages/spec, and no leg of #11632 does. The right moment to settle it is when a downstream leg first makes this schema load-bearing, because that leg's direction is the answer to "declaration or contract". If the maintainer wants it closed sooner, B is the one to take, on the AI-authoring axis alone — but it should land as its own Clause-② card with the RFC divergence written down, not as a rider on a measurement pass.

6. Disposition

Zero code, so no PR, no changeset, no gates owed. Nothing in packages/spec was touched, so no gate family is implicated by this leg. The local worktree is removed.

One piece of litter this seat could not clear: the branch claude/issue-11697-scim-group-parity was pushed empty as the standard write-routing probe and still sits on the remote at dce6a019f with zero commits — identical to main. Deleting it returns HTTP 403 from this seat (push is permitted, delete is not), so it is left for whoever has the permission. It carries no work and there is nothing to recover from it.

{
 "issue": 11697,
 "status": "done",
 "branch": "claude/issue-11697-scim-group-parity",
 "pr": null,
 "premise_still_valid": true,
 "summary": "Field-level parity pass between SCIMGroupSchema/SCIMMemberReferenceSchema and stable @better-auth/scim@1.7.1's group wire shape. Delivered as a measurement: full diff in this comment, both wire directions, cited to dist/index.mjs line numbers, with the stable half executed against a real constructed plugin rather than read off source. Result is ZERO CODE — the diff forces no authorable-surface movement. Of eleven field rows, nine agree or differ only as input/output asymmetries that strip harmlessly; two are ours-looser-than-theirs (schemas admits extra URIs; members[].type admits 'Group'), and a looser declaration cannot break a stricter implementation. Decisive context: SCIMGroupSchema has zero runtime consumers repo-wide and in objectui (docs pages only), and the gate's scimGroup/scimGroupMember are DATABASE models mapping onto absent platform objects, not onto this wire schema — a different layer, which is the mapping the card asked for.",
 "tests": "No build/test run and none owed: zero files changed, so no gate family is implicated (verified clean tree on branch at base dce6a019f). Measurement evidence instead: (1) executed probe — standalone npm install of @better-auth/scim@1.7.1 (shasum 715077319aeba4a35f114f7dfc2a8e0523aa9f6f), payloads valid under SCIMGroupSchema run through plugin.endpoints.createSCIMGroup.options.body on the real constructed plugin; node exit 0; verbatim output quoted in section 3 of this comment. Five cases: A/B/E ACCEPTED (B strips $ref+display, E strips id+meta), C REJECTED (members.0.type, nested group), D REJECTED (schemas.1, extra URI). (2) The ours-side half of case C needs no new probe — it is already pinned green on main by packages/spec/src/identity/scim.test.ts:380 'should support nested groups'. (3) Source cites: stable dist/index.mjs 20-29 (request), 4591-4601 (member guard), 4909-4938 (response), 109-186 (discovery); ours packages/spec/src/identity/scim.zod.ts 657-685, 693-741. No reverse verification leg exists because no assertion was written.",
 "open_questions": [
 {
 "question": "Should SCIMMemberReferenceSchema.type keep accepting 'Group'? Ours admits 'User' | 'Group' (RFC 7643 §4.2 canonical values); stable @better-auth/scim@1.7.1 rejects 'Group' twice over — zod refine at dist/index.mjs:22 and a BAD_REQUEST/invalidValue throw at 4594 — and advertises canonicalValues ['User'] in its own discovery document. Not a spelling fix: it turns on whether packages/spec's SCIM schemas are an RFC declaration or the contract our implementation enforces, and the two readings give opposite answers.",
 "options": [
 "A — keep 'User' | 'Group'. RFC-faithful and portable to any SCIM peer; cost is that published docs advertise a capability our own deployment answers with a 400.",
 "B — narrow to 'User'. declared = enforced, and a generated app is stopped at authoring time rather than by the IdP; cost is a knowing divergence from RFC 7643 §4.2 plus retiring the pinned nested-group case at scim.test.ts:380.",
 "C — defer until a downstream leg first makes this schema load-bearing; that leg's direction is itself the answer to 'declaration or contract'."
 ],
 "recommendation": "C (defer), with B as the answer if the maintainer wants it closed now. Four axes: real business need is thin both ways (zero runtime consumers measured, docs-only exposure) so nothing is urgent; long-term soundness is genuinely undecided by anything on record; making AI-authored metadata hard to get wrong is the strongest pull and favours B, since SCIMGroup is published API surface with a rendered docs page and a generated app reading 'User' | 'Group' will author nested groups and collect invalidValue from the real endpoint; startup scope discipline favours deferring, because an unconsumed declaration is not worth a contract-review round today. The divergence is latent, not live — it cannot bite until something routes group payloads through packages/spec, and no leg of #11632 does. If taken now, B belongs on its own Clause-② card with the RFC divergence recorded, not as a rider on a measurement pass."
 }
 ],
 "out_of_scope_findings": []
}

---

Generated by Claude Code

[os-warren]

Review + the spec seat's call (PM seat, session session_01Rxnd8cyFnoU8V5y21PaTsy): ACCEPT — zero authorable-surface movement; this card closes complete with the measurement as its deliverable.

• The field-level diff (comment 5399511853) is the deliverable the card asked for, and it is evidence-grade: both wire directions, cited to dist/index.mjs line numbers, with the stable half EXECUTED against a real constructed @better-auth/scim@1.7.1 plugin (npm pack shasum recorded) rather than read off source — five probe cases with verdicts quoted. The gate-name-to-spec-identifier mapping the card flagged is answered structurally: the parity gate's scimGroup/scimGroupMember are DATABASE models (mapping onto platform objects that don't ship), a different layer from SCIMGroupSchema's wire shape.
• Seat determination on the two divergent rows: both are ours-looser-than-theirs (extra schemas URIs; members[].type admitting 'Group'), and a looser declaration cannot break a stricter implementation — with zero runtime consumers measured, no schema movement is forced. The 'Group' declaration-vs-contract fork is adopted as the measurement recommends: deferred, and recorded so it survives this closure as finding finding: SCIMMemberReferenceSchema.type admits 'Group' (RFC 7643 §4.2) but stable @better-auth/scim rejects it twice over — declaration-vs-contract fork, latent (zero runtime consumers) #11820 (first-touch triage; option B, if ever taken, is its own Clause-② card).
• The write-routing branch claude/issue-11697-scim-group-parity remains on the remote at dce6a019f with zero commits (identical to main) — ref deletion 403s from agent seats (a known reading); it carries no work and is safe to delete whenever someone with ref-delete permission passes by.
• Byproduct evidence relayed to the epic: stable's declared model list, measured directly by the probe, does NOT include scimProvider — noted on [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 #11632 so the epic's gained/lost table can be corrected by its owner ([Decision] sys_scim_provider's disposition under the stable @better-auth/scim migration — the upstream model it mirrors no longer exists #11693 owns the disposition itself).

pm:dispatched comes off with this closure; domain:spec stays.

---

Generated by Claude Code