docs(adr): ADR-0120 — explicit unique-scope vocabulary (organization/global) and NULL-safe per-organization uniqueness (#4986, #5030) (#5054)

* docs(adr): ADR-0120 draft — explicit unique-scope vocabulary and NULL-safe tenant uniqueness (#4986, #5030)

Proposed-status draft for maintainer review. Records the amendment of the
#3696 verbatim-declared-index decision into an explicit 'global' | 'tenant'
scope vocabulary (D1), a lossless ADR-0087 D2 conversion for stored
metadata (D2), NULL-safe COALESCE tenant key parts fixing #5030 (D3), the
duplicate-pre-flight migration ceremony (D4), authoring gates (D5), the
five-surface truth sweep (D6), 17.x -> 18 staging (D7), and the freeze on
unilateral driver-sql changes until acceptance (D8). Docs-only: no code
semantics change in this PR.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Akrzh2mHi2siSNVPPtfTw7

* docs(adr): ADR-0120 — deployment-mode portability is a first-class constraint

Maintainer requirement from #4986 review: one metadata app must run
unmodified under single-org and multi-org deployment; the author states
the business boundary of a unique constraint, never the topology. Adds
the governing principle, a dedicated Mode portability section with the
declaration x mode matrix and both mode-transition stories (single->multi
relaxes with zero migration; multi->single tightens through the D4
ceremony), matrix row S13, a D1 anchor line, and the dual-mode
conformance requirement in Acceptance tests.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Akrzh2mHi2siSNVPPtfTw7

* docs(adr): ADR-0120 — organization/company vocabulary, three-posture portability

Maintainer review round 2 on #4986. Two corrections from review:

1. The authorable word 'tenant' was ambiguous — the platform has a second
   tenancy sense (database-per-customer environments) besides row-level
   organization scoping. The scope tokens are now 'organization' and
   'company'; 'tenant' is not accepted even as an alias, and a Terminology
   section records why.

2. Multi-org splits into group (one corporate family) and isolated
   (organizations are separate customers) postures per ADR-0105 D1, which
   makes 'company-wide unique' posture-VARIANT: installation-wide under
   group, per-organization under isolated. A third scope word 'company' is
   added, resolved to one of the two existing physical shapes at
   registration where the posture is known; posture transitions re-resolve
   it through the D4 ceremony. New matrix row S14, reworked Posture
   portability section with the declaration x posture table and the
   acquisition/consolidation transition stories, acceptance coverage for
   all three postures, and two new open questions (token name; where the
   isolated-posture 'global' advisory lives).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Akrzh2mHi2siSNVPPtfTw7

* docs(adr): ADR-0120 — posture transitions are rare and not automated

Maintainer ruling on #4986 review round 3: a posture change is a planned
re-platforming event, expected to be rare; the platform's obligation is a
well-defined target state and a trustworthy migrate plan, not built-in
transition machinery. Per ADR-0087's operating assumption the migrator is
an AI agent that writes the upgrade script from the D4 plan (including the
duplicate probe report). Transition acceptance coverage slimmed to one
smoke assertion; D1 and Consequences reworded to match.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Akrzh2mHi2siSNVPPtfTw7

* docs(adr): ADR-0120 — drop the 'company' scope; two-word vocabulary, deployment-seam handling for S14

Maintainer ruling round 4: a posture-resolved third word is the only token
in the vocabulary that cannot be used without first understanding the
posture spectrum — too easy for AI authors to confuse — and the scenario
it served is rare. Vocabulary stays 'global' | 'organization'. The S14
residual (company-wide keys in a posture-portable app) moves to the
deployment seam: author 'global', and under isolated posture os doctor /
migrate plan surface each 'global' business unique as an explicit decision
point (confirm or rewrite to 'organization', AI-authored install
adjustment). Posture flips now have zero automatic schema consequences by
construction. The rejected design is recorded in Alternatives #6 per
PD #13; open questions renumbered (now four).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Akrzh2mHi2siSNVPPtfTw7

* docs(adr): ADR-0120 — resolve all four review questions (maintainer decisions)

Q1: COALESCE literal is '__global__' (flipped from '') — self-describing
constraint-violation errors for AI ops triage, and one vocabulary with the
autonumber GLOBAL_TENANT; org creation reserves the token, storage stays
NULL. Q2: field-level bare true stays valid indefinitely; examples and
scaffolding emit 'organization' as non-normative guidance. Q3: D3 ships in
17.x — waiting compounds the duplicate sets the D4 probe must report, and
the protocol-18 wave is physically empty either way. Q4: the isolated-
posture decision point is a hard install-time gate with recorded
confirmations (new D5e); doctor/plan keep the advisory form for pre-gate
installs and posture changes. Open-questions section converted to a
resolved-decisions record.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Akrzh2mHi2siSNVPPtfTw7

* docs(adr): ADR-0120 accepted (maintainer decision, 2026-08-04)

Status flipped Proposed -> Accepted. Implementation not started: the
17.x additive wave (D7) is the first work package; the protocol-18 items
(D2 conversion, bare-true rejection) stay deferred to the 18 train.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Akrzh2mHi2siSNVPPtfTw7

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-zhuang