docs(spec): organizationField pin annotation reflects the #10101 landing (three consumers live)

[os-steve]

Fixes#11307

What was stale, and why now

The #8778 scope-pin annotation beside tenancy.organizationField in
packages/spec/src/data/object.zod.ts (landed by #10999) transcribed the
cloud#1395 ruling and said, correctly at the time:

• consumer 1 (audit stamping) was "as of this annotation, still the only one
  wired up";
• "Consumers 2 and 3 are sanctioned but not yet implemented: Promote resolveRecordOrganizationField to the shared platform-row resolver (approvals + automation runs), per the ruled cloud#1395 Option A #10101 carries
  that behaviour change";
• the .describe() "still speaks of audit rows … and Promote resolveRecordOrganizationField to the shared platform-row resolver (approvals + automation runs), per the ruled cloud#1395 Option A #10101 updates it as
  the readers actually land".

#10101's PR #11311 (merged 2026-08-23T13:08:26Z) landed both remaining
consumers: resolveRecordOrganizationField was promoted to a shared resolver
in @objectstack/metadata-core (new module record-organization.ts), and
all three sanctioned platform-row writers now call it —

1. audit stamping — plugin-audit/src/audit-writers.ts imports the
   resolver from @objectstack/metadata-core and re-exports it from its
   original path (public surface unchanged);
2. plugin-approvals — approval-service.ts's openNodeRequest (the
   only sys_approval_request insert site) resolves requestOrg via
   createRecordOrganizationResolver;
3. the automation-run recorder — service-automation's
   ObjectStoreSuspendedRunStore resolves the same way on both write paths
   (serialize() for paused rows, recordTerminal() for terminal rows).

Verified directly against main before writing any prose (not from PR
description alone): grep confirms @objectstack/metadata-core exports
resolveRecordOrganizationField / createFieldPresenceProbe /
createRecordOrganizationResolver from record-organization.ts, plugin-audit
re-exports the first two from audit-writers.ts, and both
plugin-approvals/src/approval-service.ts and
service-automation/src/suspended-run-store.ts import
createRecordOrganizationResolver from @objectstack/metadata-core and call
.organizationOf(...) on live write paths.

This PR refreshes:

1. The three stale sentences — rewritten to state all three sanctioned
   consumers are live, citing Promote resolveRecordOrganizationField to the shared platform-row resolver (approvals + automation runs), per the ruled cloud#1395 Option A #10101 / PR Promote resolveRecordOrganizationField to the shared platform-row resolver: approvals + automation runs stamp the SUBJECT record's organization (cloud#1395 Option A) #11311 as the landing.
2. The .describe() on organizationField — now names all three consumers
   and the shared resolver, instead of "consulted exclusively when audit rows
   are stamped".
3. The resolver-home naming — "plugin-audit's resolveRecordOrganizationField"
   is now named as @objectstack/metadata-core's, with plugin-audit's
   re-export noted, everywhere it appeared in the block (including the
   pre-widening paragraph, which had the same stale attribution and the same
   "consulted exclusively by audit stamping" staleness once the resolver
   fanned out to all three writers).

Pin-property-untouched declaration

The pin's load-bearing property is unchanged and still states verbatim:

The ruling sanctions exactly THREE consumers of this key, and no others:

The refusal posture for a fourth consumer (lines below the list) is untouched
byte-for-byte. This PR updates which of the sanctioned three are live,
not the sanction set — no accept/reject behaviour change, no schema shape
change, no new keys. Diff is confined to the JSDoc annotation block above
TenancyConfigSchema and the organizationField.describe() string in
packages/spec/src/data/object.zod.ts, plus the generated docs mirror.

Regen audit

