docs(plugin-auth): re-measure the version-stamped vendor attestations against the installed 1.7.1

[os-warren]

Fixes#10073

The ^1.7.1 bump moved the better-auth family past the versions these comments named, turning "verified against X" into claims nobody had checked. Every site below was re-measured against the installed packages and re-stamped with the version, the date, and the shipped file:line it was read out of — so the next reader can falsify it with one grep instead of trusting it.

Installed versions (read from node_modules, never from the range)

package	installed	note
better-auth	1.7.1	what ^1.7.1 resolves to
@better-auth/sso	1.7.1	dist/version-*.mjs self-reports PACKAGE_VERSION = "1.7.1"
@better-auth/oauth-provider	1.7.1
@better-auth/core	1.7.1
@better-auth/scim	1.7.0-rc.1	pinned exactly; not stale — comments naming 1.7.0-rc.1 are current

Measured 2026-08-20. Every class-(a) claim's substance still holds at 1.7.1; none was found false. Details per site below.

This is not a find-and-replace — 32 hits, three dispositions

The raw scan finds 32 lines (not 29 — reconciled at the bottom). They are not interchangeable:

Re-stamped — 20 sites. Live claims about the current pin, each re-measured:

site	what was re-measured, at 1.7.1
session-tombstone.ts:34	endPreservedSessions at dist/db/internal-adapter.mjs:41, still deleteManyWithHooks(..., { fn, executeMainFn: false }) gated on secondaryStorage
session-tombstone.ts (hooks bullet)	dist/db/with-hooks.mjs:132 — a delete.before returning false does return null ahead of the delete.after loop at :140
session-tombstone.ts:83	no sweeper (setInterval only in two client-side dist files); sole expiry GC at dist/api/routes/session.mjs:146-157
session-tombstone.test.ts:296	same GC
sso-client-secret.ts:24	all 14 SSOOptions top-level members enumerated — none concerns secret storage
sso-client-secret-at-rest.test.ts:25	oidcMappingSchema at dist/index.mjs:1852, z.strictObject, no id
remove-member-permission-guard.ts:10 + .test.ts:8	crud-members.mjs — (3a) :196, (3b) :197-200, hasPermission:202-207, still ordered after
register-sso-provider.ts:130	oidcMappingSchema strict, email/name required, no id
register-sso-provider.test.ts:50	augmented, not re-stamped — see below
impersonation-bearer-rotation.ts:11	dist/plugins/bearer/index.mjs:46
member-role-canonical.ts:14 + .test.ts:25	three raw role.split(",") branches at :193, :288, :420
managed-extension-fields.test.ts:186 + :918	no ./plugins/api-key subpath; apiKey === undefined (counter-checked: bearer/admin are functions in the same import)
auth-manager.ts:1084	changeEmail declares exactly 3 members
change-email-delete-user-wiring.test.ts:507	update-user.mjs branch :496, returns :505
auth-manager.ts:3606	deleteUser:233-247, three calls, zero transaction occurrences
adopt-membership.ts:40	crud-invites.mjs — createMember unconditional :324, rollback :332-339
objectql-adapter.ts:243	see "more than a number" below
auth-schema-config.ts:917	the field-surface measurement — see below

Left exactly as written — 7 sites, deliberately historical. Rewriting them destroys information:

admin-user-endpoints.ts:70 (the rc.2/stable accountId contrast) · auth-schema-config.ts:107 and :472 (rename narratives) · register-sso-provider.ts:138 and :140 (when the id member was retired) · objectql-adapter.test.ts:92 · revoke-session-match-guard.ts:11.

That last one is worth flagging: the card listed it under category (a), but it has already been re-stamped to 1.7.1 by the #9714/#10069 work that landed on this surface since the card was filed. Its 1.7.0-rc.2 mention is now historical provenance inside a current attestation. Cutting from the post-19f98fa1f tree is what made that visible.

Already corrected by #10072 — 5 sites, which name the stamp they superseded (that naming is what makes the correction auditable): better-auth-schema-parity.test.ts:51 · auth-schema-config.ts:970 · auth-manager.ts:2792 and :2795 · objectql-adapter.test.ts:309.

Two sites needed more than a new number

objectql-adapter.ts called the dependency a prerelease. 1.7.1 is a stable release, so that half of the reason is deleted, not re-stamped — re-stamping it would have preserved a now-false premise behind a fresh-looking date. The half that still carries the argument (a vendor dist internal, invisible to any published type, not covering the raw-adapter path) is kept and re-anchored at the corrected lines :127,146,602,615 — the old :120,139,594,607 were rc.2's.

auth-manager.ts cited @better-auth/core/src/types/init-options.ts:946-971. No src/ is published, so nobody reading it could have checked it. Re-pointed at the shipped dist/types/init-options.d.mts:835-857.

The field-surface claim (auth-schema-config.ts:917) — measured, not re-stamped

