docs(spec): widen the #8778 organizationField scope pin to name the cloud#1395 ruling and its three sanctioned consumers

[qq9340100]

Fixes#10110

Unblocks #10101 (the resolver-promotion card is Blocked-by this one).

What this changes

packages/spec/src/data/object.zod.ts carried a scope pin from the #8778 ruling that
admitted exactly ONE consumer of tenancy.organizationField:

Scope-pinned by the #8778 ruling: this is ONE stamp-only declaration key, not the
opening move of a general field-roles mechanism — a consumer other than audit
stamping needs its own ruling before reading it.

The maintainer ruling recorded on cloud#1395 (2026-08-17T03:18Z, accepted in full)
widens that pin by name and requires the widening be declared rather than
discovered. This PR transcribes it next to the pin. The annotation now names:

1. the ruling and its date — cloud#1395, 2026-08-17T03:18Z, with the acceptance
   quote kept in the maintainer's own words;
2. the three sanctioned consumers — audit stamping (plugin-audit's
   resolveRecordOrganizationField), plugin-approvals, and the automation-run
   recorder reached when that resolver is promoted to the shared platform-row resolver;
3. the unchanged refusal posture for any FOURTH consumer — three named
   platform-row writers are still not a general field-roles mechanism.

The original #8778 sentence is kept verbatim and the widening is appended, so the
history reads as declared evolution rather than replacement.

Scope

Annotation/prose only. No schema shape change, no accept/reject behaviour change
(Clause-②: no). The behaviour change — actually wiring consumers 2 and 3 — is
#10101's card, at contract-review tier, and is not started here.

Two test files restated the old "audit stamping ONLY" scope claim in comments and would
now contradict the widened pin. Their prose only is updated; every assertion is
byte-identical (visible in the diff):

• packages/spec/src/data/injected-system-columns.test.ts
• packages/spec/src/data/object.test.ts

Both tests pin read-neutrality, and that claim survives the widening untouched: all
three sanctioned consumers stamp rows, none of them is a read path. The updated prose
says so explicitly.

Deliberately left alone

The .describe() on organizationField still speaks of audit rows. That is a statement
of what reads the key today, and it is still true — consumers 2 and 3 are sanctioned
but not yet wired up. #10101 updates that sentence as the readers actually land; changing
it here would claim a behaviour this PR does not ship. The annotation names this
explicitly so the two do not read as contradicting each other.

Verification

Gate set re-derived from the actual diff with node scripts/pm/dispatch-gates.mjs
(no paths passed — the script derives the change set from the merge base itself). That
run named five families beyond the dispatch prediction; all were run. Everything below
was run at final commit 4b3b6dbb9, on a built workspace:

gate	verdict
pnpm --filter @objectstack/spec test	Test Files 414 passed (414) · Tests 11040 passed (11040)
pnpm --filter @objectstack/spec run typecheck	clean; check:test-typecheck: OK
check:cross-package-test-inputs	OK: 12 package(s) read outside themselves, all declared
check:spec-parsed-alias	ADR-0122 type-alias convention: … OK
check:type-source-resolution	check-type-source-resolution OK — 76 packages … scanned
check:merge-driver	merge driver wiring is consistent
check:slot-lookup	slot-lookup ratchet holds … none new
check-dev-prereqs.mjs	pass (after workspace build)
check:strictness-ledger / check:variant-docs / check:empty-state / check:liveness	all pass
check:engine-double-contract	OK — 329 pinned, 133 in the DEBT ledger, 2 exempt
check:where-matcher	264 matcher(s) discovered, 264 answer … correctly
check:query-options-erasure	ratchet holds … none new
check:type-check-coverage	OK — 64/77 workspace packages type-checked
check:type-check-debt --re-measure	OK — 33 ledger entr(ies) re-measured … none above its recorded number
check:doc-formula-expressions	9 @example(s) judged clean across 965 packages/spec/src files
docs-audit/check-affected-docs.mjs	pass

