feat(driver-sql,driver-turso)!: 18.x step 7 part 7b-0 — a table the driver creates carries its tenant column NOT NULL

.changeset/24583-tenant-column-not-null-ddl.md

@@ -0,0 +1,21 @@
+---
+'@objectstack/driver-sql': patch
+'@objectstack/driver-turso': patch
+'@objectstack/spec': patch
+---
+
+feat(driver-sql,driver-turso)!: a table the driver creates carries its tenant column NOT NULL, so a write that names no organization is refused at the database
+
+Clause-②: yes (narrowing)
+Metadata-protocol: none
+
+<!-- adr-0087: not-required (no-migration-prescription) A storage constraint at CREATE TABLE: no key of any metadata schema is removed, renamed or re-shaped, so there is nothing for `objectstack migrate meta` to rewrite and no tombstone. No export, type or error code is removed or renamed; `TENANT_SCOPE_FIELD_DEF` keeps its shape and only its description text is corrected. The remedy is a run-time one, stated below. -->
+
+**BREAKING** accept-set narrowing at the database (ADR-0131 D1: "There is no nullable tenant column anywhere"). It changes what a data writer can store, not what a metadata author can write, so it ships as `patch` with this banner.
+
+- **Before.** The SQL driver created a table's tenant column (`organization_id`, or a declared `tenancy.tenantField`) nullable, as the injected field's declaration says (`required: false`, no `storage`). A write that reached the driver without an organization landed a row no organization owns.
+- **Now.** Every table the driver CREATES takes its tenant column `NOT NULL`, with no metadata change: the plain managed table (`initObjects`), every newly rotated shard (asked of the base table's declaration), and a table the Turso remote face creates (`syncSchema`, `syncSchemasBatch`, `initObjects`). A write with no organization on such a table is refused by the database (`NOT NULL constraint failed: <table>.organization_id`, `violates not-null constraint`, or `cannot be null`). That includes an `upsert` whose payload omits the organization: the database checks the proposed row before it resolves the conflict.
+- **Unchanged.** A tenant column ADDED to a table that already exists stays nullable, and so does an existing shard or an existing remote table: a table that already holds rows is the organization-ownership ceremony's to tighten (`os migrate organization-ownership`), which reports a shard and the Turso remote face as unable to. The schema differ reports no drift over the tenant column's nullability either way. On a database that has not taken the ceremony, a table this release creates (a newly rotated shard, or a cold table a newly configured lifecycle tier creates) is NOT NULL beside nullable siblings: an organization-less row the lifecycle mover would carry into it is refused there, and stays where it is until the ceremony attributes it. An object with no tenant column (`tenancy: { enabled: false }`, `systemFields: { tenant: false }`) is untouched, even when it carries a field named `organization_id`.
+- **Who sees it.** A composed `os serve` / `os dev` / `os start` with auth stamps every write with its organization, so nothing changes there. A production `os serve` whose `AuthPlugin` did not compose (no `OS_AUTH_SECRET`) and a lean embedding (`@objectstack/objectql/core` or `createStandaloneStack` over a SQL driver, with no organization object) used to write those rows with a NULL organization; now each such write fails, loudly.
+
+**The remedy.** Carry the organization on the write: `ql.insert(object, { ...row, organization_id: orgId })`, or `{ context: { tenantId: orgId } }`. Compose authentication (set `OS_AUTH_SECRET`) so the platform derives it. If the object's rows legitimately belong to no organization, declare it so and it has no tenant column: `systemFields: { tenant: false }` or `tenancy: { enabled: false }`.

examples/app-crm/test/default-organization.testkit.ts

@@ -0,0 +1,45 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * Give a lean test engine what every real `single` install has: an
+ * organization object holding its Default Organization.
+ *
+ * ADR-0131 D1: a table the SQL driver creates carries its tenant column NOT
+ * NULL. The engine stamps an organization-less system write with the derived
+ * organization under `single` (D9) — but only where the composition registers
+ * the organization object; a bare `ObjectQL` + `SqlDriver` registers none, so
+ * the write reaches the database with no organization and is refused there.
+ * A suite whose subject is not tenancy (claims, acks, idle cost, at-rest
+ * shapes) calls this once its own objects are registered, so its system
+ * writes land the way they do on a real install.
+ *
+ * The object mirrors the platform's: managed by better-auth, so it carries no
+ * tenant column of its own.
+ */
+export const DEFAULT_ORGANIZATION_ID = 'org_default';
+
+export async function installDefaultOrganization(engine: {
+  registry: { registerObject(def: unknown, owner: string): unknown };
+  getSchema(object: string): unknown;
+  syncSchemas(): Promise<unknown>;
+  getDriverForObject(object: string):
+    | {
+        create(object: string, data: Record<string, unknown>): Promise<unknown>;
+        findOne(object: string, query: unknown): Promise<unknown>;
+      }
+    | undefined;
+}): Promise<void> {
+  // Idempotent: a suite that syncs one engine more than once may call it each time.
+  if (!engine.getSchema('sys_organization')) {
+    engine.registry.registerObject(
+      { name: 'sys_organization', label: 'Organization', managedBy: 'better-auth', fields: { name: { type: 'text', label: 'Name' } } },
+      '@objectstack/example-crm',
+    );
+  }
+  await engine.syncSchemas();
+  // Seeded through the driver: the organization is data at rest, not a write
+  // the suite under test should observe (an audit or activity mirror would).
+  const driver = engine.getDriverForObject('sys_organization')!;
+  if (await driver.findOne('sys_organization', { where: { id: DEFAULT_ORGANIZATION_ID } })) return;
+  await driver.create('sys_organization', { id: DEFAULT_ORGANIZATION_ID, name: 'Default' });
+}

examples/app-crm/test/opportunity-stage-hook.test.ts

@@ -56,6 +56,7 @@ import { SqlDriver } from '@objectstack/driver-sql';
 import { Account, Opportunity, OpportunityLineItem } from '../src/objects/index.js';
 import { allHooks } from '../src/hooks/index.js';
 import { OpportunityStageHook } from '../src/hooks/opportunity.hook.js';
+import { installDefaultOrganization } from './default-organization.testkit.js';
 
 /** The app id `AppPlugin` derives its `packageId` from. */
 const PACKAGE_ID = 'app:com.example.crm';
@@ -96,6 +97,9 @@ async function bootCrm(hooks: unknown[] = allHooks): Promise<ObjectQL> {
     engine.registry.registerObject(def as never, PACKAGE_ID, 'crm');
   }
   await engine.syncSchemas();
+  // A real `single` install's Default Organization: the system writes below
+  // derive it (ADR-0131 D9), as a fresh NOT NULL tenant column requires (D1).
+  await installDefaultOrganization(engine);
 
   // Exactly the AppPlugin call, minus the sandbox body runner this app has no
   // use for (its single hook is an inline code handler).

examples/app-showcase/test/approval-resume-relation-expand.test.ts

@@ -58,6 +58,7 @@ import {
   TaskDoneNotifyOwnerFlow,
   NotifyOwnerSubflow,
 } from '../src/automation/flows/index.js';
+import { installDefaultOrganization } from './default-organization.testkit.js';
 
 /** Everything the approvals service treats as an unconditional actor. */
 const SYSTEM_CTX = { isSystem: true, positions: [], permissions: [] } as any;
@@ -128,6 +129,9 @@ async function bootShowcaseApprovals(
     objectql.registry.registerObject(obj, 'showcase', 'showcase');
   }
   await objectql.syncSchemas();
+  // A real `single` install's Default Organization: the system writes below
+  // derive it (ADR-0131 D9), as a fresh NOT NULL tenant column requires (D1).
+  await installDefaultOrganization(objectql);
 
   for (const flow of flows) automation.registerFlow(flow.name, flow);
 

examples/app-showcase/test/default-organization.testkit.ts

@@ -0,0 +1,45 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * Give a lean test engine what every real `single` install has: an
+ * organization object holding its Default Organization.
+ *
+ * ADR-0131 D1: a table the SQL driver creates carries its tenant column NOT
+ * NULL. The engine stamps an organization-less system write with the derived
+ * organization under `single` (D9) — but only where the composition registers
+ * the organization object; a bare `ObjectQL` + `SqlDriver` registers none, so
+ * the write reaches the database with no organization and is refused there.
+ * A suite whose subject is not tenancy (claims, acks, idle cost, at-rest
+ * shapes) calls this once its own objects are registered, so its system
+ * writes land the way they do on a real install.
+ *
+ * The object mirrors the platform's: managed by better-auth, so it carries no
+ * tenant column of its own.
+ */
+export const DEFAULT_ORGANIZATION_ID = 'org_default';
+
+export async function installDefaultOrganization(engine: {
+  registry: { registerObject(def: unknown, owner: string): unknown };
+  getSchema(object: string): unknown;
+  syncSchemas(): Promise<unknown>;
+  getDriverForObject(object: string):
+    | {
+        create(object: string, data: Record<string, unknown>): Promise<unknown>;
+        findOne(object: string, query: unknown): Promise<unknown>;
+      }
+    | undefined;
+}): Promise<void> {
+  // Idempotent: a suite that syncs one engine more than once may call it each time.
+  if (!engine.getSchema('sys_organization')) {
+    engine.registry.registerObject(
+      { name: 'sys_organization', label: 'Organization', managedBy: 'better-auth', fields: { name: { type: 'text', label: 'Name' } } },
+      '@objectstack/example-showcase',
+    );
+  }
+  await engine.syncSchemas();
+  // Seeded through the driver: the organization is data at rest, not a write
+  // the suite under test should observe (an audit or activity mirror would).
+  const driver = engine.getDriverForObject('sys_organization')!;
+  if (await driver.findOne('sys_organization', { where: { id: DEFAULT_ORGANIZATION_ID } })) return;
+  await driver.create('sys_organization', { id: DEFAULT_ORGANIZATION_ID, name: 'Default' });
+}

examples/app-showcase/test/hook-body-persisted-writes.test.ts

@@ -49,6 +49,7 @@ import { QuickJSScriptRunner, hookBodyRunnerFactory } from '@objectstack/runtime
 
 import { Account, Project, Task, Inquiry } from '../src/data/objects/index.js';
 import { allHooks } from '../src/data/hooks/index.js';
+import { installDefaultOrganization } from './default-organization.testkit.js';
 
 /** The app id `AppPlugin` derives its `packageId` from. */
 const APP_ID = 'com.objectstack.showcase';
@@ -87,6 +88,9 @@ async function bootShowcase(hooks: unknown[] = allHooks): Promise<ObjectQL> {
     engine.registry.registerObject(def as never, PACKAGE_ID, 'showcase');
   }
   await engine.syncSchemas();
+  // A real `single` install's Default Organization: the system writes below
+  // derive it (ADR-0131 D9), as a fresh NOT NULL tenant column requires (D1).
+  await installDefaultOrganization(engine);
 
   engine.bindHooks(hooks as never[], {
     packageId: PACKAGE_ID,

examples/app-showcase/test/new-project-wizard-initial-status.test.ts

@@ -37,6 +37,7 @@ import { SqlDriver } from '@objectstack/driver-sql';
 import stack from '../objectstack.config.js';
 import { Account, Project } from '../src/data/objects/index.js';
 import { NewProjectWizardPage } from '../src/ui/pages/new-project-wizard.page.js';
+import { installDefaultOrganization } from './default-organization.testkit.js';
 
 type Rule = {
   type?: string;
@@ -82,6 +83,9 @@ async function bootShowcase(): Promise<ObjectQL> {
     engine.registry.registerObject(def as never, PACKAGE_ID, 'showcase');
   }
   await engine.syncSchemas();
+  // A real `single` install's Default Organization: the system writes below
+  // derive it (ADR-0131 D9), as a fresh NOT NULL tenant column requires (D1).
+  await installDefaultOrganization(engine);
   return engine;
 }
 

examples/app-showcase/test/paid-invoice-line-lock.test.ts

@@ -34,6 +34,7 @@ import {
   PAID_INVOICE_LINE_REMOVE_REFUSAL,
   PAID_INVOICE_LINE_MOVE_REFUSAL,
 } from '../src/data/hooks/index.js';
+import { installDefaultOrganization } from './default-organization.testkit.js';
 
 const APP_ID = 'com.objectstack.showcase';
 const PACKAGE_ID = `app:${APP_ID}`;
@@ -61,6 +62,9 @@ async function bootShowcase(hooks: unknown[] = allHooks): Promise<ObjectQL> {
     engine.registry.registerObject(def as never, PACKAGE_ID, 'showcase');
   }
   await engine.syncSchemas();
+  // A real `single` install's Default Organization: the system writes below
+  // derive it (ADR-0131 D9), as a fresh NOT NULL tenant column requires (D1).
+  await installDefaultOrganization(engine);
   engine.bindHooks(hooks as never[], {
     packageId: PACKAGE_ID,
     bodyRunner: hookBodyRunnerFactory(new QuickJSScriptRunner(), { ql: engine, appId: APP_ID }),

examples/app-showcase/test/task-reopen-hook-refusal.test.ts

@@ -38,6 +38,7 @@ import {
 import { Account, Project, Task } from '../src/data/objects/index.js';
 import { allHooks, TASK_REOPEN_REFUSAL } from '../src/data/hooks/index.js';
 import { ReopenTaskAction } from '../src/ui/actions/index.js';
+import { installDefaultOrganization } from './default-organization.testkit.js';
 
 const APP_ID = 'com.objectstack.showcase';
 const PACKAGE_ID = `app:${APP_ID}`;
@@ -65,6 +66,9 @@ async function bootShowcase(hooks: unknown[] = allHooks): Promise<ObjectQL> {
     engine.registry.registerObject(def as never, PACKAGE_ID, 'showcase');
   }
   await engine.syncSchemas();
+  // A real `single` install's Default Organization: the system writes below
+  // derive it (ADR-0131 D9), as a fresh NOT NULL tenant column requires (D1).
+  await installDefaultOrganization(engine);
   engine.bindHooks(hooks as never[], {
     packageId: PACKAGE_ID,
     bodyRunner: hookBodyRunnerFactory(new QuickJSScriptRunner(), { ql: engine, appId: APP_ID }),

examples/app-todo/test/default-organization.testkit.ts

@@ -0,0 +1,45 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * Give a lean test engine what every real `single` install has: an
+ * organization object holding its Default Organization.
+ *
+ * ADR-0131 D1: a table the SQL driver creates carries its tenant column NOT
+ * NULL. The engine stamps an organization-less system write with the derived
+ * organization under `single` (D9) — but only where the composition registers
+ * the organization object; a bare `ObjectQL` + `SqlDriver` registers none, so
+ * the write reaches the database with no organization and is refused there.
+ * A suite whose subject is not tenancy (claims, acks, idle cost, at-rest
+ * shapes) calls this once its own objects are registered, so its system
+ * writes land the way they do on a real install.
+ *
+ * The object mirrors the platform's: managed by better-auth, so it carries no
+ * tenant column of its own.
+ */
+export const DEFAULT_ORGANIZATION_ID = 'org_default';
+
+export async function installDefaultOrganization(engine: {
+  registry: { registerObject(def: unknown, owner: string): unknown };
+  getSchema(object: string): unknown;
+  syncSchemas(): Promise<unknown>;
+  getDriverForObject(object: string):
+    | {
+        create(object: string, data: Record<string, unknown>): Promise<unknown>;
+        findOne(object: string, query: unknown): Promise<unknown>;
+      }
+    | undefined;
+}): Promise<void> {
+  // Idempotent: a suite that syncs one engine more than once may call it each time.
+  if (!engine.getSchema('sys_organization')) {
+    engine.registry.registerObject(
+      { name: 'sys_organization', label: 'Organization', managedBy: 'better-auth', fields: { name: { type: 'text', label: 'Name' } } },
+      '@objectstack/example-todo',
+    );
+  }
+  await engine.syncSchemas();
+  // Seeded through the driver: the organization is data at rest, not a write
+  // the suite under test should observe (an audit or activity mirror would).
+  const driver = engine.getDriverForObject('sys_organization')!;
+  if (await driver.findOne('sys_organization', { where: { id: DEFAULT_ORGANIZATION_ID } })) return;
+  await driver.create('sys_organization', { id: DEFAULT_ORGANIZATION_ID, name: 'Default' });
+}

examples/app-todo/test/derived-flag-removal.test.ts

@@ -65,6 +65,7 @@ import { SqliteWasmDriver } from '@objectstack/driver-sqlite-wasm';
 import { Task } from '../src/objects/task.object.js';
 import taskHook from '../src/objects/task.hook.js';
 import TodoApp from '../objectstack.config.js';
+import { installDefaultOrganization } from './default-organization.testkit.js';
 
 /** The two fields this card retired. */
 const REMOVED_FIELDS = ['is_completed', 'is_overdue'] as const;
@@ -94,6 +95,9 @@ async function bootEngine(objectDef: unknown = Task) {
   openDrivers.push(driver);
   objectql.registry.registerObject(objectDef, 'todo', 'todo');
   await objectql.syncSchemas();
+  // A real `single` install's Default Organization: the system writes below
+  // derive it (ADR-0131 D9), as a fresh NOT NULL tenant column requires (D1).
+  await installDefaultOrganization(objectql);
   objectql.bindHooks([taskHook], { packageId: 'app:com.example.todo' });
   return objectql;
 }

examples/app-todo/test/loop-body-iteration.test.ts

@@ -44,6 +44,7 @@ import { AutomationServicePlugin, type AutomationEngine } from '@objectstack/ser
 
 import { OverdueEscalationFlow, TaskReminderFlow } from '../src/flows/index.js';
 import { Task } from '../src/objects/task.object.js';
+import { installDefaultOrganization } from './default-organization.testkit.js';
 
 /** One captured `messaging.emit()` call — the notice as the service received it. */
 interface CapturedEmit {
@@ -109,6 +110,9 @@ async function bootTodoKernel(): Promise<{
   openDrivers.push(driver);
   objectql.registry.registerObject(Task, 'todo', 'todo');
   await objectql.syncSchemas();
+  // A real `single` install's Default Organization: the system writes below
+  // derive it (ADR-0131 D9), as a fresh NOT NULL tenant column requires (D1).
+  await installDefaultOrganization(objectql);
 
   automation.registerFlow(OverdueEscalationFlow.name, OverdueEscalationFlow);
   automation.registerFlow(TaskReminderFlow.name, TaskReminderFlow);

examples/app-todo/test/overdue-escalation-days-overdue.test.ts

@@ -36,6 +36,7 @@ import { SqliteWasmDriver } from '@objectstack/driver-sqlite-wasm';
 
 import { OverdueEscalationFlow } from '../src/flows/index.js';
 import { Task } from '../src/objects/task.object.js';
+import { installDefaultOrganization } from './default-organization.testkit.js';
 
 const openDrivers: Array<{ disconnect?: () => Promise<void> }> = [];
 afterEach(async () => {
@@ -106,6 +107,9 @@ async function bootTodoData(): Promise<any> {
   openDrivers.push(driver);
   objectql.registry.registerObject(Task, 'todo', 'todo');
   await objectql.syncSchemas();
+  // A real `single` install's Default Organization: the system writes below
+  // derive it (ADR-0131 D9), as a fresh NOT NULL tenant column requires (D1).
+  await installDefaultOrganization(objectql);
 
   return kernel.getService('data');
 }

examples/app-todo/test/task-completion-trigger.test.ts

@@ -45,6 +45,7 @@ import { allFlows, TaskCompletionFlow } from '../src/flows/index.js';
 import { Task } from '../src/objects/task.object.js';
 import taskHook from '../src/objects/task.hook.js';
 import TodoApp from '../objectstack.config.js';
+import { installDefaultOrganization } from './default-organization.testkit.js';
 
 const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
 
@@ -83,6 +84,9 @@ async function bootTodoKernel(): Promise<{
   openDrivers.push(driver);
   objectql.registry.registerObject(Task, 'todo', 'todo');
   await objectql.syncSchemas();
+  // A real `single` install's Default Organization: the system writes below
+  // derive it (ADR-0131 D9), as a fresh NOT NULL tenant column requires (D1).
+  await installDefaultOrganization(objectql);
 
   // [#7036] The app's lifecycle hook, bound the way `AppPlugin` binds it from
   // `defineStack({ hooks })`. This kernel is assembled by hand (no AppPlugin),
@@ -359,6 +363,9 @@ describe('#7036 — completing a task is possible for a normal user', () => {
     openDrivers.push(driver);
     objectql.registry.registerObject(Task, 'todo', 'todo');
     await objectql.syncSchemas();
+    // A real `single` install's Default Organization: the system writes below
+    // derive it (ADR-0131 D9), as a fresh NOT NULL tenant column requires (D1).
+    await installDefaultOrganization(objectql);
     // NB: no `bindHooks` — that is the whole fixture.
 
     const id = await newTask(data);