feat(plugin-auth): auth mail follows the caller's Accept-Language, deployment default second

[hotlong]

Fixes#14319

Second and final PR for this card. #14591 landed the deployment rung; this one lands
the rung above it, on the maintainer's 2026-09-02 ruling.

The ruling

Maintainer, 2026-09-02, in session. Quoted verbatim and untranslated, as rulings are:

注册 / 登录 / 重置密码等由请求触发的 auth 邮件，语言优先取请求的 Accept-Language（命中
AUTH_EMAIL_TEMPLATE_LOCALES 才生效），其次才是 PR #14591 确立的部署默认
（localization.locale → i18n.defaultLocale）。这翻转了 2026-08-13「拒绝
Accept-Language」的裁决。

The motivating case is the one no deployment default can answer: at cloud self-service
signup there is no workspace yet, so nothing on the server represents that person's
language. A Chinese browser reached a Chinese signup screen and got an English
verification email.

What changed

The locale is now a two-rung ladder resolved at send time in AuthManager:

1. the caller's own Accept-Language, when it names a locale in AUTH_EMAIL_TEMPLATE_LOCALES;
2. the deployment default (localization.locale, then i18n.defaultLocale);
3. nothing named, which is EmailService's documented en-US.

The header is parsed by the platform's existing preferredLocaleFromHeader — the one
function REST already uses for metadata translation and the runtime dispatcher for
ExecutionContext.requestLocale. A second parser here would let the mail disagree with
the screen that triggered it, which is the class of defect this card is about.

The hit requirement is the ruling's, and it is load-bearing: fr-FR falls through to the
deployment default rather than naming a row that does not exist. That is deliberately
narrower than normalizeAuthEmailLocale, which passes unshipped regional tags through
because a tenant may overlay en-GB rows and a deployment default may legitimately ask
for them. A per-request header is a weaker claim than a deployment's declaration.

Two exclusions, one of them a judgement call worth reviewing

Per-user language stays deferred. No sys_user column is added. The 2026-09-02 ruling
keeps that half deferred and this PR does not touch it.

Invitations deliberately do NOT take the request rung — please check this reading.
better-auth hands sendInvitationEmail a ctx.request like the others, so wiring it was
available and was declined. That request is the inviter's: stamping their browser
language onto the invitee's mail would reproduce this very card one seat over. The
2026-09-02 ruling enumerates signup, sign-in and password reset — sends where the requester
IS the recipient — and the superseded 2026-08-13 ruling named invitations as its own
counterexample. So invitees keep the deployment default until a per-user language exists to
read. The abstention is commented at the call site rather than left as an omission. If the
maintainer reads the ruling's 等 as covering invitations too, it is a one-argument change.

The other four sends all have requester == recipient, including the change-email notice,
which goes to the account's current address, i.e. to the person who just asked to change it.

Vendor seam, measured rather than assumed

better-auth is not consistent about what it passes these callbacks. Measured against the
installed 1.7.x, not inferred from docs:

callback	second argument
sendResetPassword	ctx.request — a Web Request
sendVerificationEmail	ctx.request (and safeCloneRequest(ctx.request) on one path)
sendInvitationEmail	ctx.request
sendMagicLink	the endpoint ctx, not a Request
change-email notice	fires from the global after hook, which holds a ctx

One reader covers all three shapes, and it never throws: a vendor changing the shape it
hands a callback must degrade to the deployment default, never fail a send.

One story, not two

The 2026-08-13 ruling is rewritten wherever it was recorded, marked superseded, with its
original date and reasoning preserved: AuthManager.setDefaultEmailLocale holds the single
history record, and auth-plugin.ts plus auth-email-locale.test.ts point at it instead of
restating it. The old reasoning did not simply lose — it is exactly why the request rung is
scoped to requester-is-recipient sends, and that is said where the invitation abstains.

Tests

13 new cases in auth-email-locale.test.ts. The three the dispatch asked for — a zh-CN
caller gets zh-CN; an absent header falls back to the deployment default; a locale we ship
no row for (fr-FR, de, pt-BR, *) falls back — plus: ja-JP / es-ES / en-US
callers; both rungs silent leaves the key absent rather than en-US, because that is
what the ladder's contract is written against; the invitation abstention; payload
non-disturbance; and unit cases for the reader across a Request, an endpoint ctx, both
header-bag spellings, bare-language promotion, and a header bag that throws.

Locale is what this layer outputs, so locale is what is asserted. That a zh-CN row then
renders a Chinese subject carrying no en-US text is plugin-email/src/auth-templates-locales.test.ts,
which owns the row half; the two together are the card's acceptance criterion.

Reverse verification. Rather than reverting the whole file — which would have failed the
import and produced a red that proves nothing — the mutation was surgical: the one
load-bearing line, authEmailLocaleFromRequest(requestSource) ?? this.emailLocale, was
replaced by this.emailLocale alone, keeping the exported helper so the red would be
behavioural. Direction: RED, and discriminating — 4 failed | 26 passed, the four being
exactly the request-precedence cases (expected 'zh-CN' to be 'en-US'), while the fallback
cases and every unit case stayed green. A blanket red would have meant the tests were not
isolating the rung. Mutation confirmed on disk by blob hash and anchor counts, not by an
editor exit code: HEAD blob d0d15b92, mutated blob 4d642984, injected anchor present 1x
and deleted anchor 0x. Restore confirmed byte-identical afterwards: worktree blob back to
d0d15b92, git diff HEAD empty, git status --porcelain empty; the restore leg ran from a
trap ... EXIT INT TERM with absolute paths from git rev-parse --show-toplevel. No rebuild
was needed for either leg and none is claimed: the suite imports ./auth-manager as source,
so no dist/ sits between the mutation and the assertion.

Gates — run at cdf2c3c3d

• pnpm --filter '@objectstack/plugin-auth^...' build — VERDICT command-exit 0
• pnpm --filter @objectstack/plugin-auth test — Test Files 90 passed, Tests 1849 passed
• pnpm --filter @objectstack/plugin-auth typecheck — exit 0;
  check:test-typecheck: OK ... 10 file(s) / 94 error(s) / 23 pinned signature(s) — ledger
  unchanged, no new test-layer debt
• node scripts/check-nul-bytes.mjs — OK (scanned 7977 text file(s) ... no raw ASCII control bytes)
• 62 derived families run (dispatch-gates.mjs --repo objectstack-ai/objectstack, no paths
  passed). The first derivation gave 38; repairing the census below added content/docs/**, and
  the re-derivation returned 62, so the 24 doc families were run too.
• pnpm check:type-check-coverage --re-measure — OK — 22 ledger entr(ies) re-measured in 137.6s, 755 raw tsc error(s) total, none above its recorded number
• pnpm check:skill-examples — 261 prose examples type-check across 3 surface(s)
• pnpm check:dual-build-cjs-loads — exit 0, floors held

Those three refuse to answer on an unbuilt tree rather than green-lighting one;
turbo run build --filter='./packages/*' --filter='./packages/*/*' ran 71/71 successful and
all three then measured green.

One real gate finding, repaired.check-system-context-census went red on pure line rot —
this PR's comments moved an elevation read in auth-plugin.ts from line 1301 to 1310,
orphaning the anchor. Repaired with the script's own --fix (exactly one anchor rewritten),
after which: OK — 109 elevation read sites in 20 packages across 45 files, all anchored; 145 anchors resolve, 27 declared non-read.

Two families NOT MEASURED locally, by their own verdict text — neither is a red.
check-test-completeness exits 3 asking for a saved turbo run test log and instructs a local
family run to record NOT MEASURED; check-half-states exits 3 as an unread instrument on this
host. Both are CI's.

Expected conflict with #14591

#14591 was still open at push time, so this branch is cut from main without it. Two
overlapping regions, both mechanical:

• auth-plugin.ts — the same #8195 comment block. fix(plugin-auth): bind the auth email locale to the workspace language, not the build-time default #14591 rewrites it to describe the
  localization.locale precedence; this PR rewrites it to say the block binds the second
  rung. Intended resolution: keep both — fix(plugin-auth): bind the auth email locale to the workspace language, not the build-time default #14591's precedence text, plus this PR's "this is
  the second rung, the request rung lives in AuthManager" framing and its instruction not to
  restore the superseded reading.
• content/docs/permissions/system-context.mdx line 100 — the same census anchor, moved to
  1345 by fix(plugin-auth): bind the auth email locale to the workspace language, not the build-time default #14591 and to 1310 here. Intended resolution: neither number; re-run
  node scripts/check-system-context-census.mjs --fix on the merged tree and take what it
  writes. The number is derived, so hand-picking a side is guesswork.

Declared narrowing — verification ran UNLOCKED.scripts/pm/os-verify-lock.sh
could not take the shared verify lock on this host: no usable flock. The shared
verify lock is declared Linux-only (flock is util-linux, and a stock macOS does
not ship it), so the commands above were run directly, without the lock —
a declared narrowing, not a silent one. No serialization guarantee held for these
runs, nor for any sibling agent in this container while they ran.

Repo-wide pnpm lint was not run; it is CI's, and no narrowing of it is claimed here.

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

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

3 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 AuthManager (symbol, a top-level class))
• content/docs/kernel/services-checklist.mdx(via AuthManager (symbol, a top-level class))
• content/docs/permissions/authentication.mdx(via AuthManager (symbol, a top-level class))

What this run could not see

• 1 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 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.

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 13bf05d3fe8b1795f3f5aee7daf29ee217590ab9 → packageMentionDocs.