.describe() changes regenerate content/docs/references/**
(check:docs). Ran pnpm --filter @objectstack/spec check:generated first —
it reported exactly 1 of 14 artifacts stale (check:docs), all others green.
Regenerated narrowly with pnpm --filter @objectstack/spec gen:docs (never
the whole set). Diff to content/docs/references/data/object.mdx is exactly
the organizationField describe-text change, one row, no other rows moved.
check:generated reruns clean after regen (see Verification).

needs:contract-review

Diff touches packages/spec/src/**, so per the clause-② path limb this PR
stays DRAFT, held for the PM's contract review — needs:contract-review
applies. The substantive claim under review is narrow: prose accuracy
only, the pin property untouched — the review verifies exactly that (the
"exactly THREE consumers, and no others" sentence and the refusal-posture
paragraph are unchanged; only which consumers are live changed).

Verification

All heavy commands run through scripts/pm/os-verify-lock.sh; exit codes
captured before any pipe; verdicts quoted from the tool's own printed line.
At final commit cf29316fb0.

• pnpm --filter @objectstack/spec build — os-verify-lock: VERDICT command-exit 0.
• pnpm --filter @objectstack/spec check:generated — first run reported 1 of
  14 stale (check:docs, expected from the .describe() edit), regenerated
  narrowly with gen:docs (audited above), rerun reports ✓ All 14 generated artifacts are up to date — os-verify-lock: VERDICT command-exit 0.
• pnpm --filter @objectstack/spec test -- --maxWorkers=2 — Test Files 419 passed (419), Tests 11183 passed (11183) — os-verify-lock: VERDICT command-exit 0.
• pnpm --filter @objectstack/spec typecheck — tsc --noEmit clean,
  check:scripts-typecheck clean, check:test-typecheck: OK (55 file(s) /
  263 error(s) held in the pre-existing shrink-only
  test-typecheck-debt.json ledger, issue @ts-expect-error 退役 pin 在 packages/spec 里是幽灵检查:tsconfig 把 **/*.test.ts 排除出唯一的 tsc --noEmit #5286 — unaffected by this diff)
  — os-verify-lock: VERDICT command-exit 0.
• Gate union derived by node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack (no hand-supplied paths, re-run at the final
  commit — same 3-file change set both times) — 32 local gate(s) named, all
  run to a green verdict: check:changeset-gate-self-tests ·
  check:cross-package-test-inputs · check:doc-anchors ·
  check:doc-authoring · check:doc-formula-expressions ·
  check:doc-security-posture · check:docs-audit-scope ·
  check:docs-redirects · check:empty-state (spec) · check:liveness
  (spec) · check:merge-driver · check:objectui-changeset ·
  check:published-files · check:published-readme-links ·
  check:quick-reference-counts · check:role-word · check:slot-lookup ·
  check:spec-parsed-alias · check:strictness-ledger (spec) ·
  check:test-source-alias · check:type-source-resolution ·
  check:variant-docs (spec) · check-adr-0087-registration ·
  check-changeset-no-major · check-ci-filter-parity ·
  check-cross-package-test-inputs · check-doc-frontmatter ·
  check-empty-changeset · check-plugin-teardown-shape ·
  check-section-landing-index · docs-audit/check-affected-docs. The 32nd,
  check-dev-prereqs, needed a call-site distinction: CI's own gate for it
  (lint.yml) invokes only --self-test, which passes; the full scan (no
  flag) reports the workspace's other 66 packages have no dist/ in this
  fresh worktree — a local dev-server precondition unrelated to this diff
  (unbuilt siblings, not this PR), not something CI enforces here.
  @objectstack/formula and @objectstack/lint were built (their own
  dependency closures first) so their two doc-content gates above could run
  for real rather than being declared unrunnable.
• node scripts/check-nul-bytes.mjs (repo-wide) and
  node scripts/check-adr-anchors.mjs — both clean; the file's one ADR
  anchor (ADR-0120, IndexSchema.unique) is untouched by this diff.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

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

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

• content/docs/releases/v17.mdx(via TenancyConfigSchema (symbol))

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 45 of 222 client-bound route-ledger rows — the other 177 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run: node scripts/docs-audit/affected-docs.mjs --bridge-coverage

Coarse fallback — 126 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 b6d9432d1ac2db89bb18075ff14d2acf150b1932 → packageMentionDocs.

Which tree this was computed on

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

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