feat(spec,lint): unique 范围显式词汇 'organization' + D5a/D5b lint 规则(ADR-0120 17.x 波,#4986) (#5208)

* feat(spec,lint): unique 范围显式词汇 'organization' + D5a/D5b lint 规则 (#4986, ADR-0120 17.x 波)

- UniqueScopeSchema → boolean | 'global' | 'organization'(D1,17.x 纯增量);
  'tenant'/'org' 拒绝且报错指名 'organization'(§Terminology,strictTenancyError 先例)
- IndexSchema.unique 注释与 describe() 按 D1/D6 重写:verbatim 收窄到 'global';
  'organization' = 注册期并入 NULL-safe 组织键部(COALESCE 物化随 #5030);
  裸 true 弃用(17.x 警告 → 协议 18 拒绝,#5082)
- UniqueScopeSchema 文档块单租户假豁免替换为 D3 真相(NULL 桶 + COALESCE);
  Resolved #2 非规范性引导入注释(示例/脚手架输出 'organization',裸 true 永久合法)
- 新导出 isOrganizationUnique;isUniqueDeclared 计入 'organization'(ADR-0078)
- lint 新规则 unique/unscoped-declared-index(D5a,警告,只判拼写不推断租户性);
  R10 unique/double-declaration 四象限重写(D5b),fix 改说 'organization' 词汇
- 测试:spec unique-scope 契约测试扩充;cli data-model-rules 测试按四象限重写
- 再生成:references/data/{field,object}.mdx、api-surface.json;adr-anchors 三条;
  changeset 两包(spec minor / lint minor)

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

* chore(spec): regen api-surface after origin/main merge (merge-driver deferred artifact)

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

* fix(lint): unique/unscoped-declared-index 独立注册进 AUTHORING_RULES,不再搭车 R10

导出面即承诺(#4409 wiring 测试):导出的规则必须入注册表或入账。搭车在
lintUniqueDeclarations 里跑对注册表不可见,且 validate/build 会经两条路径
各报一次。改为:R11 自己的 AUTHORING_RULES 条目(validate/build,advisory),
lintDataModel 直接调用它服务 os lint —— 三命令全覆盖,每条 finding 恰好一报。

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

.changeset/unique-scope-lint-rules.md

@@ -0,0 +1,27 @@
+---
+"@objectstack/lint": minor
+---
+
+feat(lint): uniqueness-scope rules speak the ADR-0120 vocabulary (#4986, D5a/D5b)
+
+- **New rule `unique/unscoped-declared-index`** (warning, advisory): a declared
+  index with bare `unique: true` — the spelling whose scope is unstated, the
+  #4986 trap. Fires on the spelling alone (no tenancy/posture inference —
+  `organization_id` is kernel-injected at registration, so an authoring-time
+  guess would be wrong half the time; see #4698). The fix names both words:
+  `'global'` (installation-wide — exactly today's behavior) or
+  `'organization'` (one holder per organization). Protocol 18 rejects the
+  spelling (#5082). Exported as `lintUnscopedDeclaredIndexes` +
+  `UNIQUE_UNSCOPED_DECLARED_INDEX`, registered as its own AUTHORING_RULES
+  entry (validate/build) and called by `lintDataModel` for `os lint`, so all
+  three commands report it — each finding exactly once.
+- **R10 `unique/double-declaration` rewritten as the four-quadrant scope
+  matrix** (ADR-0120 D5b): field `true`/`'organization'` × declared `'global'`
+  (or bare `true`, its deprecated spelling) on the same single column =
+  CONTRADICTION (the installation-wide index wins physically; the
+  per-organization intent is silently dead) — and the mirror, field `'global'`
+  × declared `'organization'`, likewise; same scope on both sides = REDUNDANCY
+  (the same index declared twice). The old field-`'global'` exemption is gone
+  (now reported as redundancy), and the fix text replaces the hand-written
+  `fields: ['organization_id', …]` advice with the `'organization'` spelling —
+  the hand-written composite is not NULL-safe (#5030).

.changeset/unique-scope-organization-vocabulary.md

@@ -0,0 +1,34 @@
+---
+"@objectstack/spec": minor
+---
+
+feat(spec): `unique` scope vocabulary gains `'organization'` — scope is said, not positional (#4986, ADR-0120 D1/D6)
+
+`UniqueScopeSchema` (field-level `unique` and `IndexSchema.unique`) widens from
+`boolean | 'global'` to `boolean | 'global' | 'organization'`. Purely additive
+in 17.x — no existing spelling changes meaning:
+
+- **Field-level** `'organization'` is the explicit synonym of `true`
+  (per-organization uniqueness, identical materialization through the driver
+  predicates: `isUniqueDeclared` counts it, `isGlobalUnique` does not). Bare
+  `true` stays valid indefinitely; official examples and scaffolding emit
+  `'organization'` in new code (non-normative, ADR-0120 Resolved #2).
+- **Declared-index** contract is now stated per word (ADR-0120 D1, amending
+  #3696): `'global'` = today's verbatim behavior — materialized over exactly
+  `fields`, no organization column injected; `'organization'` = the driver
+  prepends the NULL-safe organization key part
+  (`COALESCE(organization_id, '__global__')`, ADR-0120 D3) at registration —
+  materialization lands with #5030's driver PR, which this change must follow;
+  bare `true` = the deprecated positional spelling of `'global'` — warned in
+  17.x by lint `unique/unscoped-declared-index`, rejected at protocol 18
+  (#5082).
+- **Rejected words carry the fix**: `'tenant'` and `'org'` are not accepted and
+  are not aliases — the parse error names `'organization'` (ADR-0120
+  §Terminology).
+- New export `isOrganizationUnique` — detects the explicit `'organization'`
+  spelling, single source of truth for the declared-index distinction across
+  SQL/Mongo index sync.
+- The `UniqueScopeSchema` doc block's false single-tenant exemption ("the
+  tenant column is constant, so the composite index degenerates to the
+  single-column one" — falsified by #5030: the constant is NULL and SQL UNIQUE
+  is NULL-distinct) is replaced with the D3 truth (NULL bucket + COALESCE).

content/docs/references/data/field.mdx

@@ -80,7 +80,7 @@ const result = AddressSchema.parse(data);
 | **storage** | `{ notNull?: boolean }` | optional | Physical storage constraints (ADR-0113). Owns the DDL the write contract deliberately does not imply. Absent = no storage-level constraint requested. |
 | **searchable** | `boolean` | optional | Is searchable |
 | **multiple** | `boolean` | optional | Allow multiple values (Stores as Array/JSON). Applicable for select, lookup, file, image. |
-| **unique** | `boolean \| 'global'` | optional | Unique constraint. true = unique within the tenant (composite with the tenant column on tenant-scoped objects); 'global' = unique platform-wide across all tenants |
+| **unique** | `boolean \| 'global' \| 'organization'` | optional | Unique constraint and its scope (ADR-0120). 'organization' = one holder per organization (NULL-safe composite with the organization key part on organization-scoped objects) — prefer this explicit spelling in new code; true = same per-organization scope (positional synonym, stays valid); 'global' = one holder across the whole installation. 'tenant'/'org' are rejected — the word is 'organization' |
 | **defaultValue** | `any` | optional | Default value |
 | **maxLength** | `number` | optional | Max character length |
 | **minLength** | `number` | optional | Min character length |
@@ -245,6 +245,12 @@ Type: `'global'`
 
 ---
 
+#### Option 3
+
+Type: `'organization'`
+
+---
+
 
 ---
 

content/docs/references/data/object.mdx

@@ -68,7 +68,7 @@ const result = ApiMethod.parse(data);
 | **name** | `string` | optional | Index name (auto-generated if not provided) |
 | **fields** | `string[]` | ✅ | Fields included in the index |
 | **type** | `Enum<'btree' \| 'hash' \| 'gin' \| 'gist' \| 'fulltext'>` | ✅ | Index algorithm type |
-| **unique** | `boolean \| 'global'` | ✅ | Whether the index enforces uniqueness. Materialized over exactly `fields` — no tenant column is injected; list the tenant column explicitly for a per-tenant index. 'global' is a synonym of true, for symmetry with field-level `unique` |
+| **unique** | `boolean \| 'global' \| 'organization'` | ✅ | Whether the index enforces uniqueness, and at which scope (ADR-0120). 'global' = materialized over exactly `fields`, no organization column injected — one holder across the whole installation; 'organization' = the driver prepends the NULL-safe organization key part (COALESCE(organization_id, '__global__')) at registration — one holder per organization; bare true = deprecated positional spelling of 'global' (warned in 17.x by lint unique/unscoped-declared-index, rejected at protocol 18, #5082) — state the scope. 'tenant'/'org' are rejected — the word is 'organization' |
 | **partial** | `string` | optional | Partial index condition (SQL WHERE clause for conditional indexes) |
 
 
@@ -122,7 +122,7 @@ const result = ApiMethod.parse(data);
 | **datasource** | `string` | optional | Target Datasource ID. "default" is the primary DB. |
 | **external** | `{ remoteName?: string; remoteSchema?: string; writable?: boolean; columnMap?: Record<string, string>; … }` | optional | Remote table binding for federated (external) objects. |
 | **fields** | `Record<string, { name?: string; label?: string; type: Enum<'text' \| 'textarea' \| 'email' \| 'url' \| 'phone' \| 'password' \| 'secret' \| 'markdown' \| 'html' \| 'richtext' \| 'number' \| 'currency' \| 'percent' \| 'date' \| 'datetime' \| 'time' \| 'boolean' \| 'toggle' \| 'select' \| 'multiselect' \| 'radio' \| 'checkboxes' \| 'lookup' \| 'master_detail' \| 'tree' \| 'user' \| 'image' \| 'file' \| 'avatar' \| 'video' \| 'audio' \| 'formula' \| 'summary' \| 'autonumber' \| 'composite' \| 'repeater' \| 'record' \| 'location' \| 'address' \| 'code' \| 'json' \| 'color' \| 'rating' \| 'slider' \| 'signature' \| 'qrcode' \| 'progress' \| 'tags' \| 'vector'>; description?: string; … }>` | ✅ | Field definitions map. Keys must be snake_case identifiers. |
-| **indexes** | `{ name?: string; fields: string[]; type?: Enum<'btree' \| 'hash' \| 'gin' \| 'gist' \| 'fulltext'>; unique?: boolean \| 'global'; … }[]` | optional | Database performance indexes |
+| **indexes** | `{ name?: string; fields: string[]; type?: Enum<'btree' \| 'hash' \| 'gin' \| 'gist' \| 'fulltext'>; unique?: boolean \| 'global' \| 'organization'; … }[]` | optional | Database performance indexes |
 | **fieldGroups** | `{ key: string; label: string; icon?: string; description?: string; … }[]` | optional | Ordered list of field groups (array order = display order). See ObjectFieldGroupSchema. |
 | **tenancy** | `{ enabled: boolean; tenantField?: string }` | optional | Multi-tenancy configuration for SaaS applications |
 | **access** | `{ default?: Enum<'public' \| 'private'> }` | optional | [ADR-0066 D2] Object exposure posture (public-by-default vs private secure-by-default). |
@@ -196,7 +196,7 @@ const result = ApiMethod.parse(data);
 | **pluralLabel** | `string` | optional | Override plural label for the extended object |
 | **description** | `string` | optional | Override description for the extended object |
 | **validations** | `any[]` | optional | Additional validation rules to merge into the target object |
-| **indexes** | `{ name?: string; fields: string[]; type?: Enum<'btree' \| 'hash' \| 'gin' \| 'gist' \| 'fulltext'>; unique?: boolean \| 'global'; … }[]` | optional | Additional indexes to merge into the target object |
+| **indexes** | `{ name?: string; fields: string[]; type?: Enum<'btree' \| 'hash' \| 'gin' \| 'gist' \| 'fulltext'>; unique?: boolean \| 'global' \| 'organization'; … }[]` | optional | Additional indexes to merge into the target object |
 | **priority** | `integer` | optional | Merge priority (higher = applied later) |