Which tree this was computed on

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

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

[hotlong]

Fixes#14319

Second and final PR for this card. #14591 landed the deployment rung; this one lands
the rung above it, on the maintainer's 2026-09-02 ruling.

The ruling

Maintainer, 2026-09-02, in session. Quoted verbatim and untranslated, as rulings are:

注册 / 登录 / 重置密码等由请求触发的 auth 邮件，语言优先取请求的 Accept-Language（命中
AUTH_EMAIL_TEMPLATE_LOCALES 才生效），其次才是 PR #14591 确立的部署默认
（localization.locale → i18n.defaultLocale）。这翻转了 2026-08-13「拒绝
Accept-Language」的裁决。

The motivating case is the one no deployment default can answer: at cloud self-service
signup there is no workspace yet, so nothing on the server represents that person's
language. A Chinese browser reached a Chinese signup screen and got an English
verification email.

What changed

The locale is now a two-rung ladder resolved at send time in AuthManager:

1. the caller's own Accept-Language, when it names a locale in AUTH_EMAIL_TEMPLATE_LOCALES;
2. the deployment default (localization.locale, then i18n.defaultLocale);
3. nothing named, which is EmailService's documented en-US.

The header is parsed by the platform's existing preferredLocaleFromHeader — the one
function REST already uses for metadata translation and the runtime dispatcher for
ExecutionContext.requestLocale. A second parser here would let the mail disagree with
the screen that triggered it, which is the class of defect this card is about.

The hit requirement is the ruling's, and it is load-bearing: fr-FR falls through to the
deployment default rather than naming a row that does not exist. That is deliberately
narrower than normalizeAuthEmailLocale, which passes unshipped regional tags through
because a tenant may overlay en-GB rows and a deployment default may legitimately ask
for them. A per-request header is a weaker claim than a deployment's declaration.

Two exclusions, one of them a judgement call worth reviewing

Per-user language stays deferred. No sys_user column is added. The 2026-09-02 ruling
keeps that half deferred and this PR does not touch it.

Invitations deliberately do NOT take the request rung — please check this reading.
better-auth hands sendInvitationEmail a ctx.request like the others, so wiring it was
available and was declined. That request is the inviter's: stamping their browser
language onto the invitee's mail would reproduce this very card one seat over. The
2026-09-02 ruling enumerates signup, sign-in and password reset — sends where the requester
IS the recipient — and the superseded 2026-08-13 ruling named invitations as its own
counterexample. So invitees keep the deployment default until a per-user language exists to
read. The abstention is commented at the call site rather than left as an omission. If the
maintainer reads the ruling's 等 as covering invitations too, it is a one-argument change.

The other four sends all have requester == recipient, including the change-email notice,
which goes to the account's current address, i.e. to the person who just asked to change it.

Vendor seam, measured rather than assumed

better-auth is not consistent about what it passes these callbacks. Measured against the
installed 1.7.x, not inferred from docs:

callback	second argument
sendResetPassword	ctx.request — a Web Request
sendVerificationEmail	ctx.request (and safeCloneRequest(ctx.request) on one path)
sendInvitationEmail	ctx.request
sendMagicLink	the endpoint ctx, not a Request
change-email notice	fires from the global after hook, which holds a ctx

One reader covers all three shapes, and it never throws: a vendor changing the shape it
hands a callback must degrade to the deployment default, never fail a send.

One story, not two

The 2026-08-13 ruling is rewritten wherever it was recorded, marked superseded, with its
original date and reasoning preserved: AuthManager.setDefaultEmailLocale holds the single
history record, and auth-plugin.ts plus auth-email-locale.test.ts point at it instead of
restating it. The old reasoning did not simply lose — it is exactly why the request rung is
scoped to requester-is-recipient sends, and that is said where the invitation abstains.

Tests

13 new cases in auth-email-locale.test.ts. The three the dispatch asked for — a zh-CN
caller gets zh-CN; an absent header falls back to the deployment default; a locale we ship
no row for (fr-FR, de, pt-BR, *) falls back — plus: ja-JP / es-ES / en-US
callers; both rungs silent leaves the key absent rather than en-US, because that is
what the ladder's contract is written against; the invitation abstention; payload
non-disturbance; and unit cases for the reader across a Request, an endpoint ctx, both
header-bag spellings, bare-language promotion, and a header bag that throws.

Locale is what this layer outputs, so locale is what is asserted. That a zh-CN row then
renders a Chinese subject carrying no en-US text is plugin-email/src/auth-templates-locales.test.ts,
which owns the row half; the two together are the card's acceptance criterion.

Reverse verification. Rather than reverting the whole file — which would have failed the
import and produced a red that proves nothing — the mutation was surgical: the one
load-bearing line, authEmailLocaleFromRequest(requestSource) ?? this.emailLocale, was
replaced by this.emailLocale alone, keeping the exported helper so the red would be
behavioural. Direction: RED, and discriminating — 4 failed | 26 passed, the four being
exactly the request-precedence cases (expected 'zh-CN' to be 'en-US'), while the fallback
cases and every unit case stayed green. A blanket red would have meant the tests were not
isolating the rung. Mutation confirmed on disk by blob hash and anchor counts, not by an
editor exit code: HEAD blob d0d15b92, mutated blob 4d642984, injected anchor present 1x
and deleted anchor 0x. Restore confirmed byte-identical afterwards: worktree blob back to
d0d15b92, git diff HEAD empty, git status --porcelain empty; the restore leg ran from a
trap ... EXIT INT TERM with absolute paths from git rev-parse --show-toplevel. No rebuild
was needed for either leg and none is claimed: the suite imports ./auth-manager as source,
so no dist/ sits between the mutation and the assertion.

Gates — run at cdf2c3c3d

• pnpm --filter '@objectstack/plugin-auth^...' build — VERDICT command-exit 0
• pnpm --filter @objectstack/plugin-auth test — Test Files 90 passed, Tests 1849 passed
• pnpm --filter @objectstack/plugin-auth typecheck — exit 0;
  check:test-typecheck: OK ... 10 file(s) / 94 error(s) / 23 pinned signature(s) — ledger
  unchanged, no new test-layer debt
• node scripts/check-nul-bytes.mjs — OK (scanned 7977 text file(s) ... no raw ASCII control bytes)
• 62 derived families run (dispatch-gates.mjs --repo objectstack-ai/objectstack, no paths
  passed). The first derivation gave 38; repairing the census below added content/docs/**, and
  the re-derivation returned 62, so the 24 doc families were run too.
• pnpm check:type-check-coverage --re-measure — OK — 22 ledger entr(ies) re-measured in 137.6s, 755 raw tsc error(s) total, none above its recorded number
• pnpm check:skill-examples — 261 prose examples type-check across 3 surface(s)
• pnpm check:dual-build-cjs-loads — exit 0, floors held

Those three refuse to answer on an unbuilt tree rather than green-lighting one;
turbo run build --filter='./packages/*' --filter='./packages/*/*' ran 71/71 successful and
all three then measured green.

One real gate finding, repaired.check-system-context-census went red on pure line rot —
this PR's comments moved an elevation read in auth-plugin.ts from line 1301 to 1310,
orphaning the anchor. Repaired with the script's own --fix (exactly one anchor rewritten),
after which: OK — 109 elevation read sites in 20 packages across 45 files, all anchored; 145 anchors resolve, 27 declared non-read.

Two families NOT MEASURED locally, by their own verdict text — neither is a red.
check-test-completeness exits 3 asking for a saved turbo run test log and instructs a local
family run to record NOT MEASURED; check-half-states exits 3 as an unread instrument on this
host. Both are CI's.

Expected conflict with #14591

#14591 was still open at push time, so this branch is cut from main without it. Two
overlapping regions, both mechanical:

• auth-plugin.ts — the same #8195 comment block. fix(plugin-auth): bind the auth email locale to the workspace language, not the build-time default #14591 rewrites it to describe the
  localization.locale precedence; this PR rewrites it to say the block binds the second
  rung. Intended resolution: keep both — fix(plugin-auth): bind the auth email locale to the workspace language, not the build-time default #14591's precedence text, plus this PR's "this is
  the second rung, the request rung lives in AuthManager" framing and its instruction not to
  restore the superseded reading.
• content/docs/permissions/system-context.mdx line 100 — the same census anchor, moved to
  1345 by fix(plugin-auth): bind the auth email locale to the workspace language, not the build-time default #14591 and to 1310 here. Intended resolution: neither number; re-run
  node scripts/check-system-context-census.mjs --fix on the merged tree and take what it
  writes. The number is derived, so hand-picking a side is guesswork.

Declared narrowing — verification ran UNLOCKED.scripts/pm/os-verify-lock.sh
could not take the shared verify lock on this host: no usable flock. The shared
verify lock is declared Linux-only (flock is util-linux, and a stock macOS does
not ship it), so the commands above were run directly, without the lock —
a declared narrowing, not a silent one. No serialization guarantee held for these
runs, nor for any sibling agent in this container while they ran.

Repo-wide pnpm lint was not run; it is CI's, and no narrowing of it is claimed here.

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

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

3 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 AuthManager (symbol, a top-level class))
• content/docs/kernel/services-checklist.mdx(via AuthManager (symbol, a top-level class))
• content/docs/permissions/authentication.mdx(via AuthManager (symbol, a top-level class))

What this run could not see

• 1 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 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.

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 13bf05d3fe8b1795f3f5aee7daf29ee217590ab9 → packageMentionDocs.

