docs(driver-sql): isOrganizationScopedUnique judges the FIELD-level unique only

[os-zhuang]

Fixes#8463

Comment-only correction. No behaviour change — normalizeDeclaredIndex, the helper body, and every call site are untouched.

The defect

The exported helper's JSDoc claimed it judged organization scope "on either spelling (field-level unique or a declared index's unique)". It does not, and never did.

Claim	Reality on origin/main @ e474853
Helper body	schema-drift.ts:82-84 — return unique === true || unique === 'organization';
Call site 1	:933 — isOrganizationScopedUnique(field.unique)
Call site 2	:1102 — if (!isOrganizationScopedUnique(field.unique)) continue;
Declared-index path	:987 — } else if (idx?.unique === 'organization' && tenantField) { — a strict equality, not the helper

Both call sites are field-level. A declared index's bare unique: true is therefore taken verbatim as global.

Why the code is right and the comment was wrong

The divergence is deliberate — the #4986 answer, ADR-0120 D1 — and it is already pinned and documented elsewhere (both verified, not assumed):

• packages/lint/src/data-model-rules.ts:101 ships unique/unscoped-declared-index, and its indexUniqueScope at :137-141 states the declared-index contract.
• packages/spec/src/data/object.zod.ts:401 — IndexSchema.unique's describe() says bare true is the deprecated positional spelling of 'global'.
• sql-driver-declared-index-organization-respelling.test.ts:161 pins that a declared bare true takes the listed columns verbatim, with no tenant column.

The hazard was that the comment invited the obvious tidy-up — routing the declared-index branch through the helper so code and comment agree. That edit is option 1 of #8323, ruled out by the maintainer on 2026-08-13, and it pre-empts the bare-spelling question parked on #5082. It would silently reinterpret every existing declared unique: true on deployed databases as organization-scoped: an unannounced index migration, landing a release before#5082 refuses the bare spelling.

Neither #8323 nor #5082 is addressed here; both remain open.

What the new JSDoc does

States the field-level scope plainly; names the declared-index path's strict-equality requirement and the verbatim-global reading of bare true; {@link normalizeDeclaredIndex}; points at #5082 for the parked question; and records the rejected-unification reasoning so the next reader learns why the disagreement is correct rather than re-deriving the hazard.

Changeset: patch

Judged on this package's own evidence rather than by copying the driver-sql precedent in #8283 / PR #8488 (a protected member). Stronger case here: isOrganizationScopedUnique is a top-level export at src/index.ts:86, the package is published (no private), types is dist/index.d.ts, declaration: true is set in both the package and base tsconfig, and no removeComments exists anywhere. Verified empirically by building — the corrected text appears verbatim at dist/index.d.ts:39-65.

Verification

pnpm --filter '@objectstack/driver-sql' test — 90 files / 1457 tests passed, 4 files / 52 skipped. typecheck clean. Gates green: check:nul-bytes, check:driver-conformance, check:test-source-alias, check:type-source-resolution, check:empty-changeset (re-run post-commit: 1 declaring changeset(s) added), check:changeset-gate-self-tests, check:objectui-changeset, check-adr-0087-registration, check-changeset-no-major. check:objectui-pin-fresh and check-dev-prereqs are known-ambient.

Reverse verification does not apply to a comment-only change — there is no behaviour to invert. Each claim the new text makes was instead checked against the code it describes, at the file:line above.

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 13, 2026 4:37pm

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/driver-sql.

8 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/data-modeling/drivers.mdx(via @objectstack/driver-sql)
• content/docs/getting-started/glossary.mdx(via @objectstack/driver-sql)
• content/docs/kernel/services-checklist.mdx(via @objectstack/driver-sql)
• content/docs/plugins/anatomy.mdx(via @objectstack/driver-sql)
• content/docs/plugins/packages.mdx(via @objectstack/driver-sql)
• content/docs/protocol/kernel/index.mdx(via @objectstack/driver-sql)
• content/docs/protocol/kernel/lifecycle.mdx(via @objectstack/driver-sql)
• content/docs/protocol/objectql/query-syntax.mdx(via @objectstack/driver-sql)

⛔ 1 release-owned page(s) also reference the affected code. These are read-only:

• content/docs/releases/implementation-status.mdx(via @objectstack/driver-sql)

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.

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.