auth-mount coverage — follow-ups 1/2/4 LANDED; remaining scope is follow-up 3 (sdk bridge) + the #10975 ledger row (body below is the original census, now historical)

[os-zhuang]

#10050 asked whether POST /organization/add-member being mounted-but-undocumented was a one-off. It was not. Census below, measured on origin/main at 4544be260, with positive controls on both legs.

Population

auth-plugin.ts mounts routes directly on the raw Hono app, ahead of the better-auth catch-all. Those mounts are the ObjectStack-owned auth surface — the catch-all never sees them, so the vendor's own route table cannot account for them.

Enumerated by matching rawApp.<verb>(\${basePath}/…`)inpackages/plugins/plugin-auth/src/auth-plugin.ts(excluding therawApp.allcatch-all and the.well-known/*mounts, which are not underbasePath`): 17 routes.

Leg 1 — documented?

Test: does the literal wire path /api/v1/auth<path> appear anywhere in the hand-written docs corpus (392 .md/.mdx files under content/docs, content/docs/releases/** excluded as release-owned)?

6 of 17 undocumented, before this card's PR:

Route	In a ledger?
POST /api/v1/auth/admin/sso/request-domain-verification	no
POST /api/v1/auth/admin/sso/verify-domain	no
POST /api/v1/auth/admin/unban-user	vendor inventory only
GET /api/v1/auth/bootstrap-status	yes — objectstack / sdk
POST /api/v1/auth/organization/add-member	yes — objectstack / server-only
POST /api/v1/auth/set-initial-password	no

#10050's PR documents the last-but-one, leaving 5 of 17.

⚠️ Two refinements the raw number hides. set-initial-password is named once in prose (authentication.mdx, "offers set-initial-password") without its URL — named, not documented. And add-member was named three times in tenancy-modes.mdx with no URL anywhere, which is how it stayed invisible while looking discussed.

Positive control (leg 1): the same expression, run before the docs were written, returned organization/add-member — the known-present member of the set. So a zero would have been a real zero. Control output: POSITIVE CONTROL organization/add-member present in undocumented set: true.

Leg 2 — ledgered?

auth-route-ledger.ts has two halves: the reviewed AUTH_ROUTE_LEDGER rows and the machine-maintained BETTER_AUTH_MOUNTED_SURFACE inventory. A route in neither is unaccounted for.

9 of 17 appear in neither half:

/admin/import-users · /admin/oauth2/toggle-disabled · /admin/sso/register · /admin/sso/register-saml · /admin/sso/request-domain-verification · /admin/sso/verify-domain · /admin/unlock-user · /set-initial-password · /sys-oauth-application/register

Only 3 of the 17 carry a reviewed source: 'objectstack' row: /config, /bootstrap-status, /organization/add-member. The rest are either attributed to the vendor (correct where the vendor also declares the path — the ObjectStack mount shadows it) or absent entirely.

Verified two ways that agree: a regex parse of the ledger source, and a direct grep "auth<path>'" per route. Positive control (leg 2): the same grep returns 1 for /organization/add-member and 1 for /config, so an absence is an absence and not a broken pattern.

Leg 3 — why nothing caught it

Both of #10050's asks land on the same hole, and it is upstream of either ledger row.

scripts/docs-audit/affected-docs.mjs --bridge-coverage on this tree:

  client-bound ledger rows ... 221
    reachable ................ 45
    UNREACHABLE .............. 176
        55 of 55   unreachable  packages/plugins/plugin-auth/src/auth-route-ledger.ts

Every client-bound row in the auth ledger is unreachable by the sdk doc-nomination bridge. The bridge finds route registrars by filename convention — REGISTRAR_FILE_RE = /(?:^|\/)(?:[\w.-]*route[\w.-]*|[\w.-]*-server)\.ts$/ — and the file that actually registers this surface is auth-plugin.ts, which matches neither alternative. No registrar tail is produced for the auth surface, so no auth ledger row can be selected, so the sdk anchor never nominates a doc for an auth route.

add-member is then invisible a second time on top of that: its row is disposition: 'server-only' with no client, so it is not even among the 55 client-bound rows the bridge fails to reach.

The 221→45 shape is already recorded in #9572 (closed). What is new here is the auth slice being 55 of 55 and the concrete cause being one filename convention — plus the demonstration that this is what let a route mount and its documentation gap ship separately with nothing objecting.

⛔ Deliberately not acted on: scripts/docs-audit/affected-docs.mjs is being edited by open PR #10501, which is fixing a different silent-parse defect in the same file. Any remedy here belongs after that lands.

Suggested follow-ups

1. Document the 5 remaining undocumented mounts (or record a deliberate "server-only, not user-facing" verdict for each — bootstrap-status may well be one).
2. Ledger the 9 unledgered mounts as source: 'objectstack' rows, which is what the ledger's own header says objectstack mounts are for.
3. Decide whether the sdk bridge should reach the auth surface at all — either by teaching REGISTRAR_FILE_RE about auth-plugin.ts, or by declaring registrars explicitly rather than by filename convention. After fix(docs-audit): a PARTIAL ledger read is a verdict, not a smaller number #10501.
4. Consider a gate: a rawApp mount under basePath with no ledger row is exactly the state that produced [finding] sys_member "Add Member" action targets POST /organization/add-member, which better-auth 1.7.0-rc.2 never mounts (server-only) — on multi-org there is NO remaining UI path to attach an existing user to an org #9941 and docs: the newly mounted POST /organization/add-member is undocumented — and it is the ONLY multi-org path to attach an existing user #10050, and it is mechanically detectable.

Refs

#10050 (the card this sweep came from) · #9941 / PR #10049 (the mount) · #9572 (the 221→45 bridge measurement, closed) · #10501 (open, owns affected-docs.mjs) · #9969 / #9652 (adjacent: vendor /admin/ routes and their admit sets)

[os-zhuang]

Triage (first-touch grading): promoted finding → pm:queue, domain:services (landing surface: packages/plugins/plugin-auth/src/auth-route-ledger.ts + content/docs route pages), type Task.

Scope ruling: follow-ups 1 + 2 only — document the 5 remaining undocumented mounts (or record a per-route "server-only, not user-facing" verdict where that's the truth, e.g. bootstrap-status candidates) and ledger the 9 unledgered mounts as source: 'objectstack' rows. Both are exactly what the ledger's own header declares itself for; the census with positive controls on both legs is dispatch-ready evidence.

Fenced out of this card: follow-up 3 (the REGISTRAR_FILE_RE / bridge fix) — scripts/docs-audit/affected-docs.mjs is open PR #10501's surface; file it as its own card after #10501 lands. Follow-up 4 (a mount-without-ledger-row gate) — worthwhile, file separately once 1+2 establish the clean baseline it would ratchet.

---

Generated by Claude Code

[os-warren]

Claim: PM domain:services 派发（范围 = 建议 1 + 2，见下）

• Session: 0f14f70b-575c-5f2b-a235-4000a55db042
• Branch: claude/issue-10534-auth-mount-ledger-and-docs
• Worktree: ../objectstack-10534（per-repo；⛔ 不在共享主检出上编辑；⛔ 不用 git stash）
• File surface: packages/plugins/plugin-auth/src/auth-route-ledger.ts + content/docs/** 的相关页面。⛔ 零 packages/spec 所有权；⛔ 不碰 content/docs/releases/（卡面自己已把它排除在语料之外，别再碰回来）。
• Container & model: claude-opus-5
• Clause-②: no —— 补文档与补账本行，不改任何路由的挂载、行为或接受/拒绝集。⚠️ 若你发现某个 mount 的行为与账本将要声明的不符，⛔ 不要改行为去迁就账本，停下报告。

本轮范围

✅ 建议 1 — 5 个仍未文档化的 mount：/admin/sso/request-domain-verification、/admin/sso/verify-domain、/admin/unban-user、/bootstrap-status、/set-initial-password。
✅ 建议 2 — 9 个两个账本半边都不在的 mount，补为 source: 'objectstack' 行。

⛔ 建议 3（sdk bridge / REGISTRAR_FILE_RE）不做 —— 卡面明写 scripts/docs-audit/affected-docs.mjs 被开着的 PR #10501 占用，补救要等它落地。先核实 #10501 是否仍开着（自己查，别采信我或卡面的转述）；仍开则连碰都不要碰那个文件。
⛔ 建议 4（加门禁）不做 —— 那是门禁设计决策，不是本卡的机械活。若你在实现中拿到了「这条门禁该怎么写」的具体证据，写进报告，由我决定是否立卡。

判断成分：不要机械填表

⚠️ 这两条都不是纯机械，卡面自己留了口子：

• 建议 1 允许「或为每个记录一个刻意的 server-only, not user-facing 裁决」，并且点名 bootstrap-status 很可能就是这一类。文档化和裁决为不面向用户是两种不同的答案，逐个给理由。
• 建议 2 的每一行都要定 disposition（client-bound 还是 server-only）。这决定它是否进入那 55 行 client-bound 群体，不是格式字段。add-member 之所以第二次隐形，正是因为它是 server-only 且无 client。

⛔ 任何一个你定不下来的，停下并在报告里点名，不要为了让表填满而猜一个 disposition。今晚本车道已经两次因为「选最近的允许选项」而差点写下假声明。

实现要求

1. 两条腿都要有正向对照 —— 卡面自己做了（leg 1 用 organization/add-member 已知在集内、leg 2 用 /config 与 /organization/add-member 各返回 1）。你重新测量时照做：零结果在有对照之前不是发现。
2. 路由枚举以卡面的表达式为准（rawApp.(\${basePath}/…`)，排除 rawApp.allcatch-all 与.well-known/*），但**自己跑一遍**确认仍是 17 条 —— main 从 4544be2` 起已经动过。
3. 文档页里必须出现字面 wire path。卡面记了一个陷阱：set-initial-password 在 authentication.mdx 里被提到过名字但没有 URL，add-member 在 tenancy-modes.mdx 里被提了三次也没有 URL —— 「被提到」不等于「被文档化」，这正是它们隐形的方式。
4. 门禁并集在最终提交之后、干净工作树上跑。⚠️ 今晚四个门禁未被派生点名（class [finding] Every PM dispatch list is short by the same ~5 changeset-triggered gate families — they are path-derivable, but the changeset does not exist yet when the list is derived #10309），其中两个专咬 plugin-auth：显式加跑 pnpm check:route-envelope 与 check:dispatcher-error-vocabulary（各含 --self-test），不要等派生点名。另外你改 content/docs/**，显式加跑 pnpm --filter @objectstack/spec check:docs 与 check:affected-docs。
5. ⚠️ @objectstack/plugin-auth 的 TEST_DEBT：卡 [finding] @objectstack/plugin-auth's TEST_DEBT records 109 where tsc now reports 98 — an 11-error surplus opened by PR #10614 #10615 报告账本记 109 而 tsc 现报 98。⛔ 不要动那个数字，也不要跑 --lower；若你的改动让它变化，如实报告。
6. 消融：对新增的账本行，预测签名先写再跑（删掉一行应让门禁点名它），git hash-object 证明恢复逐字节一致。

---

Generated by Claude Code

[os-warren]

os-dev-report

{
  "issue": 10534,
  "status": "done",
  "branch": "claude/issue-10534-auth-mount-ledger-and-docs",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/10660",
  "premise_still_valid": true,
  "summary": "Follow-ups 1+2 only. Re-ran both census legs myself on 47aff0938 with positive controls: population still 17. Leg 2 reproduced the card exactly (9 unledgered). Leg 1 did NOT: the card's test is a substring test and /admin/sso/register is a PREFIX of /admin/sso/register-saml, so it was credited as documented on the strength of its longer sibling's URL. Boundary-aware, it is 6 undocumented, not 5. All 6 are now documented with literal wire paths (none earned the 'server-only, not user-facing' verdict -- bootstrap-status specifically does NOT, because client.auth.bootstrapStatus() is a shipped SDK method ledgered 'sdk', which falsifies the card's hypothesis). 8 of the 9 unledgered mounts gain source:'objectstack' rows, all disposition:'server-only', decided per route by measuring who builds the URL rather than defaulted. The 9th, POST /api/v1/auth/set-initial-password, is DELIBERATELY NOT LEDGERED and escalated below -- see open_questions. The conformance pin over the objectstack-sourced set moves 3 -> 11 in the same edit. No route's mounting, behaviour or accept/reject set changed (Clause-2 no); zero packages/spec and zero content/docs/releases/** ownership.",
  "tests": "All at final commit 3115f7939, clean worktree; every exit code captured BEFORE any pipe (cmd > file 2>&1; EXIT=$?), never after a tail. Gate family derived by `node scripts/pm/dispatch-gates.mjs` with NO path arguments (5 paths, 20 matched families + convention-triggered set). SUITE: `pnpm --filter @objectstack/plugin-auth test` -> 'Test Files 61 passed (61) / Tests 1359 passed (1359)'. TYPES: `pnpm --filter @objectstack/plugin-auth typecheck` (tsc --noEmit) exit 0. GATES, each quoted as it printed: check:affected-docs '✓ affected-docs self-test: 281 cases pass.'; check:docs-audit-scope '✓ docs-accuracy-audit scope is in sync with content/docs/: 189 hand-written doc(s).' + '✓ release-owned pages are in scope and read-only: 9 page(s) ... review-only'; check:doc-anchors '✅ ... slug parity, custom ids, duplicate counters ... (277 live fragment links)'; spec check:docs '✅ 229 generated files in sync with packages/spec'; check:nul-bytes 'OK (scanned 6212 text file(s) ... no raw ASCII control bytes).'; check:route-envelope + --self-test '✓ Plugin-mounted Hono routes -- 12 module(s) audited ... 8 conformant, 0 ratcheted'; check:dispatcher-error-vocabulary + --self-test '8 shapes + 102 assertions OK'; check:where-matcher '✓ ... 271 matcher(s) discovered, 271 answer the combinator battery correctly'; check:cross-package-test-inputs 'OK: 13 package(s) read outside themselves, all declared'; check:type-check-coverage '✓ --self-test -- 23 semantic + 24 observation + 25 re-measure + 28 built-closure + 9 auto-lowering case(s) hold.'; plus exit-0 on check:engine-double-contract, check:query-options-erasure, check:slot-lookup, check:test-source-alias, check:type-source-resolution, check:role-word, check:docs-redirects, check:published-readme-links, check:objectui-changeset, check:changeset-gate-self-tests, check-changeset-no-major, check-empty-changeset, check-adr-0087-registration, and spec check:{empty-state,liveness,strictness-ledger,variant-docs}. CLASS #10309 CONFIRMED LIVE: the derivation named NEITHER check:route-envelope NOR check:dispatcher-error-vocabulary for this change set -- both were run only because the dispatch named them explicitly. DECLARED NARROWING: check:type-check-debt --re-measure was NOT run (it refuses on an unbuilt worktree and needs the full workspace closure built under the container-shared lock); substituted the package typecheck above; CI runs the ratchet regardless. TEST_DEBT (#10615): untouched -- number not edited, --lower not run, nothing re-measured; the edited test file is pre-existing so no package gains/loses test-file coverage. ABLATION, signature predicted in writing BEFORE running: deleting the 'POST /api/v1/auth/admin/unlock-user' row should make the objectstack-mounted pin fail with own at 10 instead of 11, NAMING the route. Observed exactly: 'AssertionError: expected [ ...(10) ] to deeply equal [ ...(11) ]' with '- \"POST /api/v1/auth/admin/unlock-user\",', 'Tests 1 failed | 9 passed (10)'. NO REBUILD IS INVOLVED and that is PROVEN, not asserted: the suite imports the ledger relatively (from './auth-route-ledger', conformance test line 27), so resolution cannot go through the package exports field and no dist/ sits between edit and run. Mutation confirmed on disk (row grepped to 0), not from an editor exit code. Restore proven byte-identical: git hash-object 123e1a87dcedf63dc188cf680c2fc3ed08417913 before and after, git diff --quiet exit 0. CENSUS CONTROLS: leg 1 -- '/api/v1/auth/sign-in/email strict-present: true', '/api/v1/auth/zzz-not-a-route present: false', 'add-member strict-present: true' (the card's own add-member control now correctly reports false since #10050's PR landed, so it was replaced rather than dropped); leg 2 -- ledger grep returns 1 for /config and 1 for /organization/add-member; SDK-caller grep control -- bootstrap-status 2, sign-in/email 2, get-session 6, so the zeros for all 8 ledgered routes are real zeros.",
  "open_questions": [
    {
      "question": "What disposition should `POST /api/v1/auth/set-initial-password` carry? I stopped rather than guess. Evidence: zero ObjectStackClient methods build it (control-verified). Its only real caller is @object-ui/auth's createAuthClient, which builds exactly four auth URLs -- /config, /get-session, /list-accounts, /set-initial-password -- and the first THREE are all ledgered `sdk` with ObjectStackClient methods (auth.getConfig, auth.me, auth.accounts.list). Its own sibling branch in the same Console password card, changePassword, is also ledgered `sdk`. So its peer group is uniformly SDK-expressed except itself, which is the shape of `gap` ('should be in the SDK and is not'), not `server-only` ('deliberately not SDK surface'). But `gap` is ratcheted to <= 0 by auth-route-ledger.conformance.test.ts. Contrast /admin/import-users, which is ALSO called by a hand-written objectui client and which I DID ledger server-only: its peer group (/admin/create-user, /admin/ban-user, /admin/set-user-password) is uniformly SDK-absent, so the intent claim is consistent there. The discriminator is the peer group, not convenience -- which is exactly why this one cannot be settled from the tree.",
      "options": [
        "A. Rule it genuinely server-only by decision -- the Account/Console SPA owns its own auth client and ObjectStackClient deliberately does not cover the SSO-onboarding password path. Costs nothing mechanically; I can add the row in a follow-up. Requires a maintainer to actually MEAN it, because the row then declares intent.",
        "B. Rule it a real `gap` -- accept that ObjectStackClient should express setInitialPassword. Needs the gap ratchet moved from 0 to 1 with a note, and the row says so honestly until the SDK method lands.",
        "C. Close the gap instead: add `auth.setInitialPassword` to ObjectStackClient and ledger the row `sdk`. This is a public-surface widening and a behaviour change, so it is out of Clause-2 `no` and belongs on its own card.",
        "D. Leave it unledgered (today's shipped state). Rejected as a resting place: unaccounted-for is precisely the state this card exists to end, and it would silently survive as the one remaining member of the set."
      ],
      "recommendation": "B, then C as the follow-through. B is the only option that states today's truth without either a false intent claim or a surface change: the SDK does not express it, its entire peer group does, and nobody has decided that asymmetry is intentional. A is the option I would have taken if I were filling the table, and I think it would be a false declaration -- there is no evidence of deliberateness, only of absence. Moving a ratchet from 0 to 1 is visible, reviewable and reversible; writing 'deliberately not SDK surface' about a route nobody deliberated is neither. If the maintainer prefers not to move the ratchet at all, A is defensible ONLY as an explicit ruling recorded in the row's note (the add-member precedent does exactly that, with a quoted decision), never as a default."
    },
    {
      "question": "Follow-up 3's stated blocker has cleared, and the PM asked me to verify rather than take it on trust. PR #10501 (which the card and the claim comment both describe as OPEN and owning scripts/docs-audit/affected-docs.mjs) is MERGED -- closed 2026-08-21T02:46:52Z, merged true, commit 4e7229a6. I did not touch that file, because the scope ruling admits follow-ups 1 and 2 only. But the reason for the fence no longer holds.",
      "options": [
        "A. File follow-up 3 (teach REGISTRAR_FILE_RE about auth-plugin.ts, or declare registrars explicitly) as its own card now -- the card's own text says 'file it as its own card after #10501 lands', and it has landed.",
        "B. Hold it until this PR merges, so the bridge work starts from the completed ledger rather than a moving one."
      ],
      "recommendation": "A. The two do not overlap in file surface (this PR touches no scripts/), and the card's own instruction was conditional on #10501 landing, which it has. Worth noting for whoever takes it: the auth ledger's client-bound row count is unchanged by this PR -- all 8 new rows are server-only with no `client`, so the '55 of 55 unreachable' figure the card measured does not move, and the bridge card's baseline is still valid."
    }
  ],
  "out_of_scope_findings": [
    "filed as #10658: check-error-code-casing prints '✓ no lowercase error codes in 4346 scanned file(s) (ADR-0112)' while two ObjectStack-authored lowercase codes ship in packages/plugins/plugin-auth/src/register-sso-provider.ts (lines 411 request_domain_verification_failed, 465 verify_domain_failed) -- a literal reached through an `||` fallback (`code: parsed?.code || 'x'`) matches none of the gate's four recognizers, all of which require the quote to sit directly after the position token. Verified with a positive control on the gate's own regex: it returns ['oops_bad'] for the direct spelling and [] for the fallback spelling. Repo-wide extent measured at exactly 2 (non-test). Same 'partial read reported as complete' class PR #10501 just closed for a different scanner, and the third instance of the pattern across the error-code gates after #9223 and #9460. NOT fixed here: different defect class from this card, and renaming the codes is wire-visible (a dogfood test pins verify_domain_failed by name).",
    "NOT filed, reported for the PM's follow-up-4 decision as instructed -- concrete evidence on how the proposed mount-without-ledger-row gate should be written. (1) A mount-vs-docs leg MUST match the wire path with a right boundary; matching by substring silently credits a prefix route to its longer sibling, which is the artifact that made this card's own leg 1 read 5 instead of 6. (2) The mount-vs-ledger leg is cheap and already nearly exists: auth-route-ledger.conformance.test.ts's 'the objectstack-mounted rows' pin asserts the source:'objectstack' set exactly, so it already fails when a row DISAPPEARS. What it cannot do is fail when a MOUNT appears with no row, because both sides of it are hand-written -- the missing half is enumerating rawApp mounts from auth-plugin.ts source and diffing against the ledger, which this card proves is mechanically reliable (the same expression reproduced 17/17 across two different commits). (3) The gate must exclude rawApp.all and rawApp.use, or the catch-all and the IP-gate middleware both read as unledgered mounts. (4) A disposition cannot be inferred mechanically -- the set-initial-password question above is exactly the judgement such a gate would force onto whoever adds route 18, which is an argument FOR the gate, but it means the gate's failure text should demand a disposition with a rationale, not merely a row."
  ]
}

---

Generated by Claude Code