Which tree this was computed on

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

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

[hotlong]

Fixes#14319

Second and final PR for this card. #14591 landed the deployment rung; this one lands
the rung above it, on the maintainer's 2026-09-02 ruling.

The ruling

Maintainer, 2026-09-02, in session. Quoted verbatim and untranslated, as rulings are:

注册 / 登录 / 重置密码等由请求触发的 auth 邮件，语言优先取请求的 Accept-Language（命中
AUTH_EMAIL_TEMPLATE_LOCALES 才生效），其次才是 PR #14591 确立的部署默认
（localization.locale → i18n.defaultLocale）。这翻转了 2026-08-13「拒绝
Accept-Language」的裁决。

The motivating case is the one no deployment default can answer: at cloud self-service
signup there is no workspace yet, so nothing on the server represents that person's
language. A Chinese browser reached a Chinese signup screen and got an English
verification email.

What changed

The locale is now a two-rung ladder resolved at send time in AuthManager:

1. the caller's own Accept-Language, when it names a locale in AUTH_EMAIL_TEMPLATE_LOCALES;
2. the deployment default (localization.locale, then i18n.defaultLocale);
3. nothing named, which is EmailService's documented en-US.

The header is parsed by the platform's existing preferredLocaleFromHeader — the one
function REST already uses for metadata translation and the runtime dispatcher for
ExecutionContext.requestLocale. A second parser here would let the mail disagree with
the screen that triggered it, which is the class of defect this card is about.

The hit requirement is the ruling's, and it is load-bearing: fr-FR falls through to the
deployment default rather than naming a row that does not exist. That is deliberately
narrower than normalizeAuthEmailLocale, which passes unshipped regional tags through
because a tenant may overlay en-GB rows and a deployment default may legitimately ask
for them. A per-request header is a weaker claim than a deployment's declaration.

Two exclusions, one of them a judgement call worth reviewing

Per-user language stays deferred. No sys_user column is added. The 2026-09-02 ruling
keeps that half deferred and this PR does not touch it.

Invitations deliberately do NOT take the request rung — please check this reading.
better-auth hands sendInvitationEmail a ctx.request like the others, so wiring it was
available and was declined. That request is the inviter's: stamping their browser
language onto the invitee's mail would reproduce this very card one seat over. The
2026-09-02 ruling enumerates signup, sign-in and password reset — sends where the requester
IS the recipient — and the superseded 2026-08-13 ruling named invitations as its own
counterexample. So invitees keep the deployment default until a per-user language exists to
read. The abstention is commented at the call site rather than left as an omission. If the
maintainer reads the ruling's 等 as covering invitations too, it is a one-argument change.

The other four sends all have requester == recipient, including the change-email notice,
which goes to the account's current address, i.e. to the person who just asked to change it.

Vendor seam, measured rather than assumed

better-auth is not consistent about what it passes these callbacks. Measured against the
installed 1.7.x, not inferred from docs:

callback	second argument
sendResetPassword	ctx.request — a Web Request
sendVerificationEmail	ctx.request (and safeCloneRequest(ctx.request) on one path)
sendInvitationEmail	ctx.request
sendMagicLink	the endpoint ctx, not a Request
change-email notice	fires from the global after hook, which holds a ctx

One reader covers all three shapes, and it never throws: a vendor changing the shape it
hands a callback must degrade to the deployment default, never fail a send.

One story, not two

The 2026-08-13 ruling is rewritten wherever it was recorded, marked superseded, with its
original date and reasoning preserved: AuthManager.setDefaultEmailLocale holds the single
history record, and auth-plugin.ts plus auth-email-locale.test.ts point at it instead of
restating it. The old reasoning did not simply lose — it is exactly why the request rung is
scoped to requester-is-recipient sends, and that is said where the invitation abstains.

Tests

13 new cases in auth-email-locale.test.ts. The three the dispatch asked for — a zh-CN
caller gets zh-CN; an absent header falls back to the deployment default; a locale we ship
no row for (fr-FR, de, pt-BR, *) falls back — plus: ja-JP / es-ES / en-US
callers; both rungs silent leaves the key absent rather than en-US, because that is
what the ladder's contract is written against; the invitation abstention; payload
non-disturbance; and unit cases for the reader across a Request, an endpoint ctx, both
header-bag spellings, bare-language promotion, and a header bag that throws.

Locale is what this layer outputs, so locale is what is asserted. That a zh-CN row then
renders a Chinese subject carrying no en-US text is plugin-email/src/auth-templates-locales.test.ts,
which owns the row half; the two together are the card's acceptance criterion.

Reverse verification. Rather than reverting the whole file — which would have failed the
import and produced a red that proves nothing — the mutation was surgical: the one
load-bearing line, authEmailLocaleFromRequest(requestSource) ?? this.emailLocale, was
replaced by this.emailLocale alone, keeping the exported helper so the red would be
behavioural. Direction: RED, and discriminating — 4 failed | 26 passed, the four being
exactly the request-precedence cases (expected 'zh-CN' to be 'en-US'), while the fallback
cases and every unit case stayed green. A blanket red would have meant the tests were not
isolating the rung. Mutation confirmed on disk by blob hash and anchor counts, not by an
editor exit code: HEAD blob d0d15b92, mutated blob 4d642984, injected anchor present 1x
and deleted anchor 0x. Restore confirmed byte-identical afterwards: worktree blob back to
d0d15b92, git diff HEAD empty, git status --porcelain empty; the restore leg ran from a
trap ... EXIT INT TERM with absolute paths from git rev-parse --show-toplevel. No rebuild
was needed for either leg and none is claimed: the suite imports ./auth-manager as source,
so no dist/ sits between the mutation and the assertion.

Gates — run at cdf2c3c3d

• pnpm --filter '@objectstack/plugin-auth^...' build — VERDICT command-exit 0
• pnpm --filter @objectstack/plugin-auth test — Test Files 90 passed, Tests 1849 passed
• pnpm --filter @objectstack/plugin-auth typecheck — exit 0;
  check:test-typecheck: OK ... 10 file(s) / 94 error(s) / 23 pinned signature(s) — ledger
  unchanged, no new test-layer debt
• node scripts/check-nul-bytes.mjs — OK (scanned 7977 text file(s) ... no raw ASCII control bytes)
• 62 derived families run (dispatch-gates.mjs --repo objectstack-ai/objectstack, no paths
  passed). The first derivation gave 38; repairing the census below added content/docs/**, and
  the re-derivation returned 62, so the 24 doc families were run too.
• pnpm check:type-check-coverage --re-measure — OK — 22 ledger entr(ies) re-measured in 137.6s, 755 raw tsc error(s) total, none above its recorded number
• pnpm check:skill-examples — 261 prose examples type-check across 3 surface(s)
• pnpm check:dual-build-cjs-loads — exit 0, floors held

Those three refuse to answer on an unbuilt tree rather than green-lighting one;
turbo run build --filter='./packages/*' --filter='./packages/*/*' ran 71/71 successful and
all three then measured green.

One real gate finding, repaired.check-system-context-census went red on pure line rot —
this PR's comments moved an elevation read in auth-plugin.ts from line 1301 to 1310,
orphaning the anchor. Repaired with the script's own --fix (exactly one anchor rewritten),
after which: OK — 109 elevation read sites in 20 packages across 45 files, all anchored; 145 anchors resolve, 27 declared non-read.

Two families NOT MEASURED locally, by their own verdict text — neither is a red.
check-test-completeness exits 3 asking for a saved turbo run test log and instructs a local
family run to record NOT MEASURED; check-half-states exits 3 as an unread instrument on this
host. Both are CI's.

Expected conflict with #14591

#14591 was still open at push time, so this branch is cut from main without it. Two
overlapping regions, both mechanical:

• auth-plugin.ts — the same #8195 comment block. fix(plugin-auth): bind the auth email locale to the workspace language, not the build-time default #14591 rewrites it to describe the
  localization.locale precedence; this PR rewrites it to say the block binds the second
  rung. Intended resolution: keep both — fix(plugin-auth): bind the auth email locale to the workspace language, not the build-time default #14591's precedence text, plus this PR's "this is
  the second rung, the request rung lives in AuthManager" framing and its instruction not to
  restore the superseded reading.
• content/docs/permissions/system-context.mdx line 100 — the same census anchor, moved to
  1345 by fix(plugin-auth): bind the auth email locale to the workspace language, not the build-time default #14591 and to 1310 here. Intended resolution: neither number; re-run
  node scripts/check-system-context-census.mjs --fix on the merged tree and take what it
  writes. The number is derived, so hand-picking a side is guesswork.

Declared narrowing — verification ran UNLOCKED.scripts/pm/os-verify-lock.sh
could not take the shared verify lock on this host: no usable flock. The shared
verify lock is declared Linux-only (flock is util-linux, and a stock macOS does
not ship it), so the commands above were run directly, without the lock —
a declared narrowing, not a silent one. No serialization guarantee held for these
runs, nor for any sibling agent in this container while they ran.

Repo-wide pnpm lint was not run; it is CI's, and no narrowing of it is claimed here.

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

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

3 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 AuthManager (symbol, a top-level class))
• content/docs/kernel/services-checklist.mdx(via AuthManager (symbol, a top-level class))
• content/docs/permissions/authentication.mdx(via AuthManager (symbol, a top-level class))

What this run could not see

• 1 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 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.

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 13bf05d3fe8b1795f3f5aee7daf29ee217590ab9 → packageMentionDocs.

