fix(driver-memory): enforce object-level declared indexes[] uniqueness (#13239) (#13341)

`driver-sql` materializes uniqueness from two declaration surfaces. #13197
closed the field-level one here; object-level declared `indexes[]` entries
carrying `unique` were still declared-and-not-enforced, so a composite unique
was a real constraint on the SQL family and nothing at all in memory — the
colliding write landed and a read returned both rows.

- `normalizeDeclaredIndex`'s arms are reproduced (not imported — this package
  must not depend on `driver-sql`), including the #4986 trap: on a DECLARED
  index bare `unique: true` is the positional spelling of `'global'`, the
  opposite of the field surface, so the scope test is the strict
  `unique === 'organization'`.
- Both surfaces share one key model, so there is exactly one NULL rule: a NULL
  in any listed key column exempts the row, while a NULL organization folds onto
  one bucket. Measured against SQLite over both DDL shapes
  `syncDeclaredIndexes` emits, not assumed.
- The refusal is the same ADR-0112 envelope, stamped in one place for both
  surfaces. It names the key COLUMNS and no index name, so
  `uniqueViolationColumn` answers `undefined` — what `driver-sql` answers for a
  composite, and the safe answer under #6544.
- The `memory-unique-constraint.ts` docblock sentence that listed this surface
  under "Deliberately out of scope" is removed, not left standing.


Claude-Session: https://claude.ai/code/session_01LZbWd2jNV1FErXTPSS4Dry

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

Author: claude[bot]

.changeset/driver-memory-declared-index-uniqueness.md

@@ -0,0 +1,70 @@
+---
+"@objectstack/driver-memory": minor
+---
+
+fix(driver-memory): enforce object-level declared `indexes[]` uniqueness, so a colliding composite write is refused instead of landing silently (#13239)
+
+`driver-sql` materializes uniqueness from **two** declaration surfaces —
+field-level `unique` (`uniqueIndexesFromFields`) and object-level `indexes[]`
+entries carrying `unique` (`normalizeDeclaredIndex`). #13197 closed the first
+one here. The second was still **declared and not enforced**: an object
+declaring
+
+```json
+{ "indexes": [{ "fields": ["account_id", "code"], "unique": "organization" }] }
+```
+
+got a real composite UNIQUE on the SQL family and **nothing at all** in memory —
+the colliding write landed and a read returned both rows. That is the same
+ADR-0078 / Prime-Directive-#10 shape, one surface over.
+
+**⚠️ Bare `true` means the OPPOSITE on the two surfaces, and this reproduces the
+disagreement rather than smoothing it.** At field level `unique: true` is the
+positional spelling of `'organization'`; on a declared index it is the
+positional spelling of `'global'` — the listed columns VERBATIM, no organization
+key part. That is the #4986 trap, it is deliberate (the #8323 maintainer ruling
+of 2026-08-13 rejected routing the declared-index branch through the field-level
+predicate, because it would silently reinterpret every deployed declared
+`unique: true` as organization-scoped), and it is staged for retirement at
+protocol 18 by #5082. So the scope test on this surface is the strict
+`unique === 'organization'`, exactly as `normalizeDeclaredIndex` does it, and
+`memory-declared-index-unique.test.ts` holds both readings side by side on one
+object so a future edit cannot move one without moving the other.
+
+`normalizeDeclaredIndex`'s arms are reproduced — not imported: `driver-memory`
+must not depend on `driver-sql`, the same reason `computeTenantField` was
+reproduced for #13197.
+
+- `unique: true` / `'global'` → the listed columns verbatim.
+- `unique: 'organization'` with a tenant column → the organization key part is
+  prepended (and is NOT prepended twice when the author already listed it — its
+  own key part goes NULL-safe instead, order preserved).
+- `unique: 'organization'` with no tenant column → degrades to the listed
+  columns alone.
+- `unique` absent / `false`, or an entry with no usable `fields` → not a
+  constraint.
+
+**NULL handling was measured against SQLite, not assumed.** A NULL in any listed
+key column exempts the row (SQL `UNIQUE` is NULL-distinct), while a NULL
+ORGANIZATION folds onto one bucket, because ADR-0120 D3 materializes that key
+part as `COALESCE(organization_id, '__global__')` — an expression that is never
+NULL. Both halves hold here through one key model shared with the field surface,
+so there is exactly one NULL rule in the package.
+
+**The refusal** is the field surface's envelope — `code: 'UNIQUE_VIOLATION'`,
+`status: 409`, no `[driver-memory]` prefix — stamped in one place for both
+surfaces. It names the key COLUMNS and carries no index name, so
+`uniqueViolationColumn` answers `undefined`: the same answer `driver-sql` gives
+for a composite, and the safe one under the #6544 ruling that an identifier
+mistaken for a column is worse than no answer.
+
+**Why `minor` rather than `patch`:** this refuses writes that previously
+succeeded, and the blast radius was measured rather than assumed. 57 in-repo
+production/metadata declaration sites carry a `unique` `indexes[]` entry —
+`sys_user`, `sys_session`, `sys_setting`, `sys_metadata`, `sys_member`,
+`sys_team_member` and most of the identity surface among them — so any stack
+served by `InMemoryDriver` newly enforces constraints the SQL family already
+enforced. Every one of those refusals is a write SQL would have refused too, and
+existing rows are never retroactively refused (a declaration arriving over
+`initialData` is recorded, not applied backwards), but a dev or demo stack that
+relied on the store accepting a duplicate will now see a 409.

packages/drivers/driver-memory/src/index.ts

@@ -22,19 +22,30 @@ export {
 } from './memory-tenancy-guard.js';
 export type { TenancyAwareSchema } from './memory-tenancy-guard.js';
 
-// [#13197] Field-level uniqueness — the refusal's wire identity and the
-// scoping helpers, exported so a consumer can assert the envelope (`code` AND
-// `status`, never merely "it threw") without string-matching the message.
+// [#13197, #13239] Uniqueness on BOTH declaration surfaces — field-level
+// `unique` and object-level declared `indexes[]` — with the refusal's wire
+// identity and the scoping helpers, exported so a consumer can assert the
+// envelope (`code` AND `status`, never merely "it threw") without
+// string-matching the message.
 export {
   UNIQUE_VIOLATION_CODE,
   UNIQUE_VIOLATION_STATUS,
   assertNoUniqueViolation,
+  declaredIndexViolationError,
+  isDeclaredIndexConstraint,
   tenantFieldOf,
+  uniqueConstraintsFromDeclaredIndexes,
   uniqueConstraintsFromFields,
   uniqueKeyOf,
   uniqueViolationError,
 } from './memory-unique-constraint.js';
-export type { MemoryUniqueConstraint, UniqueAwareSchema } from './memory-unique-constraint.js';
+export type {
+  DeclaredIndexInput,
+  MemoryDeclaredIndexConstraint,
+  MemoryUniqueConstraint,
+  MemoryUniqueEnforcement,
+  UniqueAwareSchema,
+} from './memory-unique-constraint.js';
 
 export default {
   id: 'com.objectstack.driver.memory',