fix(metadata-protocol): enforce sys_setting's declared row identity on the tenant and global layers (#8629)

[hotlong]

Fixes#8629

sys-setting.object.ts declares the object's row identity as { fields: ['namespace', 'key', 'scope', 'user_id'], unique: 'organization' }. It was not one: user_id is NULL on every row that is not scope='user' (SettingsService.set computes it as scope === 'user' ? ctx.userId ?? null : null), and SQL UNIQUE treats NULLs as mutually distinct — so the constraint was void on the tenant and global limbs, exactly the two carrying organization-level and platform-level configuration.

Implements the maintainer's ruling of 2026-08-14 (comment 5293093894): Route 1 now — a runtime NULL-safe unique index issued at kernel:ready, the PR #6666 paradigm. Route 2 (declaring NULL-safe uniqueness in the spec vocabulary) is deferred to v18 and packages/spec is untouched. Migration semantics: refuse-to-migrate and list the duplicate rows for the operator, never keep-newest.

The premise, re-verified on origin/main

Measured before writing anything, with the real SqlDriver over the real shipped declaration on SQLite. The declared index materializes as

CREATE UNIQUE INDEX uniq_sys_setting_organization_id_namespace_key_scope_user_id
ON sys_setting (COALESCE(organization_id, '__global__'), namespace, key, scope, user_id)

and over it: two identical scope='tenant' rows in ONE organization both land; two identical scope='global' platform defaults both land; the same rows with a non-NULL user_id are refused. The premise holds, and the control identifies the mechanism as the NULL rather than the scope value.

What lands

packages/metadata-protocol/src/migrations/sys-setting-identity-index.ts — the third instance of this package's runtime-index paradigm, deliberately borrowing overlay-index.ts and view-definition-active-index.ts rather than inventing a variant:

• the key folds both nullable parts — COALESCE(organization_id, '__global__') (ADR-0120 D3's tenant form, byte-identical to what the driver already emits) and COALESCE(user_id, '') (the ensureOverlayIndex spelling for a non-tenant nullable discriminator). Neither sentinel is invented here; storage is untouched, only the index folds.
• the name is the DECLARED one, so syncDeclaredIndexes — which skips by name — never re-imposes the NULL-distinct form. Measured: a later boot's additive sync leaves the tightened definition byte for byte, and detectManagedDrift() returns [] both immediately after the migration and after that later boot (an index carrying a non-tenant expression key part is not isSyncReproducibleIndex, so isRuntimeManagedIndex claims it — the same protection idx_sys_metadata_overlay_active has).
• the probe name is short and independent (idx_sys_setting_identity_probe), rather than the declared name plus a _probe suffix: the declared name is already on the 60-character INDEX_NAME_MAX boundary, so the suffixed spelling would be 66 — over PostgreSQL's 63-byte truncation and MySQL's 64-character error.
• refuse-to-migrate is delivered by the existing probe-first order: the tightening is proved buildable under the throwaway name before the declared name is ever dropped, so a conflict leaves the previous index in place, deletes nothing, and reports at error with the exact query that lists the offending rows plus a pointer to os migrate plan. Asserted as behaviour: on a duplicate-carrying database both rows survive with their ids, the previous index DDL is unchanged and still enforcing, and the migration converges only once an operator removes a row themselves.
• a table-presence probe first.sys_setting is registered by the optional service-settings, so a kernel can legitimately reach kernel:ready without it. Absence is a silent no-op, not a degradation line — one unactionable error per boot is how the actionable ones stop being read.

resolveIndexExec's body moved into partial-index-probe.ts as resolveIndexExecForTable(engine, table) — sys_setting was about to be its third hard-coded copy, and a resolver that asks about the wrong table is the bug getDriverForObject exists to prevent. view-definition-active-index.ts keeps its exported name and delegates.

Armed from the same seam and behind the same environmentId === undefined gate as its sibling, in its own try/catch so one migration that could not be armed does not skip the other.

The pin file

sql-driver-sys-setting-organization-unique.test.ts section 4 was written to go RED when this card lands. It is flipped, not relaxed: the BEFORE cases still measure the hole on both spellings of the declaration (the #8555 respelling genuinely does not fix it, and the suite must keep saying so), and new AFTER cases apply the migration's DDL through the driver's own raw seam and pin that the same-organization tenant duplicate and the second platform default both flip from 201 to 409, that the key stays per-organization (anti-vacuity), that the user layer is unchanged, that the index survives a later boot's sync, that the reconciler reports no drift, and that a duplicate-carrying database refuses the build without losing a row. The DDL literal is hand-copied because driver-sql must not depend on metadata-protocol — the same one-directional guard the declaration mirror in that file already uses, and it is stated in the file.

Verification

Run at 9643bbc, the head of this branch.

• pnpm --filter @objectstack/metadata-protocol test — 90 files, 1346 tests, all passing (29 new).
• pnpm --filter @objectstack/driver-sql test — 96 files, 1643 passing / 54 skipped (the flipped pin file: 31 passing).
• pnpm --filter @objectstack/driver-sql typecheck — clean. (metadata-protocol declares no typecheck script; pnpm --filter @objectstack/metadata-protocol build emits its .d.ts cleanly.)
• Reverse verification, direction predicted before running: remove user_id from the sentinel map and the suite must go RED. It does — 10 of 29 cases fail, including the real-SQLite duplicate-refusal cases and the whole conflict-path group, so the assertions are not vacuous. Restored from the commit and proved byte-identical with git hash-object (7b941be8…).
• Gates, all green: check:cross-package-test-inputs (+ the ci.yml script form), check:durability-log-level, check:test-source-alias, check:type-source-resolution, check:query-options-erasure, check:type-check-coverage, check:type-check-debt (after turbo run build over the full package closure — 70/70 successful), check:nul-bytes, and the changeset family the union added on top of the dispatch list: check:changeset-gate-self-tests, check:objectui-changeset, check:empty-changeset, check:adr-0087-registration, check-changeset-no-major.mjs.

Scope

The os migrate plan pre-flight lives in packages/cli, another lane. It is not touched: the operator-facing duplicate list is delivered inside the boot's conflict report, exactly as both precedent migrations deliver theirs, so no cross-lane edit was needed. sql-driver.ts and sql-driver-upsert-conflict-target-dialects.test.ts are untouched (#8622 owns those). packages/spec is untouched (route 2 is v18).

---

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 14, 2026 4:13pm

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/metadata-protocol.

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

• content/docs/concepts/metadata-lifecycle.mdx(via @objectstack/metadata-protocol)
• content/docs/kernel/services-checklist.mdx(via @objectstack/metadata-protocol)
• content/docs/protocol/kernel/http-protocol.mdx(via @objectstack/metadata-protocol)

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

• content/docs/releases/v9.mdx(via @objectstack/metadata-protocol)

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.