Which tree this was computed on

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

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

[hotlong]

Fixes#14319

Second and final PR for this card. #14591 landed the deployment rung; this one lands
the rung above it, on the maintainer's 2026-09-02 ruling.

The ruling

Maintainer, 2026-09-02, in session. Quoted verbatim and untranslated, as rulings are:

注册 / 登录 / 重置密码等由请求触发的 auth 邮件，语言优先取请求的 Accept-Language（命中
AUTH_EMAIL_TEMPLATE_LOCALES 才生效），其次才是 PR #14591 确立的部署默认
（localization.locale → i18n.defaultLocale）。这翻转了 2026-08-13「拒绝
Accept-Language」的裁决。

The motivating case is the one no deployment default can answer: at cloud self-service
signup there is no workspace yet, so nothing on the server represents that person's
language. A Chinese browser reached a Chinese signup screen and got an English
verification email.

What changed

The locale is now a two-rung ladder resolved at send time in AuthManager:

1. the caller's own Accept-Language, when it names a locale in AUTH_EMAIL_TEMPLATE_LOCALES;
2. the deployment default (localization.locale, then i18n.defaultLocale);
3. nothing named, which is EmailService's documented en-US.

The header is parsed by the platform's existing preferredLocaleFromHeader — the one
function REST already uses for metadata translation and the runtime dispatcher for
ExecutionContext.requestLocale. A second parser here would let the mail disagree with
the screen that triggered it, which is the class of defect this card is about.

The hit requirement is the ruling's, and it is load-bearing: fr-FR falls through to the
deployment default rather than naming a row that does not exist. That is deliberately
narrower than normalizeAuthEmailLocale, which passes unshipped regional tags through
because a tenant may overlay en-GB rows and a deployment default may legitimately ask
for them. A per-request header is a weaker claim than a deployment's declaration.

Two exclusions, one of them a judgement call worth reviewing

Per-user language stays deferred. No sys_user column is added. The 2026-09-02 ruling
keeps that half deferred and this PR does not touch it.

Invitations deliberately do NOT take the request rung — please check this reading.
better-auth hands sendInvitationEmail a ctx.request like the others, so wiring it was
available and was declined. That request is the inviter's: stamping their browser
language onto the invitee's mail would reproduce this very card one seat over. The
2026-09-02 ruling enumerates signup, sign-in and password reset — sends where the requester
IS the recipient — and the superseded 2026-08-13 ruling named invitations as its own
counterexample. So invitees keep the deployment default until a per-user language exists to
read. The abstention is commented at the call site rather than left as an omission. If the
maintainer reads the ruling's 等 as covering invitations too, it is a one-argument change.

The other four sends all have requester == recipient, including the change-email notice,
which goes to the account's current address, i.e. to the person who just asked to change it.

Vendor seam, measured rather than assumed

better-auth is not consistent about what it passes these callbacks. Measured against the
installed 1.7.x, not inferred from docs:

callback	second argument
sendResetPassword	ctx.request — a Web Request
sendVerificationEmail	ctx.request (and safeCloneRequest(ctx.request) on one path)
sendInvitationEmail	ctx.request
sendMagicLink	the endpoint ctx, not a Request
change-email notice	fires from the global after hook, which holds a ctx

One reader covers all three shapes, and it never throws: a vendor changing the shape it
hands a callback must degrade to the deployment default, never fail a send.

One story, not two

The 2026-08-13 ruling is rewritten wherever it was recorded, marked superseded, with its
original date and reasoning preserved: AuthManager.setDefaultEmailLocale holds the single
history record, and auth-plugin.ts plus auth-email-locale.test.ts point at it instead of
restating it. The old reasoning did not simply lose — it is exactly why the request rung is
scoped to requester-is-recipient sends, and that is said where the invitation abstains.

Tests

13 new cases in auth-email-locale.test.ts. The three the dispatch asked for — a zh-CN
caller gets zh-CN; an absent header falls back to the deployment default; a locale we ship
no row for (fr-FR, de, pt-BR, *) falls back — plus: ja-JP / es-ES / en-US
callers; both rungs silent leaves the key absent rather than en-US, because that is
what the ladder's contract is written against; the invitation abstention; payload
non-disturbance; and unit cases for the reader across a Request, an endpoint ctx, both
header-bag spellings, bare-language promotion, and a header bag that throws.

Locale is what this layer outputs, so locale is what is asserted. That a zh-CN row then
renders a Chinese subject carrying no en-US text is plugin-email/src/auth-templates-locales.test.ts,
which owns the row half; the two together are the card's acceptance criterion.

Reverse verification. Rather than reverting the whole file — which would have failed the
import and produced a red that proves nothing — the mutation was surgical: the one
load-bearing line, authEmailLocaleFromRequest(requestSource) ?? this.emailLocale, was
replaced by this.emailLocale alone, keeping the exported helper so the red would be
behavioural. Direction: RED, and discriminating — 4 failed | 26 passed, the four being
exactly the request-precedence cases (expected 'zh-CN' to be 'en-US'), while the fallback
cases and every unit case stayed green. A blanket red would have meant the tests were not
isolating the rung. Mutation confirmed on disk by blob hash and anchor counts, not by an
editor exit code: HEAD blob d0d15b92, mutated blob 4d642984, injected anchor present 1x
and deleted anchor 0x. Restore confirmed byte-identical afterwards: worktree blob back to
d0d15b92, git diff HEAD empty, git status --porcelain empty; the restore leg ran from a
trap ... EXIT INT TERM with absolute paths from git rev-parse --show-toplevel. No rebuild
was needed for either leg and none is claimed: the suite imports ./auth-manager as source,
so no dist/ sits between the mutation and the assertion.

Gates — run at cdf2c3c3d

• pnpm --filter '@objectstack/plugin-auth^...' build — VERDICT command-exit 0
• pnpm --filter @objectstack/plugin-auth test — Test Files 90 passed, Tests 1849 passed
• pnpm --filter @objectstack/plugin-auth typecheck — exit 0;
  check:test-typecheck: OK ... 10 file(s) / 94 error(s) / 23 pinned signature(s) — ledger
  unchanged, no new test-layer debt
• node scripts/check-nul-bytes.mjs — OK (scanned 7977 text file(s) ... no raw ASCII control bytes)
• 62 derived families run (dispatch-gates.mjs --repo objectstack-ai/objectstack, no paths
  passed). The first derivation gave 38; repairing the census below added content/docs/**, and
  the re-derivation returned 62, so the 24 doc families were run too.
• pnpm check:type-check-coverage --re-measure — OK — 22 ledger entr(ies) re-measured in 137.6s, 755 raw tsc error(s) total, none above its recorded number
• pnpm check:skill-examples — 261 prose examples type-check across 3 surface(s)
• pnpm check:dual-build-cjs-loads — exit 0, floors held

Those three refuse to answer on an unbuilt tree rather than green-lighting one;
turbo run build --filter='./packages/*' --filter='./packages/*/*' ran 71/71 successful and
all three then measured green.

One real gate finding, repaired.check-system-context-census went red on pure line rot —
this PR's comments moved an elevation read in auth-plugin.ts from line 1301 to 1310,
orphaning the anchor. Repaired with the script's own --fix (exactly one anchor rewritten),
after which: OK — 109 elevation read sites in 20 packages across 45 files, all anchored; 145 anchors resolve, 27 declared non-read.

Two families NOT MEASURED locally, by their own verdict text — neither is a red.
check-test-completeness exits 3 asking for a saved turbo run test log and instructs a local
family run to record NOT MEASURED; check-half-states exits 3 as an unread instrument on this
host. Both are CI's.

Expected conflict with #14591

#14591 was still open at push time, so this branch is cut from main without it. Two
overlapping regions, both mechanical:

• auth-plugin.ts — the same #8195 comment block. fix(plugin-auth): bind the auth email locale to the workspace language, not the build-time default #14591 rewrites it to describe the
  localization.locale precedence; this PR rewrites it to say the block binds the second
  rung. Intended resolution: keep both — fix(plugin-auth): bind the auth email locale to the workspace language, not the build-time default #14591's precedence text, plus this PR's "this is
  the second rung, the request rung lives in AuthManager" framing and its instruction not to
  restore the superseded reading.
• content/docs/permissions/system-context.mdx line 100 — the same census anchor, moved to
  1345 by fix(plugin-auth): bind the auth email locale to the workspace language, not the build-time default #14591 and to 1310 here. Intended resolution: neither number; re-run
  node scripts/check-system-context-census.mjs --fix on the merged tree and take what it
  writes. The number is derived, so hand-picking a side is guesswork.

Declared narrowing — verification ran UNLOCKED.scripts/pm/os-verify-lock.sh
could not take the shared verify lock on this host: no usable flock. The shared
verify lock is declared Linux-only (flock is util-linux, and a stock macOS does
not ship it), so the commands above were run directly, without the lock —
a declared narrowing, not a silent one. No serialization guarantee held for these
runs, nor for any sibling agent in this container while they ran.

Repo-wide pnpm lint was not run; it is CI's, and no narrowing of it is claimed here.

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

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

3 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 AuthManager (symbol, a top-level class))
• content/docs/kernel/services-checklist.mdx(via AuthManager (symbol, a top-level class))
• content/docs/permissions/authentication.mdx(via AuthManager (symbol, a top-level class))

What this run could not see

• 1 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 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.

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 13bf05d3fe8b1795f3f5aee7daf29ee217590ab9 → packageMentionDocs.

