fix(driver-sql, objectql): true declarations — the uncertified tenant-key finding names the ownership ceremony, the not-certified prose says what it reports, the changeset names the sys_setting re-key and the 18.0.0-born widening

Claude-Session: https://claude.ai/code/session_01NnXVu3vF2TKFLMi5Me4CUd
Co-authored-by: Claude <noreply@anthropic.com>

Author: claude

.changeset/24583-plain-organization-key-part.md

@@ -14,6 +14,6 @@ Clause-②: yes (widening)
 18.x step 7b-1 + 7b-2 (ADR-0131 D1: the tenant column is NOT NULL, so the NULL-organization bucket of ADR-0120 D3 has no rows left to hold).
 
 - **New DDL is plain.** A field-level `unique: true` / `'organization'` on a tenant-scoped object, and a declared index with `unique: 'organization'`, now build `UNIQUE (organization_id, …)` instead of `UNIQUE (COALESCE(organization_id, '__global__'), …)`. Index names do not change. The same holds for the Turso remote face, the MySQL hash shadow (its generated column now hashes the plain column), the in-memory driver's unique enforcement, `os generate migration` (which now emits the organization composite it used to list as NOT EMITTED), and the `sys_setting` row-identity index (`COALESCE(user_id, '')` stays).
-- **Existing indexes stay as they are.** Nothing is renamed, dropped or rebuilt by this release. The schema differ reads `COALESCE(<tenant>, …)` and the plain tenant column as one key part, in both directions, where the tenant column holds no NULL: the column is physically `NOT NULL`, or the database is certified (its organization-ownership birth marker, or the ownership ceremony's marker at the current shape generation). So `os migrate plan` and the boot report no `recreate_index` for those indexes. On an uncertified database with a nullable tenant column the two forms stay different constraints, as before.
-- **What widens.** Where a tenant column is still nullable (an uncertified 17.x / 18.0 database, a rotation shard, a Turso remote table), a unique index created from now on does not constrain rows whose organization is NULL, exactly like a NULL in any other key part; in the in-memory driver a record with no organization is exempt from an organization-scoped unique. The unique duplicate pre-flight no longer reports groups of rows with a NULL key part, since the index never refuses them.
-- **Who sees it.** A certified database or a fresh install sees nothing: every row carries its organization there. Nothing to do.
+- **Existing indexes stay as they are.** Nothing is renamed, and no declared organization composite is dropped or rebuilt. One index is re-keyed: the `sys_setting` row-identity index, which the metadata protocol rebuilds on every boot, keys the plain `organization_id` from the next boot on (probe-first; a pure relaxation, so it cannot fail on existing rows). The schema differ reads `COALESCE(<tenant>, …)` and the plain tenant column as one key part, in both directions, where the column is physically `NOT NULL` or the database is certified (its organization-ownership birth marker, or the ownership ceremony's marker at the current shape generation). So `os migrate plan` and the boot report no `recreate_index` for those indexes. On an uncertified database with a nullable tenant column the two forms stay different constraints: the finding is reported, and it names `os migrate organization-ownership` as its remedy.
+- **What widens.** Where a tenant column is still nullable (every table of a database 18.0.0 created, an uncertified 17.x / 18.0 database, a rotation shard, a Turso remote table, a table the ceremony reported), a unique index created from now on does not constrain rows whose organization is NULL, exactly like a NULL in any other key part; in the in-memory driver a record with no organization is exempt from an organization-scoped unique. The unique duplicate pre-flight no longer reports groups of rows with a NULL key part, since the index never refuses them.
+- **Who sees it.** A fresh install and every ceremonied table whose tenant column is NOT NULL see nothing. A database 18.0.0 created from empty is certified by its birth marker yet keeps nullable tenant columns: its existing indexes are kept unchanged, and a new organization unique declared on one of its tables constrains only rows that carry an organization.

packages/drivers/driver-sql/src/schema-drift.ts

@@ -2557,6 +2557,22 @@ export function diffManagedIndexes(args: {
     // own (`nullSafeColumns` is only ever recorded alongside an expression key
     // part); a resolved shadow key can carry NULL-safe parts with no
     // expressions at all, so the implication no longer holds.
+    // [ADR-0131 D1] An earlier release's COALESCE tenant key part against the
+    // plain one new DDL declares — the divergence is ONLY that form, on a
+    // table where the two are still different constraints (not
+    // certified, nullable tenant column). The remedy is the ownership ceremony,
+    // which certifies the database and so retires this entry — never a rebuild:
+    // `--allow-destructive` would drop and re-key the index over rows that may
+    // still lack an organization. The op is unchanged (destructive, reported,
+    // never applied unattended); only what it tells the operator differs.
+    const uncertifiedTenantKeyOnly =
+      tenantKeyCertified !== true &&
+      !!tenantField &&
+      p.unique === e.unique &&
+      (pk.nullSafeColumns ?? []).includes(tenantField) &&
+      !(e.nullSafeColumns ?? []).includes(tenantField) &&
+      canonicalIndexKey(pk.columns, (pk.nullSafeColumns ?? []).filter((c) => c !== tenantField)) ===
+        canonicalIndexKey(e.columns, (e.nullSafeColumns ?? []).filter((c) => c !== tenantField));
     const tightenNullSafeOnly =
       e.unique &&
       p.unique &&
@@ -2584,7 +2600,15 @@ export function diffManagedIndexes(args: {
         ...(e.nullSafeColumns ? { nullSafeColumns: e.nullSafeColumns } : {}),
         ...(tightenNullSafeOnly ? { tightenNullSafeOnly: true } : {}),
       },
-      message: tightenNullSafeOnly
+      message: uncertifiedTenantKeyOnly
+        ? `${table}: index '${e.name}' is ${indexSignature(pk.columns, p.unique, pk.nullSafeColumns)} and metadata declares ` +
+          `${indexSignature(e.columns, e.unique, e.nullSafeColumns)}: the same columns, differing only in how the ` +
+          `'${tenantField}' key part treats a row with no organization. This database is not certified for the ` +
+          `organization-ownership shape and '${tenantField}' is nullable, so the two are still different constraints. ` +
+          `Run "os migrate organization-ownership": once it certifies the database the two read as one index and this ` +
+          `entry is gone. Do not rebuild it with "os migrate apply --allow-destructive", which would drop and re-key ` +
+          `the index over rows that may still have no organization.`
+        : tightenNullSafeOnly
         ? `${table}: index '${e.name}' is ${indexSignature(pk.columns, p.unique, pk.nullSafeColumns)} but metadata declares ` +
           `${indexSignature(e.columns, e.unique, e.nullSafeColumns)} (ADR-0120 D3: the organization key part is NULL-safe, ` +
           `so rows without an organization are constrained too). Pure tightening — eligibility is decided by the ` +

packages/drivers/driver-sql/src/sql-driver-tenant-key-equivalence.test.ts

@@ -73,6 +73,20 @@ describe('7b-1 — the differ: COALESCE(tenant) ≡ tenant where the tenant colu
     expect(entry).toMatchObject({ category: 'destructive', op: { type: 'recreate_index', indexName: NAME } });
   });
 
+  it('the uncertified entry names the ownership ceremony as its remedy, never --allow-destructive', () => {
+    const [entry] = diff(expectedPlain, coalesced, false);
+    expect(entry!.message).toContain('"os migrate organization-ownership"');
+    expect(entry!.message).toContain('not certified');
+    // The rebuild is named only to be ruled out, never prescribed as the fix.
+    expect(entry!.message).toContain('Do not rebuild it with "os migrate apply --allow-destructive"');
+    expect(entry!.message).not.toMatch(/existing duplicates: "os migrate apply --allow-destructive"/);
+    // Control — a real redefinition keeps the rebuild remedy it always had.
+    const other: ExpectedIndex = { name: NAME, columns: [ORG, 'code', 'region'], unique: true };
+    const [rebuild] = diff(other, coalesced, false);
+    expect(rebuild!.message).not.toContain('os migrate organization-ownership');
+    expect(rebuild!.message).toContain('"os migrate apply --allow-destructive"');
+  });
+
   it('the other direction: a plain physical index against a NULL-safe expectation, no drift when certified', () => {
     expect(diff(expectedNullSafe, plain, true)).toEqual([]);
     expect(diff(expectedNullSafe, plain, false).map((d) => d.op.type)).toEqual(['recreate_index']);

packages/drivers/driver-sql/src/sql-driver.ts

@@ -20413,9 +20413,12 @@ export class SqlDriver implements IDataDriver {
    * The answer decides one thing only: whether the differ reads an earlier
    * release's `COALESCE(<tenant>, …)` key part as the plain tenant column new
    * DDL keys ({@link detectTableIndexDrift}). Without a resolver, or when it
-   * throws, the answer is "not certified" — the two forms then stay distinct
-   * constraints, which is the reading that never proposes a rebuild on a
-   * guess.
+   * throws, the answer is "not certified": the two forms then stay distinct
+   * constraints, and the differ REPORTS the 18.0 index as a destructive
+   * `recreate_index`. That report is never applied unattended — the boot
+   * reconcile applies `safe` entries only, the artifact gate refuses it, and
+   * `os migrate apply` needs `--allow-destructive` — and its message names the
+   * ownership ceremony as the remedy.
    */
   setTenantKeyCertifiedResolver(resolve: () => boolean | Promise<boolean>): void {
     this.tenantKeyCertifiedResolver = resolve;
@@ -20443,9 +20446,11 @@ export class SqlDriver implements IDataDriver {
       // {@link PRE_DDL_QUESTION_SCOPE}).
       if ((await PRE_DDL_QUESTION_SCOPE.run(true, resolver)) !== true) return false;
     } catch (e: any) {
-      // Not knowing reads as "not certified" — the reading that never proposes
-      // a rebuild on a guess — and is said once, so a drift report that then
-      // names an 18.0 index is not taken for a verdict on a certified store.
+      // Not knowing reads as "not certified": the forms stay distinct and an
+      // 18.0 index is reported as a destructive recreate_index, which nothing
+      // applies unattended (safe-only boot reconcile, the artifact gate,
+      // `--allow-destructive`). Said once, so that report is not taken for a
+      // verdict on a certified store.
       if (!this.tenantKeyCertifiedReadFailureReported) {
         this.tenantKeyCertifiedReadFailureReported = true;
         this.logger.warn(

packages/objectql/src/adr0131-tenant-key-certified-supply.test.ts

@@ -15,7 +15,8 @@
  * (`sql-driver-tenant-key-equivalence.test.ts`).
  *
  * Every way of not knowing answers `false`, the reading under which the differ
- * keeps the two forms distinct and never proposes a rebuild on a guess.
+ * keeps the two forms distinct: the differ reports a destructive
+ * `recreate_index`, which is never applied unattended.
  */
 
 import { describe, it, expect } from 'vitest';

packages/objectql/src/engine.ts

@@ -12209,8 +12209,10 @@ export class ObjectQL implements IObjectQLEngine {
     try {
       sink.setTenantKeyCertifiedResolver(() => this.isOrganizationOwnershipCertified());
     } catch (e: any) {
-      // A driver that did not take the resolver answers "not certified", the
-      // reading that never proposes a rebuild on a guess.
+      // A driver that did not take the resolver answers "not certified": it
+      // keeps the two forms distinct and REPORTS a destructive recreate_index,
+      // which is never applied unattended (safe-only boot reconcile, the
+      // artifact gate, `os migrate apply --allow-destructive`).
       this.logger.debug('Driver declined the ADR-0131 certification resolver', {
         driverName: driver.name,
         error: e?.message ?? String(e),