It said only "Mirrors @better-auth/sso@1.6.20's BaseSSOProvider" — a claim about a version two minors behind the installed one that had never been checked. Measured by resolving the model the way the adapter does (field.fieldName ?? key) over getAuthTables({ plugins: [sso()] }):

• sso() declares 7 fields — exactly the members of the shipped BaseSSOProvider (dist/index-CZytzKv6.d.mts:189-197).
• sso({ domainVerification: { enabled: true } }) adds an 8th, domainVerified.
• All 8 resolve to columns sys_sso_provider declares. Nothing orphaned, nothing unmapped.

The claim is true at 1.7.1. Recorded along with the gap that makes it worth re-checking: this mapping has no parity gate, because better-auth-schema-parity.test.ts deliberately passes getAuthTables() no sso plugin.

Verification

Comment-only: no assertion, pin or gate input is touched — proven by filtering the diff for any added or removed line that is not comment text or blank (none). The one edit inside a string literal (managed-extension-fields.test.ts's reason: field) is documentation-only data: nothing asserts its content or length, only entry.skip.length is length-checked and that is a different field. An ablation therefore does not apply — there is no assertion here that could be made to fail, and staging one would be theatre.

Gate union derived at f1517dca2 on a clean worktree via node scripts/pm/dispatch-gates.mjs (no paths passed), exit codes captured before any pipe, each quoted from the gate's own verdict line:

• check:nul-bytes — OK (scanned 6066 text file(s) ... no raw ASCII control bytes)
• check:slot-lookup — ratchet holds: 107 unswept site(s) ... none new · baseline key set verified against 19f98fa: no files added
• check:test-source-alias — OK — 72 packages with tests scanned
• check:type-source-resolution — OK — 76 packages with a tsconfig.json scanned
• check:query-options-erasure — ratchet holds: 67 unswept non-test site(s) ... none new · no files added
• check:engine-double-contract — OK — 329 pinned, 133 in the DEBT ledger, 2 exempt
• check:where-matcher — conformance holds: 264 matcher(s) ... none new · no files added
• check:type-check-coverage — OK — 64/77 workspace packages type-checked ... 13 in the DEBT ledger
• check-affected-docs.mjs — exit 0
• pnpm --filter @objectstack/plugin-auth test — Test Files 60 passed (60) · Tests 1335 passed (1335)
• pnpm --filter @objectstack/plugin-auth typecheck — tsc --noEmit, exit 0 (script name echoed, so not a zero-match silent pass)

Declared narrowing:check:type-check-debt --re-measure was not run locally — it requires the full built workspace closure. It is provably immovable by this diff: it re-measures tsc error counts, comment text is invisible to tsc except through directives, and the diff adds and removes zerots-expect-error/ts-ignore/ts-nocheck lines (counter-checked — the same pattern matches real instances in packages/types/src/response-envelope.test.ts:123). CI runs it regardless.

Final sweep, counter-checked. 16 1.7.0-rc.2/1.6.20 hits remain; every one is deliberately-historical, an already-corrected #10072 site, or new prose naming the stamp it replaced. Zero live or unmeasured stamps remain. The zero is meaningful because the same grep machinery finds 1.7.1 in 27 files in the same tree.

skip-changeset: this PR releases nothing — comment text only, stripped from every build artifact.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

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

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

• content/docs/kernel/contracts/auth-service.mdx(via handleRequest (symbol))
• content/docs/permissions/authentication.mdx(via handleRequest (symbol))

What this run could not see

• 7 changed file(s) yielded no anchor (packages/plugins/plugin-auth/src/adopt-membership.ts, packages/plugins/plugin-auth/src/auth-schema-config.ts, packages/plugins/plugin-auth/src/impersonation-bearer-rotation.ts, …) — pages documenting those are invisible to this run
• the SDK route bridge reached 45 of 221 client-bound route-ledger rows — the other 176 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run: node scripts/docs-audit/affected-docs.mjs --bridge-coverage

Coarse fallback — 11 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 da891e0efd620f83c6b2499537029e9d2e5ebf66 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 0fcc61ae912ef8805642e9ae1837eb17969b5b47 — the merge of head f1517dca26a1f8b0c0d9d8b3689b9e1a58040b14 into base da891e0efd620f83c6b2499537029e9d2e5ebf66, 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 0fcc61ae912ef8805642e9ae1837eb17969b5b47 && git checkout 0fcc61ae912ef8805642e9ae1837eb17969b5b47
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin da891e0efd620f83c6b2499537029e9d2e5ebf66 f1517dca26a1f8b0c0d9d8b3689b9e1a58040b14 && git checkout -B drift-repro da891e0efd620f83c6b2499537029e9d2e5ebf66 && git merge --no-ff f1517dca26a1f8b0c0d9d8b3689b9e1a58040b14
node scripts/docs-audit/affected-docs.mjs --json da891e0efd620f83c6b2499537029e9d2e5ebf66

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