Which tree this was computed on

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

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

[hotlong]

Fixes#14319

Second and final PR for this card. #14591 landed the deployment rung; this one lands
the rung above it, on the maintainer's 2026-09-02 ruling.

The ruling

Maintainer, 2026-09-02, in session. Quoted verbatim and untranslated, as rulings are:

注册 / 登录 / 重置密码等由请求触发的 auth 邮件，语言优先取请求的 Accept-Language（命中
AUTH_EMAIL_TEMPLATE_LOCALES 才生效），其次才是 PR #14591 确立的部署默认
（localization.locale → i18n.defaultLocale）。这翻转了 2026-08-13「拒绝
Accept-Language」的裁决。

The motivating case is the one no deployment default can answer: at cloud self-service
signup there is no workspace yet, so nothing on the server represents that person's
language. A Chinese browser reached a Chinese signup screen and got an English
verification email.

What changed

The locale is now a two-rung ladder resolved at send time in AuthManager:

1. the caller's own Accept-Language, when it names a locale in AUTH_EMAIL_TEMPLATE_LOCALES;
2. the deployment default (localization.locale, then i18n.defaultLocale);
3. nothing named, which is EmailService's documented en-US.

The header is parsed by the platform's existing preferredLocaleFromHeader — the one
function REST already uses for metadata translation and the runtime dispatcher for
ExecutionContext.requestLocale. A second parser here would let the mail disagree with
the screen that triggered it, which is the class of defect this card is about.

The hit requirement is the ruling's, and it is load-bearing: fr-FR falls through to the
deployment default rather than naming a row that does not exist. That is deliberately
narrower than normalizeAuthEmailLocale, which passes unshipped regional tags through
because a tenant may overlay en-GB rows and a deployment default may legitimately ask
for them. A per-request header is a weaker claim than a deployment's declaration.

Two exclusions, one of them a judgement call worth reviewing

Per-user language stays deferred. No sys_user column is added. The 2026-09-02 ruling
keeps that half deferred and this PR does not touch it.

Invitations deliberately do NOT take the request rung — please check this reading.
better-auth hands sendInvitationEmail a ctx.request like the others, so wiring it was
available and was declined. That request is the inviter's: stamping their browser
language onto the invitee's mail would reproduce this very card one seat over. The
2026-09-02 ruling enumerates signup, sign-in and password reset — sends where the requester
IS the recipient — and the superseded 2026-08-13 ruling named invitations as its own
counterexample. So invitees keep the deployment default until a per-user language exists to
read. The abstention is commented at the call site rather than left as an omission. If the
maintainer reads the ruling's 等 as covering invitations too, it is a one-argument change.

The other four sends all have requester == recipient, including the change-email notice,
which goes to the account's current address, i.e. to the person who just asked to change it.

Vendor seam, measured rather than assumed

better-auth is not consistent about what it passes these callbacks. Measured against the
installed 1.7.x, not inferred from docs:

callback	second argument
sendResetPassword	ctx.request — a Web Request
sendVerificationEmail	ctx.request (and safeCloneRequest(ctx.request) on one path)
sendInvitationEmail	ctx.request
sendMagicLink	the endpoint ctx, not a Request
change-email notice	fires from the global after hook, which holds a ctx

One reader covers all three shapes, and it never throws: a vendor changing the shape it
hands a callback must degrade to the deployment default, never fail a send.

One story, not two

The 2026-08-13 ruling is rewritten wherever it was recorded, marked superseded, with its
original date and reasoning preserved: AuthManager.setDefaultEmailLocale holds the single
history record, and auth-plugin.ts plus auth-email-locale.test.ts point at it instead of
restating it. The old reasoning did not simply lose — it is exactly why the request rung is
scoped to requester-is-recipient sends, and that is said where the invitation abstains.

Tests

13 new cases in auth-email-locale.test.ts. The three the dispatch asked for — a zh-CN
caller gets zh-CN; an absent header falls back to the deployment default; a locale we ship
no row for (fr-FR, de, pt-BR, *) falls back — plus: ja-JP / es-ES / en-US
callers; both rungs silent leaves the key absent rather than en-US, because that is
what the ladder's contract is written against; the invitation abstention; payload
non-disturbance; and unit cases for the reader across a Request, an endpoint ctx, both
header-bag spellings, bare-language promotion, and a header bag that throws.

Locale is what this layer outputs, so locale is what is asserted. That a zh-CN row then
renders a Chinese subject carrying no en-US text is plugin-email/src/auth-templates-locales.test.ts,
which owns the row half; the two together are the card's acceptance criterion.

Reverse verification. Rather than reverting the whole file — which would have failed the
import and produced a red that proves nothing — the mutation was surgical: the one
load-bearing line, authEmailLocaleFromRequest(requestSource) ?? this.emailLocale, was
replaced by this.emailLocale alone, keeping the exported helper so the red would be
behavioural. Direction: RED, and discriminating — 4 failed | 26 passed, the four being
exactly the request-precedence cases (expected 'zh-CN' to be 'en-US'), while the fallback
cases and every unit case stayed green. A blanket red would have meant the tests were not
isolating the rung. Mutation confirmed on disk by blob hash and anchor counts, not by an
editor exit code: HEAD blob d0d15b92, mutated blob 4d642984, injected anchor present 1x
and deleted anchor 0x. Restore confirmed byte-identical afterwards: worktree blob back to
d0d15b92, git diff HEAD empty, git status --porcelain empty; the restore leg ran from a
trap ... EXIT INT TERM with absolute paths from git rev-parse --show-toplevel. No rebuild
was needed for either leg and none is claimed: the suite imports ./auth-manager as source,
so no dist/ sits between the mutation and the assertion.

Gates — run at cdf2c3c3d

• pnpm --filter '@objectstack/plugin-auth^...' build — VERDICT command-exit 0
• pnpm --filter @objectstack/plugin-auth test — Test Files 90 passed, Tests 1849 passed
• pnpm --filter @objectstack/plugin-auth typecheck — exit 0;
  check:test-typecheck: OK ... 10 file(s) / 94 error(s) / 23 pinned signature(s) — ledger
  unchanged, no new test-layer debt
• node scripts/check-nul-bytes.mjs — OK (scanned 7977 text file(s) ... no raw ASCII control bytes)
• 62 derived families run (dispatch-gates.mjs --repo objectstack-ai/objectstack, no paths
  passed). The first derivation gave 38; repairing the census below added content/docs/**, and
  the re-derivation returned 62, so the 24 doc families were run too.
• pnpm check:type-check-coverage --re-measure — OK — 22 ledger entr(ies) re-measured in 137.6s, 755 raw tsc error(s) total, none above its recorded number
• pnpm check:skill-examples — 261 prose examples type-check across 3 surface(s)
• pnpm check:dual-build-cjs-loads — exit 0, floors held

Those three refuse to answer on an unbuilt tree rather than green-lighting one;
turbo run build --filter='./packages/*' --filter='./packages/*/*' ran 71/71 successful and
all three then measured green.

One real gate finding, repaired.check-system-context-census went red on pure line rot —
this PR's comments moved an elevation read in auth-plugin.ts from line 1301 to 1310,
orphaning the anchor. Repaired with the script's own --fix (exactly one anchor rewritten),
after which: OK — 109 elevation read sites in 20 packages across 45 files, all anchored; 145 anchors resolve, 27 declared non-read.

Two families NOT MEASURED locally, by their own verdict text — neither is a red.
check-test-completeness exits 3 asking for a saved turbo run test log and instructs a local
family run to record NOT MEASURED; check-half-states exits 3 as an unread instrument on this
host. Both are CI's.

Expected conflict with #14591

#14591 was still open at push time, so this branch is cut from main without it. Two
overlapping regions, both mechanical:

• auth-plugin.ts — the same #8195 comment block. fix(plugin-auth): bind the auth email locale to the workspace language, not the build-time default #14591 rewrites it to describe the
  localization.locale precedence; this PR rewrites it to say the block binds the second
  rung. Intended resolution: keep both — fix(plugin-auth): bind the auth email locale to the workspace language, not the build-time default #14591's precedence text, plus this PR's "this is
  the second rung, the request rung lives in AuthManager" framing and its instruction not to
  restore the superseded reading.
• content/docs/permissions/system-context.mdx line 100 — the same census anchor, moved to
  1345 by fix(plugin-auth): bind the auth email locale to the workspace language, not the build-time default #14591 and to 1310 here. Intended resolution: neither number; re-run
  node scripts/check-system-context-census.mjs --fix on the merged tree and take what it
  writes. The number is derived, so hand-picking a side is guesswork.

Declared narrowing — verification ran UNLOCKED.scripts/pm/os-verify-lock.sh
could not take the shared verify lock on this host: no usable flock. The shared
verify lock is declared Linux-only (flock is util-linux, and a stock macOS does
not ship it), so the commands above were run directly, without the lock —
a declared narrowing, not a silent one. No serialization guarantee held for these
runs, nor for any sibling agent in this container while they ran.

Repo-wide pnpm lint was not run; it is CI's, and no narrowing of it is claimed here.

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

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

3 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 AuthManager (symbol, a top-level class))
• content/docs/kernel/services-checklist.mdx(via AuthManager (symbol, a top-level class))
• content/docs/permissions/authentication.mdx(via AuthManager (symbol, a top-level class))

What this run could not see

• 1 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 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.

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 13bf05d3fe8b1795f3f5aee7daf29ee217590ab9 → packageMentionDocs.

