fix(driver-sql): honor tenancy.enabled:false in driver org-scoping (ADR-0066) (#2241)

* fix(driver-sql): honor tenancy.enabled:false in driver org-scoping (ADR-0066)

The SqlDriver auto-detects `organization_id` as a tenant-isolation column and,
when the caller passes `DriverOptions.tenantId`, injects `WHERE organization_id
= <tenantId>` on reads/updates/deletes (and the column on inserts). The
detection had two branches: a declarative one that correctly respected
`tenancy.enabled !== false`, and an implicit `organization_id`-column fallback
that did NOT — so an object explicitly opting OUT of tenancy still got
org-scoped whenever it happened to carry an `organization_id` column.

Impact (surfaced verifying ADR-0066 Phase 1): `sys_license` is platform-global
(`tenancy.enabled:false`) but keeps an optional, often-NULL `organization_id`
owner FK. A platform admin with an active org reads it through the data API
with `ctx.tenantId = <org>`, so the engine threads that into DriverOptions and
the driver silently filtered to `organization_id = <org>` — excluding the
NULL-org rows. Net: the admin saw ZERO licenses while an unscoped/anonymous
read still returned them. The filter is injected inside the driver's query
builder, not the AST, which is why it presented as an empty result with no
visible RLS `where` (astWhere=undefined).

Fix: extract a single `computeTenantField()` helper (shared by `initObjects`
and `registerExternalObject`, which had drifted) that returns `null` for any
schema with `tenancy.enabled === false`, before the implicit column heuristic.
Genuine org-scoped objects (no tenancy decl, or `enabled:true`) are unaffected.

TursoDriver extends SqlDriver and delegates initObjects to super, so the prod
control plane (Neon/Postgres and libsql) is covered by the same fix.

Adds regression tests: tenancy-disabled object registers no tenant field, reads
are unscoped regardless of `tenantId`, scoped/unscoped reads agree, and inserts
don't auto-inject `organization_id`.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* chore(changeset): driver-sql tenancy.enabled:false opt-out patch

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: 3 people

.changeset/driver-sql-tenancy-optout.md

@@ -0,0 +1,16 @@
+---
+"@objectstack/driver-sql": patch
+---
+
+fix(driver-sql): honor `tenancy.enabled:false` in driver org-scoping
+
+The driver auto-detects `organization_id` as a tenant-isolation column and, when
+the caller passes `DriverOptions.tenantId`, scopes reads/updates/deletes to that
+tenant (and injects the column on inserts). The implicit column-detection
+fallback ignored an explicit `tenancy.enabled === false`, so a platform-global
+object that opts out of tenancy but carries an optional `organization_id` FK
+(e.g. `sys_license`) was still org-scoped — an authenticated caller's active-org
+`tenantId` then hid every NULL-org / cross-org row. The opt-out is now honored in
+a single shared `computeTenantField()` used by both `initObjects` and
+`registerExternalObject` (which had drifted). Covers `TursoDriver` (extends
+`SqlDriver`). Genuine org-scoped objects are unaffected.

packages/plugins/driver-sql/src/sql-driver-tenant-scope.test.ts

@@ -219,6 +219,60 @@ describe('SqlDriver tenant scope (organization_id)', () => {
     });
   });
 