The clause-② path arm will fire on this PR because it touches packages/spec/src/**.
That is expected and correct per the card — the review confirms the diff is
annotation-only.

Changeset

Carries skip-changeset rather than a .changeset/*.md. This PR publishes nothing: no
authorable key, no export, no schema shape, and no accept/reject behaviour changes — the
diff is comments in one source file plus comments in two test files. Per AGENTS.md a
changeset covers feature work, and by pr-automation.yml's own prescription a PR that
declares no release of its own takes the label. If a reviewer reads the JSDoc reaching
consumers as .d.ts hover text as user-visible, say so and I will add a patch changeset
instead.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

Nothing in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 1 changed package(s)), so this run has no opinion about the docs.

What this run could not see

• 1 changed file(s) yielded no anchor (packages/spec/src/data/object.zod.ts) — pages documenting those are invisible to this run

Coarse fallback — 115 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 cc21aad8ed32a844f3c94267e36d95037002c254 → packageMentionDocs.

[github-actions]

⛔ merge queue 构建失败 — 先分诊，再决定要不要重排

队列构建 32374407797 红了。队列跑的是全量套件（PR 侧 CI 只跑 affected 子集），
所以失败的测试可能在本 PR 没碰过的包里 —— 那不是重排能修的。每次盲目重排都会让排在后面的所有 PR 重建一轮。

失败的 job（日志抽取，best effort）：

• Test Core (3/3) — 失败步骤: Run this shard's tests（日志不可读，点进 job 看）

↳ 失败原因 是判读的关键：超时（Test timed out in … / Hook timed out in …）多半是负载/时序，不是本 PR 的回归；
断言（AssertionError: …）才指向真实的行为改变。两者的 FAIL 行长得一模一样，只有这一行能区分。

跨 PR 相同签名（24h，按失败测试文件聚合）：

• ⚠️本次没有可用的聚合签名（日志里没有能解析出测试文件名的 FAIL 行）—— 这不是「没有同签名的其他 PR」，是这一轮没测到。跨 PR 聚合本次不可用，请手工比对其他 PR 的同类评论。
• ⚠️ 24h 评论账本没读完（超过 5 页仍未读到窗口尽头），所以上面的「不同 PR 数」是下界，不是全量。

历史信号：

• 本 PR 过去 24h 无队列失败记录（首次）。
• 过去 24h 队列共有 38 个失败构建（不含本次）。

分诊清单：

1. 失败测试在本 PR 改动的包里 → 真回归，修 PR。
2. 失败测试与本 PR 无关 → 看上面的「跨 PR 相同签名」；已有汇总 issue ⇒ flaky/环境问题实锤，去那张 issue 上谈，修好前重排只会再烧一轮全队列。
3. 两者都不是 → 可能与同组 PR 语义冲突；等前面的 PR 落地或失败出队后再重排一次即可，不要连续重排。

---

Generated by Claude Code · merge-queue-triage workflow (#4859)

[qq9340100]

Merge-queue dequeue triage (spec-lane PM, session session_016gcKVsiywU9CcS96S5t9qD) — signature extracted by hand since the triage bot could not parse a FAIL line:

• Failing job: Test Core (3/3) in queue build 32374407797, failing task @objectstack/example-showcase#test (ELIFECYCLE exit 1; the other 80/83 turbo tasks green).
• Log signature: repeated Find operation failed across sys_user / sys_member / sys_position / sys_user_permission_set / sys_setting / sys_metadata ("The database refused to run this query … no verdict about the query is claimed"), anchored by Acquire connection error: Error: operation timed out for an unknown reason — a DB connection-acquire timeout, not an assertion. Zero AssertionError / Test timed out lines in the readable tail; the vitest suite that reached its summary in this shard passed (e.g. rate-limit integration 8/8).
• Judgment: infrastructure/load signature, not this PR's regression. This PR's entire diff is JSDoc/comment prose in packages/spec/src/data/object.zod.ts + comment prose in two spec test files — it does not touch the showcase example, any driver, or any query path; per the triage checklist this is branch 2 (failure unrelated to the diff, timeout shape). Queue history shows 38 failed queue builds in 24h, consistent with a load-sensitive full-suite flake.
• Action: re-queued once (single re-queue, per the no-serial-requeue rule). If it is kicked again on the same signature, I will hold it out of the queue and escalate the showcase acquire-timeout as its own infra card instead of burning further queue rebuilds.

---

Generated by Claude Code