Which tree this was computed on

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

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

[hotlong]

Fixes#14319

Second and final PR for this card. #14591 landed the deployment rung; this one lands
the rung above it, on the maintainer's 2026-09-02 ruling.

The ruling

Maintainer, 2026-09-02, in session. Quoted verbatim and untranslated, as rulings are:

注册 / 登录 / 重置密码等由请求触发的 auth 邮件，语言优先取请求的 Accept-Language（命中
AUTH_EMAIL_TEMPLATE_LOCALES 才生效），其次才是 PR #14591 确立的部署默认
（localization.locale → i18n.defaultLocale）。这翻转了 2026-08-13「拒绝
Accept-Language」的裁决。

The motivating case is the one no deployment default can answer: at cloud self-service
signup there is no workspace yet, so nothing on the server represents that person's
language. A Chinese browser reached a Chinese signup screen and got an English
verification email.

What changed

The locale is now a two-rung ladder resolved at send time in AuthManager:

1. the caller's own Accept-Language, when it names a locale in AUTH_EMAIL_TEMPLATE_LOCALES;
2. the deployment default (localization.locale, then i18n.defaultLocale);
3. nothing named, which is EmailService's documented en-US.

The header is parsed by the platform's existing preferredLocaleFromHeader — the one
function REST already uses for metadata translation and the runtime dispatcher for
ExecutionContext.requestLocale. A second parser here would let the mail disagree with
the screen that triggered it, which is the class of defect this card is about.

The hit requirement is the ruling's, and it is load-bearing: fr-FR falls through to the
deployment default rather than naming a row that does not exist. That is deliberately
narrower than normalizeAuthEmailLocale, which passes unshipped regional tags through
because a tenant may overlay en-GB rows and a deployment default may legitimately ask
for them. A per-request header is a weaker claim than a deployment's declaration.

Two exclusions, one of them a judgement call worth reviewing

Per-user language stays deferred. No sys_user column is added. The 2026-09-02 ruling
keeps that half deferred and this PR does not touch it.

Invitations deliberately do NOT take the request rung — please check this reading.
better-auth hands sendInvitationEmail a ctx.request like the others, so wiring it was
available and was declined. That request is the inviter's: stamping their browser
language onto the invitee's mail would reproduce this very card one seat over. The
2026-09-02 ruling enumerates signup, sign-in and password reset — sends where the requester
IS the recipient — and the superseded 2026-08-13 ruling named invitations as its own
counterexample. So invitees keep the deployment default until a per-user language exists to
read. The abstention is commented at the call site rather than left as an omission. If the
maintainer reads the ruling's 等 as covering invitations too, it is a one-argument change.

The other four sends all have requester == recipient, including the change-email notice,
which goes to the account's current address, i.e. to the person who just asked to change it.

Vendor seam, measured rather than assumed

better-auth is not consistent about what it passes these callbacks. Measured against the
installed 1.7.x, not inferred from docs:

callback	second argument
sendResetPassword	ctx.request — a Web Request
sendVerificationEmail	ctx.request (and safeCloneRequest(ctx.request) on one path)
sendInvitationEmail	ctx.request
sendMagicLink	the endpoint ctx, not a Request
change-email notice	fires from the global after hook, which holds a ctx

One reader covers all three shapes, and it never throws: a vendor changing the shape it
hands a callback must degrade to the deployment default, never fail a send.

One story, not two

The 2026-08-13 ruling is rewritten wherever it was recorded, marked superseded, with its
original date and reasoning preserved: AuthManager.setDefaultEmailLocale holds the single
history record, and auth-plugin.ts plus auth-email-locale.test.ts point at it instead of
restating it. The old reasoning did not simply lose — it is exactly why the request rung is
scoped to requester-is-recipient sends, and that is said where the invitation abstains.

Tests

13 new cases in auth-email-locale.test.ts. The three the dispatch asked for — a zh-CN
caller gets zh-CN; an absent header falls back to the deployment default; a locale we ship
no row for (fr-FR, de, pt-BR, *) falls back — plus: ja-JP / es-ES / en-US
callers; both rungs silent leaves the key absent rather than en-US, because that is
what the ladder's contract is written against; the invitation abstention; payload
non-disturbance; and unit cases for the reader across a Request, an endpoint ctx, both
header-bag spellings, bare-language promotion, and a header bag that throws.

Locale is what this layer outputs, so locale is what is asserted. That a zh-CN row then
renders a Chinese subject carrying no en-US text is plugin-email/src/auth-templates-locales.test.ts,
which owns the row half; the two together are the card's acceptance criterion.

Reverse verification. Rather than reverting the whole file — which would have failed the
import and produced a red that proves nothing — the mutation was surgical: the one
load-bearing line, authEmailLocaleFromRequest(requestSource) ?? this.emailLocale, was
replaced by this.emailLocale alone, keeping the exported helper so the red would be
behavioural. Direction: RED, and discriminating — 4 failed | 26 passed, the four being
exactly the request-precedence cases (expected 'zh-CN' to be 'en-US'), while the fallback
cases and every unit case stayed green. A blanket red would have meant the tests were not
isolating the rung. Mutation confirmed on disk by blob hash and anchor counts, not by an
editor exit code: HEAD blob d0d15b92, mutated blob 4d642984, injected anchor present 1x
and deleted anchor 0x. Restore confirmed byte-identical afterwards: worktree blob back to
d0d15b92, git diff HEAD empty, git status --porcelain empty; the restore leg ran from a
trap ... EXIT INT TERM with absolute paths from git rev-parse --show-toplevel. No rebuild
was needed for either leg and none is claimed: the suite imports ./auth-manager as source,
so no dist/ sits between the mutation and the assertion.

Gates — run at cdf2c3c3d

• pnpm --filter '@objectstack/plugin-auth^...' build — VERDICT command-exit 0
• pnpm --filter @objectstack/plugin-auth test — Test Files 90 passed, Tests 1849 passed
• pnpm --filter @objectstack/plugin-auth typecheck — exit 0;
  check:test-typecheck: OK ... 10 file(s) / 94 error(s) / 23 pinned signature(s) — ledger
  unchanged, no new test-layer debt
• node scripts/check-nul-bytes.mjs — OK (scanned 7977 text file(s) ... no raw ASCII control bytes)
• 62 derived families run (dispatch-gates.mjs --repo objectstack-ai/objectstack, no paths
  passed). The first derivation gave 38; repairing the census below added content/docs/**, and
  the re-derivation returned 62, so the 24 doc families were run too.
• pnpm check:type-check-coverage --re-measure — OK — 22 ledger entr(ies) re-measured in 137.6s, 755 raw tsc error(s) total, none above its recorded number
• pnpm check:skill-examples — 261 prose examples type-check across 3 surface(s)
• pnpm check:dual-build-cjs-loads — exit 0, floors held

Those three refuse to answer on an unbuilt tree rather than green-lighting one;
turbo run build --filter='./packages/*' --filter='./packages/*/*' ran 71/71 successful and
all three then measured green.

One real gate finding, repaired.check-system-context-census went red on pure line rot —
this PR's comments moved an elevation read in auth-plugin.ts from line 1301 to 1310,
orphaning the anchor. Repaired with the script's own --fix (exactly one anchor rewritten),
after which: OK — 109 elevation read sites in 20 packages across 45 files, all anchored; 145 anchors resolve, 27 declared non-read.

Two families NOT MEASURED locally, by their own verdict text — neither is a red.
check-test-completeness exits 3 asking for a saved turbo run test log and instructs a local
family run to record NOT MEASURED; check-half-states exits 3 as an unread instrument on this
host. Both are CI's.

Expected conflict with #14591

#14591 was still open at push time, so this branch is cut from main without it. Two
overlapping regions, both mechanical:

• auth-plugin.ts — the same #8195 comment block. fix(plugin-auth): bind the auth email locale to the workspace language, not the build-time default #14591 rewrites it to describe the
  localization.locale precedence; this PR rewrites it to say the block binds the second
  rung. Intended resolution: keep both — fix(plugin-auth): bind the auth email locale to the workspace language, not the build-time default #14591's precedence text, plus this PR's "this is
  the second rung, the request rung lives in AuthManager" framing and its instruction not to
  restore the superseded reading.
• content/docs/permissions/system-context.mdx line 100 — the same census anchor, moved to
  1345 by fix(plugin-auth): bind the auth email locale to the workspace language, not the build-time default #14591 and to 1310 here. Intended resolution: neither number; re-run
  node scripts/check-system-context-census.mjs --fix on the merged tree and take what it
  writes. The number is derived, so hand-picking a side is guesswork.

Declared narrowing — verification ran UNLOCKED.scripts/pm/os-verify-lock.sh
could not take the shared verify lock on this host: no usable flock. The shared
verify lock is declared Linux-only (flock is util-linux, and a stock macOS does
not ship it), so the commands above were run directly, without the lock —
a declared narrowing, not a silent one. No serialization guarantee held for these
runs, nor for any sibling agent in this container while they ran.

Repo-wide pnpm lint was not run; it is CI's, and no narrowing of it is claimed here.

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

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

3 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 AuthManager (symbol, a top-level class))
• content/docs/kernel/services-checklist.mdx(via AuthManager (symbol, a top-level class))
• content/docs/permissions/authentication.mdx(via AuthManager (symbol, a top-level class))

What this run could not see

• 1 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 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.

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 13bf05d3fe8b1795f3f5aee7daf29ee217590ab9 → packageMentionDocs.