+  describe('tenancy.enabled:false opts out of driver org-scoping', () => {
+    // Regression: a platform-global object (e.g. sys_license, ADR-0066) keeps an
+    // optional, often-NULL `organization_id` FK but declares `tenancy.enabled:
+    // false`. The driver previously detected the `organization_id` column via the
+    // implicit fallback and org-scoped it anyway, so an authenticated caller's
+    // active-org `tenantId` injected `WHERE organization_id = <org>` and the
+    // NULL-org rows vanished — the platform admin read zero rows while an
+    // unscoped read still saw them. tenancy.enabled:false must win.
+    const platformGlobal = [
+      {
+        name: 'sys_license',
+        tenancy: { enabled: false, strategy: 'shared' },
+        fields: {
+          customer: { type: 'string' },
+          organization_id: { type: 'string' }, // optional owner FK, may be NULL
+          status: { type: 'string' },
+        },
+      },
+    ];
+
+    beforeEach(async () => {
+      await driver.disconnect();
+      driver = new SqlDriver({
+        client: 'better-sqlite3',
+        connection: { filename: ':memory:' },
+        useNullAsDefault: true,
+      });
+      await driver.initObjects(platformGlobal);
+      // A NULL-org platform row + an org-mapped one.
+      await driver.create('sys_license', { id: 'lic_global', customer: 'ACME', organization_id: null, status: 'active' });
+      await driver.create('sys_license', { id: 'lic_org_b', customer: 'Beta', organization_id: 'org_b', status: 'active' });
+    });
+
+    it('does NOT register a tenant field for a tenancy-disabled object', () => {
+      expect((driver as any).tenantFieldByTable['sys_license']).toBeNull();
+    });
+
+    it('read is unscoped even when the caller passes tenantId (admin with active org sees all)', async () => {
+      const adminRead = await driver.find('sys_license', { object: 'sys_license' }, { tenantId: 'org_admin_active' });
+      expect(adminRead.map(r => r.id).sort()).toEqual(['lic_global', 'lic_org_b']);
+    });
+
+    it('matches the unscoped (anonymous) read — no auth-dependent divergence', async () => {
+      const scoped = await driver.find('sys_license', { object: 'sys_license' }, { tenantId: 'org_admin_active' });
+      const unscoped = await driver.find('sys_license', { object: 'sys_license' });
+      expect(scoped.map(r => r.id).sort()).toEqual(unscoped.map(r => r.id).sort());
+    });
+
+    it('does NOT auto-inject organization_id on insert when tenancy is disabled', async () => {
+      const created = await driver.create('sys_license', { id: 'lic_new', customer: 'Gamma', status: 'active' }, { tenantId: 'org_admin_active' });
+      expect(created.organization_id ?? null).toBeNull();
+    });
+  });
+
   describe('audit warn on missing tenantId', () => {
     it('logs once per object:op when writing without tenantId', async () => {
       await driver.disconnect();

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

@@ -1306,6 +1306,39 @@ export class SqlDriver implements IDataDriver {
     await this.knex.schema.dropTableIfExists(object);
   }
 
+  /**
+   * Resolve the per-table tenant-isolation column for a schema, honoring an
+   * explicit tenancy opt-out. Single source of truth for both {@link initObjects}
+   * and {@link registerExternalObject} (they previously inlined this logic and
+   * drifted).
+   *
+   * Precedence:
+   *  1. `tenancy.enabled === false` → `null` (NO driver-level org scope), even
+   *     when the object carries an `organization_id` column. Platform-global
+   *     objects (e.g. `sys_license`) keep an optional, often-NULL org FK but must
+   *     NOT be tenant-scoped: otherwise an authenticated caller's active-org
+   *     `DriverOptions.tenantId` injects `WHERE organization_id = <org>` and every
+   *     NULL-org / cross-org row silently disappears (the platform admin then
+   *     reads zero licenses while an unscoped/anonymous read still sees them).
+   *     The declarative branch below already respected `enabled !== false`; the
+   *     implicit `organization_id` fallback did not — this closes that gap.
+   *  2. Declared `tenancy.tenantField` (when that field exists on the object).
+   *  3. Implicit `organization_id` column detection (legacy objects whose
+   *     multi-tenant column was injected by the kernel without a spec migration).
+   */
+  protected computeTenantField(schema: { fields?: Record<string, any>; tenancy?: any }): string | null {
+    const tenancyDecl = (schema as any)?.tenancy;
+    // Explicit opt-out wins over any column-presence heuristic.
+    if (tenancyDecl?.enabled === false) return null;
+    const fields = schema?.fields;
+    if (tenancyDecl?.tenantField) {
+      const declared = String(tenancyDecl.tenantField);
+      if (fields && Object.prototype.hasOwnProperty.call(fields, declared)) return declared;
+    }
+    if (fields && Object.prototype.hasOwnProperty.call(fields, 'organization_id')) return 'organization_id';
+    return null;
+  }
+
   /**
    * Batch-initialise tables from an array of object definitions.
    */
@@ -1368,18 +1401,7 @@ export class SqlDriver implements IDataDriver {
     const datetimeCols: string[] = [];
     const autoNumberCols: Array<{ name: string; format: string; tokens: AutonumberToken[]; tenantField: string | null }> = [];
 
-    const tenancyDecl = (schema as any)?.tenancy;
-    let tenantField: string | null = null;
-    if (tenancyDecl && tenancyDecl.enabled !== false && tenancyDecl.tenantField) {
-      const declared = String(tenancyDecl.tenantField);
-      if (schema.fields && Object.prototype.hasOwnProperty.call(schema.fields, declared)) {
-        tenantField = declared;
-      }
-    }
-    if (!tenantField) {
-      const hasOrgField = !!(schema.fields && Object.prototype.hasOwnProperty.call(schema.fields, 'organization_id'));
-      tenantField = hasOrgField ? 'organization_id' : null;
-    }
+    const tenantField = this.computeTenantField(schema);
     if (schema.fields) {
       for (const [name, field] of Object.entries<any>(schema.fields)) {
         const type = field.type || 'string';
@@ -1425,25 +1447,10 @@ export class SqlDriver implements IDataDriver {
       const booleanCols: string[] = [];
       const numericCols: string[] = [];
       const autoNumberCols: Array<{ name: string; format: string; tokens: AutonumberToken[]; tenantField: string | null }> = [];
-      // Auto-detect tenant field. Convention: the field named
-      // `organization_id` (matching tenantPolicy default) scopes the
-      // Resolve tenant scope declaratively first (obj.tenancy.{enabled,
-      // tenantField}) — that's the user's explicit intent. Fall back to the
-      // implicit "has an organization_id field" detection so legacy objects
-      // (whose multi-tenant column was injected by the kernel implicitly)
-      // keep working without a spec migration.
-      const tenancyDecl = (obj as any)?.tenancy;
-      let tenantField: string | null = null;
-      if (tenancyDecl && tenancyDecl.enabled !== false && tenancyDecl.tenantField) {
-        const declared = String(tenancyDecl.tenantField);
-        if (obj.fields && Object.prototype.hasOwnProperty.call(obj.fields, declared)) {
-          tenantField = declared;
-        }
-      }
-      if (!tenantField) {
-        const hasOrgField = !!(obj.fields && Object.prototype.hasOwnProperty.call(obj.fields, 'organization_id'));
-        tenantField = hasOrgField ? 'organization_id' : null;
-      }
+      // Tenant-isolation column: explicit tenancy opt-out → declared field →
+      // implicit `organization_id`. See {@link computeTenantField} (shared with
+      // registerExternalObject so the two paths can't drift).
+      const tenantField = this.computeTenantField(obj);
       if (obj.fields) {
         for (const [name, field] of Object.entries<any>(obj.fields)) {
           const type = field.type || 'string';