feat(spec)!: remove tenancy.strategy + tenancy.crossTenantAccess — strict tenancy block with tombstones (#2962)

os-zhuang · web-flow · commit f71d19a05a9b · 2026-07-15T22:41:36.000+08:00
Implements the #2763 owner decision (enforce-or-remove): TenancyConfigSchema drops its two zero-consumer fields and rejects unknown keys with tombstone guidance pointing at the two real tenancy modes (database-per-tenant = environment-level deployment; row-level isolation = enabled + tenantField). Ships in the 15.x line per the launch-window policy.
diff --git a/.changeset/remove-tenancy-strategy-crosstenant.md b/.changeset/remove-tenancy-strategy-crosstenant.md
@@ -0,0 +1,37 @@
+---
+'@objectstack/spec': minor
+---
+
+feat(spec)!: remove `tenancy.strategy` + `tenancy.crossTenantAccess`; tenancy block is now strict (#2763)
+
+> ⚠️ RELEASE NOTE — breaking by strict semver, shipped as `minor` per the
+> launch-window policy (owner decision on PR #2962): the fields had zero
+> consumers, behavior is unchanged, and the parse error carries the
+> migration. Fold into the v15 release page's "What's new in 15.x" section
+> when versioning.
+
+BREAKING CHANGE: `TenancyConfigSchema` drops its two zero-consumer fields, and
+the `tenancy` block is now `.strict()` — an unknown key is a loud parse error
+with tombstone guidance instead of a silent zod strip (#1535; precedent
+ADR-0056 D8 "compliance-grade config must never merely look live", ADR-0049
+enforce-or-remove).
+
+The platform has exactly two tenancy modes, and neither needs object-level
+strategy config: database-per-tenant isolation is an environment/deployment
+choice (each environment carries its own database URL), and shared-database
+row isolation is `tenancy.enabled` + `tenancy.tenantField` (both stay, both
+live: sql-driver row scoping, security-plugin org scoping). Cross-tenant
+visibility is governed by sharing rules / OWD (ADR-0056),
+`externalSharingModel` (ADR-0090 D11), and the object access posture — never
+by a blanket boolean.
+
+Migration (delete the keys; nothing read them, so behavior is unchanged):
+
+- FROM `tenancy: { enabled: false, strategy: 'shared' }` → TO `tenancy: { enabled: false }`
+- FROM `tenancy: { enabled: true, strategy: '...', tenantField: 'x', crossTenantAccess: false }` → TO `tenancy: { enabled: true, tenantField: 'x' }`
+- Wanted per-tenant databases? Deploy per environment (EnvironmentKernelFactory) — not object metadata.
+- Wanted cross-tenant visibility? Use sharing rules / OWD or `externalSharingModel`.
+
+The compile-time authorWarn for these fields (#2750) and their liveness-ledger
+entries are retired with the removal; the schema itself now carries the
+prescription.
diff --git a/content/docs/data-modeling/objects.mdx b/content/docs/data-modeling/objects.mdx
@@ -108,12 +108,15 @@ enable: {
 
 #### Multi-Tenancy
 
+Row-level tenant isolation in a shared database — the tenant field is injected
+on write and enforced on read. Database-per-tenant isolation is an
+environment/deployment choice (each environment carries its own database URL),
+not object metadata.
+
 ```typescript
 tenancy: {
   enabled: true,
-  strategy: 'shared',         // 'shared' | 'isolated' | 'hybrid'
   tenantField: 'tenant_id',
-  crossTenantAccess: false,
 }
 ```
 
diff --git a/content/docs/protocol/objectql/schema.mdx b/content/docs/protocol/objectql/schema.mdx
@@ -642,8 +642,7 @@ Isolate data by tenant:
 ```yaml
 name: customer
 tenancy:
-  enabled: true       # Automatically filter by the tenant field
-  strategy: shared    # shared (row-level) | isolated (DB per tenant) | hybrid
+  enabled: true       # Automatically filter by the tenant field (row-level isolation)
   tenantField: tenant_id
 fields:
   tenant_id:
diff --git a/content/docs/references/data/object.mdx b/content/docs/references/data/object.mdx
@@ -228,9 +228,7 @@ Type: `string[]`
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
 | **enabled** | `boolean` | ✅ | Enable multi-tenancy for this object |
-| **strategy** | `Enum<'shared' \| 'isolated' \| 'hybrid'>` | ✅ | Tenant isolation strategy: shared (single DB, row-level), isolated (separate DB per tenant), hybrid (mix) |
 | **tenantField** | `string` | ✅ | Field name for tenant identifier |
-| **crossTenantAccess** | `boolean` | ✅ | Allow cross-tenant data access (with explicit permission) |
 
 
 ---
diff --git a/packages/cli/src/utils/lint-liveness-properties.test.ts b/packages/cli/src/utils/lint-liveness-properties.test.ts
@@ -117,11 +117,12 @@ describe('lintLivenessProperties', () => {
     expect(paths(findings).some((m) => m.includes('`timeout`'))).toBe(true);
   });
 
-  it('warns on the security-shaped dead props (tenancy.strategy / tool.permissions / permission.contextVariables)', () => {
-    const tenancy = lintLivenessProperties(objStack({ tenancy: { enabled: true, strategy: 'isolated' } }));
-    expect(paths(tenancy).some((m) => m.includes('tenancy.strategy'))).toBe(true);
-    // tenancy.enabled itself is live — must NOT warn.
-    expect(paths(tenancy).some((m) => m.includes('tenancy.enabled'))).toBe(false);
+  it('warns on the security-shaped dead props (tool.permissions / permission.contextVariables)', () => {
+    // tenancy.strategy/crossTenantAccess left this list after spec 15.0 (#2763):
+    // the schema now REJECTS them (strict tenancy block), so the ledger entries
+    // are gone and the live tenancy knobs must not warn.
+    const tenancy = lintLivenessProperties(objStack({ tenancy: { enabled: true, tenantField: 'org_id' } }));
+    expect(paths(tenancy).some((m) => m.includes('tenancy'))).toBe(false);
 
     const tool = lintLivenessProperties({ tools: [{ name: 't1', permissions: ['crm.admin'] }] });
     expect(paths(tool).some((m) => m.includes('`permissions`'))).toBe(true);
diff --git a/packages/platform-objects/src/identity/sys-sso-provider.object.ts b/packages/platform-objects/src/identity/sys-sso-provider.object.ts
@@ -45,7 +45,7 @@ export const SysSsoProvider = ObjectSchema.create({
   // Together: admins see all env providers; non-admins get 403. better-auth's
   // own endpoints already read via a system context. (Env-only object — no
   // control-plane cross-tenant risk.)
-  tenancy: { enabled: false, strategy: 'shared' },
+  tenancy: { enabled: false },
   requiredPermissions: ['manage_platform_settings'],
   // ADR-0010 §3.7 — managed by better-auth; tenants may not edit schema.
   protection: {
diff --git a/packages/plugins/driver-sql/src/sql-driver-tenant-scope.test.ts b/packages/plugins/driver-sql/src/sql-driver-tenant-scope.test.ts
@@ -231,7 +231,7 @@ describe('SqlDriver tenant scope (organization_id)', () => {
         {
           name: 'workspace_item',
           // Custom tenant column name — not the conventional organization_id.
-          tenancy: { enabled: true, strategy: 'shared', tenantField: 'workspace_id', crossTenantAccess: false },
+          tenancy: { enabled: true, tenantField: 'workspace_id' },
           fields: {
             workspace_id: { type: 'string' },
             name: { type: 'string' },
@@ -257,7 +257,7 @@ describe('SqlDriver tenant scope (organization_id)', () => {
     const platformGlobal = [
       {
         name: 'sys_license',
-        tenancy: { enabled: false, strategy: 'shared' },
+        tenancy: { enabled: false },
         fields: {
           customer: { type: 'string' },
           organization_id: { type: 'string' }, // optional owner FK, may be NULL
diff --git a/packages/plugins/driver-sqlite-wasm/src/sqlite-wasm-driver-tenant-scope.test.ts b/packages/plugins/driver-sqlite-wasm/src/sqlite-wasm-driver-tenant-scope.test.ts
@@ -192,7 +192,7 @@ describe('SqliteWasmDriver tenant scope (organization_id)', () => {
         {
           name: 'workspace_item',
           // Custom tenant column name — not the conventional organization_id.
-          tenancy: { enabled: true, strategy: 'shared', tenantField: 'workspace_id', crossTenantAccess: false },
+          tenancy: { enabled: true, tenantField: 'workspace_id' },
           fields: {
             workspace_id: { type: 'string' },
             name: { type: 'string' },
diff --git a/packages/plugins/plugin-security/src/security-plugin.test.ts b/packages/plugins/plugin-security/src/security-plugin.test.ts
@@ -224,7 +224,7 @@ describe('SecurityPlugin', () => {
       permissionSets: [tenantPolicySet],
       // Catalog table without organization_id; opts out of tenancy.
       objectFields: ['id', 'manifest_id', 'visibility', 'owner_org_id'],
-      schemaExtra: { tenancy: { enabled: false, strategy: 'shared' } },
+      schemaExtra: { tenancy: { enabled: false } },
       orgScoping: true,
     });
     await plugin.init(harness.ctx);
@@ -809,7 +809,7 @@ describe('SecurityPlugin', () => {
       const harness = makeMiddlewareCtx({
         permissionSets: [tenantPolicySet],
         objectFields: ['id', 'name'],
-        schemaExtra: { tenancy: { enabled: false, strategy: 'shared' } },
+        schemaExtra: { tenancy: { enabled: false } },
         orgScoping: true,
       });
       await plugin.init(harness.ctx);
diff --git a/packages/spec/liveness/README.md b/packages/spec/liveness/README.md
@@ -189,13 +189,13 @@ EOF
 
 | Type | live | exp | dead | planned | Notes |
 |---|---|---|---|---|---|
-| object | 36 | – | 14 | – | versioning/partitioning/cdc tier dead; ObjectCapabilities fully live post-#2707/#2727; `tenancy.strategy`/`crossTenantAccess` inert (only `enabled`+`tenantField` read) |
-| field | 54 | – | 6 | – | near-healthy; dead = referenceFilters/columnName/index/vectorConfig/fileAttachmentConfig/dependencies, all authorWarn'd |
+| object | 37 | – | 12 | 1 | versioning/partitioning/cdc tier dead; ObjectCapabilities fully live post-#2707/#2727; `tenancy.strategy`/`crossTenantAccess` REMOVED post-15.0 (#2763) — tenancy block is now strict with tombstone guidance |
+| field | 55 | – | 6 | – | near-healthy; dead = referenceFilters/columnName/index/vectorConfig/fileAttachmentConfig/dependencies, all authorWarn'd |
 | flow | 27 | – | 4 | – | dead = description/template/nodes.outputSchema/errorHandling.fallbackNodeId (engine uses fault edges) |
 | action | 34 | 1 | 1 | – | `disabled` went LIVE via metadata-admin authoring UI (2026-06 audit missed objectui); only `timeout` dead |
 | hook | 11 | – | 2 | – | model-healthy; only label/description dead (benign) |
 | permission | 32 | – | 1 | – | CRUD/FLS/RLS live; `contextVariables` dead (RLS uses current_user.* built-ins only) |
-| position | 3 | – | – | – | (role's ADR-0090 successor) fully live |
+| position | 4 | – | – | – | (role's ADR-0090 successor) fully live |
 | agent | 14 | 5 | 1 | – | `tenantId` dead (tenancy comes from request context); autonomy tier experimental |
 | tool | 9 | 1 | 1 | – | `permissions` dead — tool invocation not permission-gated by it |
 | skill | 10 | – | – | – | fully live |
diff --git a/packages/spec/liveness/object.json b/packages/spec/liveness/object.json
@@ -132,24 +132,10 @@
           "status": "live",
           "evidence": "packages/plugins/driver-sql/src/sql-driver.ts:1081"
         },
-        "strategy": {
-          "status": "dead",
-          "evidence": "inert — only tenancy.enabled is read",
-          "note": "REMOVAL DECIDED (#2763, owner 2026-07-10): the platform has exactly two tenancy modes — per-tenant database (environment-level, zero object config) and shared-DB org row isolation (enabled+tenantField). Object-level isolation strategy has no requirement; remove at the next spec major.",
-          "authorWarn": true,
-          "authorHint": "No requirement — removal decided (#2763). Library-level isolation is an environment/deployment choice; row-level isolation is tenancy.enabled + tenantField. This knob changes nothing."
-        },
         "tenantField": {
           "status": "live",
           "evidence": "packages/plugins/driver-sql/src/sql-driver.ts",
-          "note": "row-level tenant scoping (org-scoping plugin path) reads tenancy.tenantField — audit called it inert; corrected."
-        },
-        "crossTenantAccess": {
-          "status": "dead",
-          "evidence": "inert",
-          "note": "REMOVAL DECIDED (#2763, owner 2026-07-10): cross-visibility governance lives in sharing/OWD (ADR-0056), externalSharingModel (ADR-0090 D11) and access posture; a blanket boolean has no requirement. Remove at the next spec major.",
-          "authorWarn": true,
-          "authorHint": "No requirement — removal decided (#2763). Setting it true grants nothing; use sharing rules / externalSharingModel for cross-visibility."
+          "note": "row-level tenant scoping (org-scoping plugin path) reads tenancy.tenantField — audit called it inert; corrected. strategy/crossTenantAccess were REMOVED after spec 15.0 (#2763): zero consumers; tenancy block is now .strict() with tombstone guidance."
         }
       }
     },
diff --git a/packages/spec/src/data/object.test.ts b/packages/spec/src/data/object.test.ts
@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { ObjectSchema, ObjectCapabilities, IndexSchema, ObjectFieldGroupSchema, ObjectExternalBindingSchema, ObjectAccessConfigSchema, LifecycleSchema, type ServiceObject } from './object.zod';
+import { ObjectSchema, ObjectCapabilities, IndexSchema, ObjectFieldGroupSchema, ObjectExternalBindingSchema, ObjectAccessConfigSchema, LifecycleSchema, TenancyConfigSchema, type ServiceObject } from './object.zod';
 
 describe('ObjectCapabilities', () => {
   it('should apply default values correctly', () => {
@@ -1279,7 +1279,7 @@ describe('ADR-0066 — object access posture (D2) + requiredPermissions (D3)', (
   it('round-trips access + requiredPermissions on an object', () => {
     const obj = ObjectSchema.create({
       name: 'sys_license',
-      tenancy: { enabled: false, strategy: 'shared' },
+      tenancy: { enabled: false },
       access: { default: 'private' },
       requiredPermissions: ['manage_licenses'],
       fields: { signed_token: { type: 'text' } },
@@ -1297,3 +1297,48 @@ describe('ADR-0066 — object access posture (D2) + requiredPermissions (D3)', (
     expect(obj.requiredPermissions).toBeUndefined();
   });
 });
+
+describe('TenancyConfigSchema — #2763 strategy/crossTenantAccess removal', () => {
+  it('accepts the two live knobs and applies the tenantField default', () => {
+    const result = TenancyConfigSchema.parse({ enabled: true });
+    expect(result.enabled).toBe(true);
+    expect(result.tenantField).toBe('tenant_id');
+    expect(TenancyConfigSchema.parse({ enabled: false, tenantField: 'workspace_id' }))
+      .toEqual({ enabled: false, tenantField: 'workspace_id' });
+  });
+
+  it('rejects the retired `strategy` with a tombstone pointing at the two real modes', () => {
+    const result = TenancyConfigSchema.safeParse({ enabled: true, strategy: 'isolated' });
+    expect(result.success).toBe(false);
+    const message = result.error!.issues.map((i) => i.message).join('\n');
+    expect(message).toContain('removed from @objectstack/spec after v15.0 (#2763)');
+    expect(message).toContain('environment/deployment');
+    expect(message).toContain('`tenancy.enabled` + `tenancy.tenantField`');
+  });
+
+  it('rejects the retired `crossTenantAccess` with a tombstone pointing at sharing/OWD', () => {
+    const result = TenancyConfigSchema.safeParse({ enabled: true, crossTenantAccess: true });
+    expect(result.success).toBe(false);
+    const message = result.error!.issues.map((i) => i.message).join('\n');
+    expect(message).toContain('crossTenantAccess');
+    expect(message).toContain('ADR-0056');
+    expect(message).toContain('externalSharingModel');
+  });
+
+  it('rejects arbitrary unknown tenancy keys instead of silently stripping them (#1535)', () => {
+    const result = TenancyConfigSchema.safeParse({ enabled: true, tenantfield: 'org_id' });
+    expect(result.success).toBe(false);
+    expect(result.error!.issues.map((i) => i.message).join('\n'))
+      .toContain('`tenantfield` is not a `tenancy` key');
+  });
+
+  it('rejects a retired key on ObjectSchema.create() (the authoring entrypoint)', () => {
+    expect(() =>
+      ObjectSchema.create({
+        name: 'sys_license',
+        tenancy: { enabled: false, strategy: 'shared' } as never,
+        fields: { name: { type: 'text' } },
+      }),
+    ).toThrow(/removed from @objectstack\/spec after v15\.0/);
+  });
+});
diff --git a/packages/spec/src/data/object.zod.ts b/packages/spec/src/data/object.zod.ts
@@ -153,24 +153,71 @@ export const SearchConfigSchema = lazySchema(() => z.object({
   filters: z.array(z.string()).optional().describe('Default filters for search results'),
 }));
 
+/**
+ * Tombstones for RETIRED tenancy keys — same doctrine as the top-level
+ * `UNKNOWN_KEY_GUIDANCE` map below: a retired key's rejection must carry the
+ * upgrade prescription, because the parse error is the one channel every
+ * consumer bumping `@objectstack/spec` is guaranteed to hit. Removed after
+ * spec 15.0 by owner decision #2763 (enforce-or-remove, ADR-0049; precedent
+ * ADR-0056 D8 — compliance-grade config must never merely look live).
+ */
+const TENANCY_RETIRED_KEY_GUIDANCE: Record<string, string> = {
+  strategy:
+    '`tenancy.strategy` was removed from @objectstack/spec after v15.0 (#2763) — it ' +
+    'never had a consumer. The platform has exactly two tenancy modes and neither is ' +
+    'object-level config: database-per-tenant isolation is an environment/deployment ' +
+    'choice (each environment carries its own database URL), and row-level isolation ' +
+    'is `tenancy.enabled` + `tenancy.tenantField`. Delete the key.',
+  crossTenantAccess:
+    '`tenancy.crossTenantAccess` was removed from @objectstack/spec after v15.0 (#2763) — it ' +
+    'never had a consumer; setting it granted nothing. Cross-tenant visibility is ' +
+    'governed by sharing rules / OWD (ADR-0056), `externalSharingModel` (ADR-0090 ' +
+    'D11), and the object access posture. Delete the key.',
+};
+
+/**
+ * Custom zod `error` for the `.strict()` tenancy block (#2763, pattern of
+ * `strictVisibilityError` / ADR-0089 D3a): an unknown key — a retired
+ * `strategy`/`crossTenantAccess` or a typo — is a loud, *fixable* parse error
+ * instead of a silent strip (#1535), and a retired key's error carries its
+ * upgrade prescription. Every other issue code defers to zod's default.
+ */
+const strictTenancyError: z.core.$ZodErrorMap = (issue) => {
+  if (issue.code !== 'unrecognized_keys') return undefined;
+  const keys = (issue as { keys?: readonly string[] }).keys ?? [];
+  const lines = keys.map((key) =>
+    TENANCY_RETIRED_KEY_GUIDANCE[key] ?? `\`${key}\` is not a \`tenancy\` key.`,
+  );
+  return (
+    `Unrecognized key(s) on \`tenancy\`: ${keys.map((k) => `\`${k}\``).join(', ')}. ` +
+    'The two supported tenancy modes are: database-per-tenant = environment-level ' +
+    'deployment (no object config); row-level isolation = `tenancy.enabled` + ' +
+    '`tenancy.tenantField`.\n' +
+    lines.map((l) => `  • ${l}`).join('\n')
+  );
+};
+
 /**
  * Multi-Tenancy Configuration Schema
- * Configures tenant isolation strategy for SaaS applications
- * 
- * @example Shared database with tenant_id isolation
+ * Row-level tenant isolation for shared-database SaaS applications: the
+ * tenant field is injected on write and enforced on read (RLS predicate).
+ * Platform objects declare `enabled: false` to opt out of org row-scoping
+ * (environment-level objects). Database-per-tenant isolation is NOT object
+ * metadata — it is an environment/deployment choice.
+ *
+ * `.strict()`: unknown keys (incl. the retired `strategy` /
+ * `crossTenantAccess`, #2763) are rejected with guidance, not stripped (#1535).
+ *
+ * @example Shared database with tenant_id row isolation
  * {
  *   enabled: true,
- *   strategy: 'shared',
- *   tenantField: 'tenant_id',
- *   crossTenantAccess: false
+ *   tenantField: 'tenant_id'
  * }
  */
 export const TenancyConfigSchema = lazySchema(() => z.object({
   enabled: z.boolean().describe('Enable multi-tenancy for this object'),
-  strategy: z.enum(['shared', 'isolated', 'hybrid']).describe('Tenant isolation strategy: shared (single DB, row-level), isolated (separate DB per tenant), hybrid (mix)'),
   tenantField: z.string().default('tenant_id').describe('Field name for tenant identifier'),
-  crossTenantAccess: z.boolean().default(false).describe('Allow cross-tenant data access (with explicit permission)'),
-}));
+}, { error: strictTenancyError }).strict());
 
 /**
  * [ADR-0066 D2] Secure-by-default object posture.
diff --git a/skills/objectstack-data/SKILL.md b/skills/objectstack-data/SKILL.md
@@ -615,7 +615,7 @@ OAuth clients). These hit a non-obvious interaction:
 **Recipe — env-global, admin-only object that admins can fully see:**
 
 ```typescript
-tenancy: { enabled: false, strategy: 'shared' }, // env IS the tenant; admin viewAllRecords bypass applies
+tenancy: { enabled: false }, // env IS the tenant; admin viewAllRecords bypass applies
 requiredPermissions: ['manage_platform_settings'], // object-level gate → members get 403
 ```
 

Original file line number	Diff line number	Diff line change
`@@ -192,7 +192,7 @@ describe('SqliteWasmDriver tenant scope (organization_id)', () => {`
`192`	`192`	`{`
`193`	`193`	`name: 'workspace_item',`
`194`	`194`	`// Custom tenant column name — not the conventional organization_id.`
`195`		`- tenancy: { enabled: true, strategy: 'shared', tenantField: 'workspace_id', crossTenantAccess: false },`
	`195`	`+ tenancy: { enabled: true, tenantField: 'workspace_id' },`
`196`	`196`	`fields: {`
`197`	`197`	`workspace_id: { type: 'string' },`
`198`	`198`	`name: { type: 'string' },`