Which tree this was computed on

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

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

[hotlong]

Fixes#14319

Second and final PR for this card. #14591 landed the deployment rung; this one lands
the rung above it, on the maintainer's 2026-09-02 ruling.

The ruling

Maintainer, 2026-09-02, in session. Quoted verbatim and untranslated, as rulings are:

注册 / 登录 / 重置密码等由请求触发的 auth 邮件，语言优先取请求的 Accept-Language（命中
AUTH_EMAIL_TEMPLATE_LOCALES 才生效），其次才是 PR #14591 确立的部署默认
（localization.locale → i18n.defaultLocale）。这翻转了 2026-08-13「拒绝
Accept-Language」的裁决。

The motivating case is the one no deployment default can answer: at cloud self-service
signup there is no workspace yet, so nothing on the server represents that person's
language. A Chinese browser reached a Chinese signup screen and got an English
verification email.

What changed

The locale is now a two-rung ladder resolved at send time in AuthManager:

1. the caller's own Accept-Language, when it names a locale in AUTH_EMAIL_TEMPLATE_LOCALES;
2. the deployment default (localization.locale, then i18n.defaultLocale);
3. nothing named, which is EmailService's documented en-US.

The header is parsed by the platform's existing preferredLocaleFromHeader — the one
function REST already uses for metadata translation and the runtime dispatcher for
ExecutionContext.requestLocale. A second parser here would let the mail disagree with
the screen that triggered it, which is the class of defect this card is about.

The hit requirement is the ruling's, and it is load-bearing: fr-FR falls through to the
deployment default rather than naming a row that does not exist. That is deliberately
narrower than normalizeAuthEmailLocale, which passes unshipped regional tags through
because a tenant may overlay en-GB rows and a deployment default may legitimately ask
for them. A per-request header is a weaker claim than a deployment's declaration.

Two exclusions, one of them a judgement call worth reviewing

Per-user language stays deferred. No sys_user column is added. The 2026-09-02 ruling
keeps that half deferred and this PR does not touch it.

Invitations deliberately do NOT take the request rung — please check this reading.
better-auth hands sendInvitationEmail a ctx.request like the others, so wiring it was
available and was declined. That request is the inviter's: stamping their browser
language onto the invitee's mail would reproduce this very card one seat over. The
2026-09-02 ruling enumerates signup, sign-in and password reset — sends where the requester
IS the recipient — and the superseded 2026-08-13 ruling named invitations as its own
counterexample. So invitees keep the deployment default until a per-user language exists to
read. The abstention is commented at the call site rather than left as an omission. If the
maintainer reads the ruling's 等 as covering invitations too, it is a one-argument change.

The other four sends all have requester == recipient, including the change-email notice,
which goes to the account's current address, i.e. to the person who just asked to change it.

Vendor seam, measured rather than assumed

better-auth is not consistent about what it passes these callbacks. Measured against the
installed 1.7.x, not inferred from docs:

callback	second argument
sendResetPassword	ctx.request — a Web Request
sendVerificationEmail	ctx.request (and safeCloneRequest(ctx.request) on one path)
sendInvitationEmail	ctx.request
sendMagicLink	the endpoint ctx, not a Request
change-email notice	fires from the global after hook, which holds a ctx

One reader covers all three shapes, and it never throws: a vendor changing the shape it
hands a callback must degrade to the deployment default, never fail a send.

One story, not two

The 2026-08-13 ruling is rewritten wherever it was recorded, marked superseded, with its
original date and reasoning preserved: AuthManager.setDefaultEmailLocale holds the single
history record, and auth-plugin.ts plus auth-email-locale.test.ts point at it instead of
restating it. The old reasoning did not simply lose — it is exactly why the request rung is
scoped to requester-is-recipient sends, and that is said where the invitation abstains.

Tests

13 new cases in auth-email-locale.test.ts. The three the dispatch asked for — a zh-CN
caller gets zh-CN; an absent header falls back to the deployment default; a locale we ship
no row for (fr-FR, de, pt-BR, *) falls back — plus: ja-JP / es-ES / en-US
callers; both rungs silent leaves the key absent rather than en-US, because that is
what the ladder's contract is written against; the invitation abstention; payload
non-disturbance; and unit cases for the reader across a Request, an endpoint ctx, both
header-bag spellings, bare-language promotion, and a header bag that throws.

Locale is what this layer outputs, so locale is what is asserted. That a zh-CN row then
renders a Chinese subject carrying no en-US text is plugin-email/src/auth-templates-locales.test.ts,
which owns the row half; the two together are the card's acceptance criterion.

Reverse verification. Rather than reverting the whole file — which would have failed the
import and produced a red that proves nothing — the mutation was surgical: the one
load-bearing line, authEmailLocaleFromRequest(requestSource) ?? this.emailLocale, was
replaced by this.emailLocale alone, keeping the exported helper so the red would be
behavioural. Direction: RED, and discriminating — 4 failed | 26 passed, the four being
exactly the request-precedence cases (expected 'zh-CN' to be 'en-US'), while the fallback
cases and every unit case stayed green. A blanket red would have meant the tests were not
isolating the rung. Mutation confirmed on disk by blob hash and anchor counts, not by an
editor exit code: HEAD blob d0d15b92, mutated blob 4d642984, injected anchor present 1x
and deleted anchor 0x. Restore confirmed byte-identical afterwards: worktree blob back to
d0d15b92, git diff HEAD empty, git status --porcelain empty; the restore leg ran from a
trap ... EXIT INT TERM with absolute paths from git rev-parse --show-toplevel. No rebuild
was needed for either leg and none is claimed: the suite imports ./auth-manager as source,
so no dist/ sits between the mutation and the assertion.

Gates — run at cdf2c3c3d

• pnpm --filter '@objectstack/plugin-auth^...' build — VERDICT command-exit 0
• pnpm --filter @objectstack/plugin-auth test — Test Files 90 passed, Tests 1849 passed
• pnpm --filter @objectstack/plugin-auth typecheck — exit 0;
  check:test-typecheck: OK ... 10 file(s) / 94 error(s) / 23 pinned signature(s) — ledger
  unchanged, no new test-layer debt
• node scripts/check-nul-bytes.mjs — OK (scanned 7977 text file(s) ... no raw ASCII control bytes)
• 62 derived families run (dispatch-gates.mjs --repo objectstack-ai/objectstack, no paths
  passed). The first derivation gave 38; repairing the census below added content/docs/**, and
  the re-derivation returned 62, so the 24 doc families were run too.
• pnpm check:type-check-coverage --re-measure — OK — 22 ledger entr(ies) re-measured in 137.6s, 755 raw tsc error(s) total, none above its recorded number
• pnpm check:skill-examples — 261 prose examples type-check across 3 surface(s)
• pnpm check:dual-build-cjs-loads — exit 0, floors held

Those three refuse to answer on an unbuilt tree rather than green-lighting one;
turbo run build --filter='./packages/*' --filter='./packages/*/*' ran 71/71 successful and
all three then measured green.

One real gate finding, repaired.check-system-context-census went red on pure line rot —
this PR's comments moved an elevation read in auth-plugin.ts from line 1301 to 1310,
orphaning the anchor. Repaired with the script's own --fix (exactly one anchor rewritten),
after which: OK — 109 elevation read sites in 20 packages across 45 files, all anchored; 145 anchors resolve, 27 declared non-read.

Two families NOT MEASURED locally, by their own verdict text — neither is a red.
check-test-completeness exits 3 asking for a saved turbo run test log and instructs a local
family run to record NOT MEASURED; check-half-states exits 3 as an unread instrument on this
host. Both are CI's.

Expected conflict with #14591

#14591 was still open at push time, so this branch is cut from main without it. Two
overlapping regions, both mechanical:

• auth-plugin.ts — the same #8195 comment block. fix(plugin-auth): bind the auth email locale to the workspace language, not the build-time default #14591 rewrites it to describe the
  localization.locale precedence; this PR rewrites it to say the block binds the second
  rung. Intended resolution: keep both — fix(plugin-auth): bind the auth email locale to the workspace language, not the build-time default #14591's precedence text, plus this PR's "this is
  the second rung, the request rung lives in AuthManager" framing and its instruction not to
  restore the superseded reading.
• content/docs/permissions/system-context.mdx line 100 — the same census anchor, moved to
  1345 by fix(plugin-auth): bind the auth email locale to the workspace language, not the build-time default #14591 and to 1310 here. Intended resolution: neither number; re-run
  node scripts/check-system-context-census.mjs --fix on the merged tree and take what it
  writes. The number is derived, so hand-picking a side is guesswork.

Declared narrowing — verification ran UNLOCKED.scripts/pm/os-verify-lock.sh
could not take the shared verify lock on this host: no usable flock. The shared
verify lock is declared Linux-only (flock is util-linux, and a stock macOS does
not ship it), so the commands above were run directly, without the lock —
a declared narrowing, not a silent one. No serialization guarantee held for these
runs, nor for any sibling agent in this container while they ran.

Repo-wide pnpm lint was not run; it is CI's, and no narrowing of it is claimed here.

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

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

3 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 AuthManager (symbol, a top-level class))
• content/docs/kernel/services-checklist.mdx(via AuthManager (symbol, a top-level class))
• content/docs/permissions/authentication.mdx(via AuthManager (symbol, a top-level class))

What this run could not see

• 1 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 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.

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 13bf05d3fe8b1795f3f5aee7daf29ee217590ab9 → packageMentionDocs.

Which tree this was computed on

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

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

