docs(core): re-key the §6b-config posture-gate comment to the ruling it cites

[huangyiirene]

Fixes #18380

Clause-②: no

Comment-only repair at packages/core/src/security/resolve-authz-context.ts §6b-config. No behaviour, no assertion, no logic touched — the diff is 32 insertions / 11 deletions, all of them inside one // block.

The defect

The comment justifying the posture gate on the legacy-grant deprecation notice stated the PRE-reversal rule as current fact, and cited a pin as live support for it:

the single promotion is pinned NEVER to consult that variable (bootstrap-platform-admin-walled-owner.test.ts, "never consults the owner-email variable")

The maintainer ruling of 2026-09-08 (decision batch #100, recorded on #16682, comment 5587754690) reversed exactly that point, verbatim:

F3 — the Choice 4A sentence is superseded for this one point. Under single posture the first-boot promotion consults OS_PLATFORM_OWNER_EMAIL first.

What the pin records now — read, not assumed

probe	reading
never consults the owner-email variable, repo-wide under packages/	1 — packages/plugins/plugin-security/src/bootstrap-platform-admin-walled-owner.test.ts:436
firing control owner-email variable, same corpus	4 files ⇒ the 1 above is a reading, not a dead grep

That single hit lives at :434-456, inside a block that opens ⚠️ RE-AUTHORED by #16682, says the case "used to assert the opposite", quotes the maintainer ruling, and is followed by a case titled a declared owner DOES redirect the single-org promotion (#16682), and 'single' still promotes. So the citation resolved and did not support the claim — it recorded its reversal. The repaired comment now cites the pin for what the pin says.

What the reversal did NOT change — the gate's real justification

Verified by reading packages/plugins/plugin-security/src/bootstrap-platform-admin.ts (read-only; another lane):

• The declared-owner leg mints the same unscoped admin_full_access row — promote() is one call site serving both legs (:867), organization_id: null.
• A rig that already holds such a row never reaches that leg: if (!walled && unscopedHolder) return { reason: 'already_have_admin' } (:687) runs first.
• The ruling's own second sentence preserves the standing this gate rests on: "The rest of Choice 4A (platform-admin re-anchor L4 (plugin-security): bootstrap stops granting under walled postures; explain reports config-derived standing; deprecation log for legacy grants #11974, 2026-08-25) stands: retiring the walled write must not retire the single one, and the over-denial invariant (adminPromoted === true with a grant row minted) stays pinned."

⇒ The notice's first half ("it is removed in a later release") is still false for a single rig, so the posture gate stays right. Its second half ("Re-anchor ... by declaring its administrators in configuration") is no longer inert under single — which is what the old comment got backwards — but it still does not move such a rig off the grant row. The repaired comment says that, instead of the reversed premise.

The neighbouring clause was stale too, and is fixed

The old text read "That holds whichever way Choice 4B (#11979) is eventually ruled". Checked rather than assumed: 4B is already ruled, and what is pending is the landing — #11663 comment 5404675670 (maintainer acceptance 2026-08-25), verbatim: "4B is ruled as the sequenced follow-up, not dropped (card filed ...)"; #11979 is open and pm:blocked behind #11978. The clause now says ruled and filed, not landed.

Verification — final head cb602a03b3

Gate derivation and reconciliation were run once, on this head:

node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --ran RANFILE
  -> 47 derived, 45 run, 2 NOT-MEASURED, 0 UNRUN   (exit 0)

• 44 of 45 green.
• pnpm check:cross-package-test-inputs :: exit 1 — the known gate defect [finding] check:cross-package-test-inputs exits 0 or 1 on the same commit depending on whether a dist/ exists — and lint.yml runs it with no build ahead of it, so CI only ever sees the blind leg #18621, not this PR's red. It fires on the mere existence of packages/spec/dist/, which the dependency-closure build creates. Control measured here: with packages/spec/dist/ moved aside the same command exits 0 ("OK: 29 package(s) read outside themselves, all declared"), and restored byte-for-byte afterwards (216 files before, 216 after).
• pnpm check:dual-build-cjs-loads and pnpm check:lean-entry-closure :: exit 3, PREREQUISITE NOT MET — both refuse to measure without a whole-repo dist/. Recorded as NOT MEASURED, declared to CI; a comment-only diff cannot move either.

Targeted, under the shared verify lock:

pnpm --filter '@objectstack/core...' build      -> VERDICT command-exit 0
pnpm --filter @objectstack/core typecheck       -> exit 0 (tsc + examples + check:test-typecheck)
pnpm --filter @objectstack/core test            -> exit 0 — Test Files 51 passed (51), Tests 1316 passed (1316)

Repo-wide pnpm lint (eslint . --no-inline-config) also run in full: exit 0, so no narrowing had to be declared.

Changeset decision: none, skip-changeset — measured, not assumed

@objectstack/core ships files: ["dist", "README.md", "CHANGELOG.md"]. After building the package, those paths were grepped with a positive control:

probe	hits in the published paths
needle — text from this PR's comment ("the notice's FIRST half is false", "re-authored block")	0
second needle — a pre-existing body comment from the same function ("This gates the NOTICE and nothing else")	0
positive control — a docblock on the exported hasPlatformAdminStanding ("the ID-SHAPED platform-admin question")	1 in dist/index.d.ts, 1 in dist/index.d.cts

The control lands, so the instrument is live; the needles do not. A function-body comment reaches no published artifact: the declaration emitter carries only declaration-level docblocks, esbuild drops body comments from dist/*.js / *.cjs, and dropSourcesContent keeps the source text out of dist/*.map. Nothing published moves ⇒ no changeset, and the skip-changeset label is applied.

Acceptance notes

• noted, not filed — bootstrap-platform-admin-walled-owner.test.ts's enclosing describe title still reads single posture — "first user is owner" is ruled reasonable and UNCHANGED (Choice 4A), while the case inside it now asserts that a declared owner redirects the promotion. The block's own re-authored docblock explains the split correctly, so this is a title-level nit, not a defect, and it is in the domain:services lane (read-only for this card). Who will touch it: platform-admin re-anchor follow-up (Choice 4B): config-anchor the single posture — first-user promotion becomes development-only fallback #11979's implementer — Choice 4B rewrites exactly this block when it lands.
• No other stale claim about the single promotion exists in the edited file: OS_PLATFORM_OWNER_EMAIL appears once more, in the hasPlatformAdminStanding docblock, and that text is accurate.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/core, touching 1 documentable anchor(s).

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

• content/docs/deployment/environment-variables.mdx (via resolveUserAuthzGrants (symbol, a top-level function))

⛔ 2 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v16.mdx (via resolveUserAuthzGrants (symbol, a top-level function))
• content/docs/releases/v17/17-1.mdx (via resolveUserAuthzGrants (symbol, a top-level function))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• the SDK route bridge reached 60 of 215 client-bound route-ledger rows — the other 155 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 155: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 100 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 — 24 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 922c7558882403b77e245c8e0ab5634e0ee47e6b → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 976911cede069f717a55ebaf5eaa7f24dac72e4a — the merge of head cb602a03b3d2b1a092f544d8c65de6cebb212c52 into base 922c7558882403b77e245c8e0ab5634e0ee47e6b, 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 976911cede069f717a55ebaf5eaa7f24dac72e4a && git checkout 976911cede069f717a55ebaf5eaa7f24dac72e4a
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 922c7558882403b77e245c8e0ab5634e0ee47e6b cb602a03b3d2b1a092f544d8c65de6cebb212c52 && git checkout -B drift-repro 922c7558882403b77e245c8e0ab5634e0ee47e6b && git merge --no-ff cb602a03b3d2b1a092f544d8c65de6cebb212c52

node scripts/docs-audit/affected-docs.mjs --json 922c7558882403b77e245c8e0ab5634e0ee47e6b

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