[hotlong]

Fixes#14319

Second and final PR for this card. #14591 landed the deployment rung; this one lands
the rung above it, on the maintainer's 2026-09-02 ruling.

The ruling

Maintainer, 2026-09-02, in session. Quoted verbatim and untranslated, as rulings are:

注册 / 登录 / 重置密码等由请求触发的 auth 邮件，语言优先取请求的 Accept-Language（命中
AUTH_EMAIL_TEMPLATE_LOCALES 才生效），其次才是 PR #14591 确立的部署默认
（localization.locale → i18n.defaultLocale）。这翻转了 2026-08-13「拒绝
Accept-Language」的裁决。

The motivating case is the one no deployment default can answer: at cloud self-service
signup there is no workspace yet, so nothing on the server represents that person's
language. A Chinese browser reached a Chinese signup screen and got an English
verification email.

What changed

The locale is now a two-rung ladder resolved at send time in AuthManager:

1. the caller's own Accept-Language, when it names a locale in AUTH_EMAIL_TEMPLATE_LOCALES;
2. the deployment default (localization.locale, then i18n.defaultLocale);
3. nothing named, which is EmailService's documented en-US.

The header is parsed by the platform's existing preferredLocaleFromHeader — the one
function REST already uses for metadata translation and the runtime dispatcher for
ExecutionContext.requestLocale. A second parser here would let the mail disagree with
the screen that triggered it, which is the class of defect this card is about.

The hit requirement is the ruling's, and it is load-bearing: fr-FR falls through to the
deployment default rather than naming a row that does not exist. That is deliberately
narrower than normalizeAuthEmailLocale, which passes unshipped regional tags through
because a tenant may overlay en-GB rows and a deployment default may legitimately ask
for them. A per-request header is a weaker claim than a deployment's declaration.

Two exclusions, one of them a judgement call worth reviewing

Per-user language stays deferred. No sys_user column is added. The 2026-09-02 ruling
keeps that half deferred and this PR does not touch it.

Invitations deliberately do NOT take the request rung — please check this reading.
better-auth hands sendInvitationEmail a ctx.request like the others, so wiring it was
available and was declined. That request is the inviter's: stamping their browser
language onto the invitee's mail would reproduce this very card one seat over. The
2026-09-02 ruling enumerates signup, sign-in and password reset — sends where the requester
IS the recipient — and the superseded 2026-08-13 ruling named invitations as its own
counterexample. So invitees keep the deployment default until a per-user language exists to
read. The abstention is commented at the call site rather than left as an omission. If the
maintainer reads the ruling's 等 as covering invitations too, it is a one-argument change.

The other four sends all have requester == recipient, including the change-email notice,
which goes to the account's current address, i.e. to the person who just asked to change it.

Vendor seam, measured rather than assumed

better-auth is not consistent about what it passes these callbacks. Measured against the
installed 1.7.x, not inferred from docs:

callback	second argument
sendResetPassword	ctx.request — a Web Request
sendVerificationEmail	ctx.request (and safeCloneRequest(ctx.request) on one path)
sendInvitationEmail	ctx.request
sendMagicLink	the endpoint ctx, not a Request
change-email notice	fires from the global after hook, which holds a ctx

One reader covers all three shapes, and it never throws: a vendor changing the shape it
hands a callback must degrade to the deployment default, never fail a send.

One story, not two

The 2026-08-13 ruling is rewritten wherever it was recorded, marked superseded, with its
original date and reasoning preserved: AuthManager.setDefaultEmailLocale holds the single
history record, and auth-plugin.ts plus auth-email-locale.test.ts point at it instead of
restating it. The old reasoning did not simply lose — it is exactly why the request rung is
scoped to requester-is-recipient sends, and that is said where the invitation abstains.

Tests

13 new cases in auth-email-locale.test.ts. The three the dispatch asked for — a zh-CN
caller gets zh-CN; an absent header falls back to the deployment default; a locale we ship
no row for (fr-FR, de, pt-BR, *) falls back — plus: ja-JP / es-ES / en-US
callers; both rungs silent leaves the key absent rather than en-US, because that is
what the ladder's contract is written against; the invitation abstention; payload
non-disturbance; and unit cases for the reader across a Request, an endpoint ctx, both
header-bag spellings, bare-language promotion, and a header bag that throws.

Locale is what this layer outputs, so locale is what is asserted. That a zh-CN row then
renders a Chinese subject carrying no en-US text is plugin-email/src/auth-templates-locales.test.ts,
which owns the row half; the two together are the card's acceptance criterion.

Reverse verification. Rather than reverting the whole file — which would have failed the
import and produced a red that proves nothing — the mutation was surgical: the one
load-bearing line, authEmailLocaleFromRequest(requestSource) ?? this.emailLocale, was
replaced by this.emailLocale alone, keeping the exported helper so the red would be
behavioural. Direction: RED, and discriminating — 4 failed | 26 passed, the four being
exactly the request-precedence cases (expected 'zh-CN' to be 'en-US'), while the fallback
cases and every unit case stayed green. A blanket red would have meant the tests were not
isolating the rung. Mutation confirmed on disk by blob hash and anchor counts, not by an
editor exit code: HEAD blob d0d15b92, mutated blob 4d642984, injected anchor present 1x
and deleted anchor 0x. Restore confirmed byte-identical afterwards: worktree blob back to
d0d15b92, git diff HEAD empty, git status --porcelain empty; the restore leg ran from a
trap ... EXIT INT TERM with absolute paths from git rev-parse --show-toplevel. No rebuild
was needed for either leg and none is claimed: the suite imports ./auth-manager as source,
so no dist/ sits between the mutation and the assertion.

Gates — run at cdf2c3c3d

• pnpm --filter '@objectstack/plugin-auth^...' build — VERDICT command-exit 0
• pnpm --filter @objectstack/plugin-auth test — Test Files 90 passed, Tests 1849 passed
• pnpm --filter @objectstack/plugin-auth typecheck — exit 0;
  check:test-typecheck: OK ... 10 file(s) / 94 error(s) / 23 pinned signature(s) — ledger
  unchanged, no new test-layer debt
• node scripts/check-nul-bytes.mjs — OK (scanned 7977 text file(s) ... no raw ASCII control bytes)
• 62 derived families run (dispatch-gates.mjs --repo objectstack-ai/objectstack, no paths
  passed). The first derivation gave 38; repairing the census below added content/docs/**, and
  the re-derivation returned 62, so the 24 doc families were run too.
• pnpm check:type-check-coverage --re-measure — OK — 22 ledger entr(ies) re-measured in 137.6s, 755 raw tsc error(s) total, none above its recorded number
• pnpm check:skill-examples — 261 prose examples type-check across 3 surface(s)
• pnpm check:dual-build-cjs-loads — exit 0, floors held

Those three refuse to answer on an unbuilt tree rather than green-lighting one;
turbo run build --filter='./packages/*' --filter='./packages/*/*' ran 71/71 successful and
all three then measured green.

One real gate finding, repaired.check-system-context-census went red on pure line rot —
this PR's comments moved an elevation read in auth-plugin.ts from line 1301 to 1310,
orphaning the anchor. Repaired with the script's own --fix (exactly one anchor rewritten),
after which: OK — 109 elevation read sites in 20 packages across 45 files, all anchored; 145 anchors resolve, 27 declared non-read.

Two families NOT MEASURED locally, by their own verdict text — neither is a red.
check-test-completeness exits 3 asking for a saved turbo run test log and instructs a local
family run to record NOT MEASURED; check-half-states exits 3 as an unread instrument on this
host. Both are CI's.

Expected conflict with #14591

#14591 was still open at push time, so this branch is cut from main without it. Two
overlapping regions, both mechanical:

• auth-plugin.ts — the same #8195 comment block. fix(plugin-auth): bind the auth email locale to the workspace language, not the build-time default #14591 rewrites it to describe the
  localization.locale precedence; this PR rewrites it to say the block binds the second
  rung. Intended resolution: keep both — fix(plugin-auth): bind the auth email locale to the workspace language, not the build-time default #14591's precedence text, plus this PR's "this is
  the second rung, the request rung lives in AuthManager" framing and its instruction not to
  restore the superseded reading.
• content/docs/permissions/system-context.mdx line 100 — the same census anchor, moved to
  1345 by fix(plugin-auth): bind the auth email locale to the workspace language, not the build-time default #14591 and to 1310 here. Intended resolution: neither number; re-run
  node scripts/check-system-context-census.mjs --fix on the merged tree and take what it
  writes. The number is derived, so hand-picking a side is guesswork.

Declared narrowing — verification ran UNLOCKED.scripts/pm/os-verify-lock.sh
could not take the shared verify lock on this host: no usable flock. The shared
verify lock is declared Linux-only (flock is util-linux, and a stock macOS does
not ship it), so the commands above were run directly, without the lock —
a declared narrowing, not a silent one. No serialization guarantee held for these
runs, nor for any sibling agent in this container while they ran.

Repo-wide pnpm lint was not run; it is CI's, and no narrowing of it is claimed here.

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

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

3 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 AuthManager (symbol, a top-level class))
• content/docs/kernel/services-checklist.mdx(via AuthManager (symbol, a top-level class))
• content/docs/permissions/authentication.mdx(via AuthManager (symbol, a top-level class))

What this run could not see

• 1 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 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.

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 13bf05d3fe8b1795f3f5aee7daf29ee217590ab9 → packageMentionDocs.

Which tree this was computed on

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

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