fix(objectql): the cascade skips a federated object's injected tenant anchor

The registry injects `organization_id` (a lookup to `sys_organization`)
into every object it registers, federated ones included, and the platform
provisions no storage for a federated object. The cascade scan probed the
remote table on that column, the driver refused the unknown column, and
every organization delete answered 500 on the showcase once its federated
fixture existed.

Both cascade walks now ask one predicate, `isFederatedInjectedTenantAnchor`:
the column is `organization_id`, the object is federated by
`isFederatedObject`, and the field is the platform's own definition by the
injected-column provenance marker. An author-declared `organization_id` and
any other author lookup on a federated object stay in the scan, and the
probe's catch is unchanged. The atomicity plan asks the same predicate so
it keeps the scan's participant set.

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

Author: claude

.changeset/21910-cascade-federated-tenant-anchor.md

@@ -0,0 +1,11 @@
+---
+'@objectstack/objectql': patch
+---
+
+Deleting an organization no longer fails with a 500 on a deployment that has a federated (ADR-0015 `external`) object bound. The engine's referential cascade no longer treats the `organization_id` the platform injects into a federated object as a reference to `sys_organization`.
+
+Clause-②: no
+
+- **What was wrong.** The registry injects `organization_id` into every object, federated ones included, and the platform provisions no storage for a federated object. The cascade's dependents probe filtered the remote table on that column, the SQL driver refused the unknown column (`INVALID_FILTER`), and the probe's failure propagated, so the delete failed. The showcase, with its federated fixture provisioned, answered every organization delete with 500.
+- **What changed.** The cascade scan skips a federated object's injected tenant anchor. It asks the same `isFederatedObject` predicate as the driver-option builder and the related-record read, plus the injected-column provenance marker, so an `organization_id` the author declared on a federated object is still probed. The cascade's atomicity plan asks the same question, so an organization delete on such a deployment now runs as one transaction instead of being reported as a cross-datasource cascade.
+- **What did not change.** Any lookup an author declares on a federated object is still probed, and a probe that cannot run still fails the delete. Only a missing child table is passed over as having no dependents.

packages/objectql/src/engine-cascade-federated-tenant-anchor.test.ts

@@ -0,0 +1,265 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * [#21910] The referential cascade does not treat a federated object's
+ * platform-INJECTED `organization_id` as a reference to `sys_organization`,
+ * and treats nothing else that way.
+ *
+ * The registry injects the tenant anchor (`organization_id`, a lookup to
+ * `sys_organization`) into every object it registers, ADR-0015 `external` ones
+ * included, and the platform provisions no storage for a federated object. On
+ * the showcase, deleting an organization ran the cascade scan's dependents
+ * probe against the remote `customers` table on that column. The SQL driver
+ * refused it (`INVALID_FILTER`, no such column), the probe's #8895 catch
+ * propagated the refusal, and the organization delete answered 500.
+ *
+ * What this file pins, all through `engine.delete` on a two-driver engine (the
+ * default one, and the remote a federated object is bound to by `datasource`):
+ *
+ *  1. the scan never reads a federated object on its injected anchor, so an
+ *     organization delete lands while that read would be refused. A local
+ *     object's injected anchor IS read on the same delete, which proves the
+ *     scan ran;
+ *  2. an `organization_id` the AUTHOR declared on a federated object is still
+ *     probed, and a probe failure still propagates (#8895);
+ *  3. any other lookup the author declares on a federated object is still
+ *     probed, and a probe failure still propagates (#8895);
+ *  4. the cascade's atomicity plan agrees with the scan: an organization delete
+ *     whose only cross-datasource "participant" was the injected anchor runs
+ *     as one transaction, while an author-declared federated lookup still
+ *     makes the plan cross-datasource.
+ *
+ * The seed rows are written straight into the stub's store, so no write path
+ * other than the delete under test runs. The door pin is
+ * `packages/qa/dogfood/test/organization-delete-federated-fixture.dogfood.test.ts`.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { resolveInjectedColumnProvenance } from '@objectstack/spec/data';
+import { ObjectQL } from './engine.js';
+
+/** The remote datasource every federated fixture below is bound to. */
+const REMOTE = 'remote_ds';
+const PACKAGE_ID = 'test-21910';
+
+type Rows = Map<string, Map<string, Record<string, unknown>>>;
+
+/**
+ * A stub driver that records every read into a shared log and can be told to
+ * refuse reads of one object with an exact error object.
+ */
+function makeDriver(name: string, log: { reads: string[]; begun: number }) {
+  const stores: Rows = new Map();
+  const failReads = new Map<string, unknown>();
+  const storeFor = (o: string) => {
+    let s = stores.get(o);
+    if (!s) { s = new Map(); stores.set(o, s); }
+    return s;
+  };
+  const matches = (row: Record<string, unknown>, where: any): boolean => {
+    if (!where || typeof where !== 'object') return true;
+    for (const [k, v] of Object.entries(where)) {
+      if (k.startsWith('$')) continue;
+      const exp = v && typeof v === 'object' && '$eq' in (v as any) ? (v as any).$eq : v;
+      if ((row[k] ?? null) !== (exp ?? null)) return false;
+    }
+    return true;
+  };
+  const gate = (o: string) => {
+    log.reads.push(o);
+    if (failReads.has(o)) throw failReads.get(o);
+  };
+  const driver: any = {
+    name, version: '0.0.0', supports: {},
+    async connect() {}, async disconnect() {}, async checkHealth() { return true; }, async execute() { return null; },
+    async syncSchema() {},
+    registerExternalObject() {},
+    async find(o: string, ast: any) {
+      gate(o);
+      return Array.from(storeFor(o).values()).filter((r) => matches(r, ast?.where));
+    },
+    async findOne(o: string, ast: any) {
+      gate(o);
+      for (const r of storeFor(o).values()) if (matches(r, ast?.where)) return r;
+      return null;
+    },
+    async count(o: string, ast: any) {
+      gate(o);
+      return Array.from(storeFor(o).values()).filter((r) => matches(r, ast?.where)).length;
+    },
+    async create(o: string, data: Record<string, unknown>) {
+      const row = { ...data, id: String(data.id) };
+      storeFor(o).set(row.id, row);
+      return row;
+    },
+    async update(o: string, id: string, data: Record<string, unknown>) {
+      const cur = storeFor(o).get(String(id));
+      if (!cur) throw new Error(`not found ${o}/${id}`);
+      const up = { ...cur, ...data, id: String(id) };
+      storeFor(o).set(String(id), up);
+      return up;
+    },
+    async upsert(o: string, data: Record<string, unknown>) { return this.create(o, data); },
+    async delete(o: string, id: string) { return storeFor(o).delete(String(id)); },
+    async bulkCreate() { return []; }, async bulkUpdate() { return []; }, async bulkDelete() {},
+    async beginTransaction() { log.begun += 1; return { id: `trx_${log.begun}` }; },
+    async commit() {}, async rollback() {},
+  };
+  return { driver, stores, failReads, seed: (o: string, row: Record<string, unknown>) => storeFor(o).set(String(row.id), row) };
+}
+
+/** The deleted object. Its own injected anchor makes it self-referencing, harmlessly. */
+const ORGANIZATION = {
+  name: 'sys_organization',
+  label: 'Organization',
+  fields: { name: { name: 'name', label: 'Name', type: 'text' as const } },
+};
+
+/** A LOCAL object: the registry injects `organization_id`, and storage backs it. */
+const LOCAL = {
+  name: 'acct',
+  label: 'Account',
+  fields: { name: { name: 'name', label: 'Name', type: 'text' as const } },
+};
+
+/** Federated, as the showcase declares it: no `organization_id` of its own. */
+const FEDERATED = {
+  name: 'ext_customer',
+  label: 'External Customer',
+  datasource: REMOTE,
+  external: { remoteName: 'customers' },
+  fields: { name: { name: 'name', label: 'Name', type: 'text' as const } },
+};
+
+/** Federated, with an `organization_id` the AUTHOR declared: it maps a real remote column. */
+const FEDERATED_DECLARED_ANCHOR = {
+  name: 'ext_tenant_customer',
+  label: 'External Tenant Customer',
+  datasource: REMOTE,
+  external: { remoteName: 'tenant_customers' },
+  fields: {
+    name: { name: 'name', label: 'Name', type: 'text' as const },
+    organization_id: {
+      name: 'organization_id',
+      label: 'Remote Organization',
+      type: 'lookup' as const,
+      reference: 'sys_organization',
+    },
+  },
+};
+
+/** Federated, with another lookup the author declared against the organization. */
+const FEDERATED_AUTHOR_LOOKUP = {
+  name: 'ext_order',
+  label: 'External Order',
+  datasource: REMOTE,
+  external: { remoteName: 'orders' },
+  fields: {
+    amount: { name: 'amount', label: 'Amount', type: 'number' as const },
+    org_ref: { name: 'org_ref', label: 'Organization', type: 'lookup' as const, reference: 'sys_organization' },
+  },
+};
+
+const ORG_ID = 'org_21910';
+
+/** The refusal the SQL driver answers for a filter on a column the remote does not have. */
+function unknownColumnRefusal(object: string, column: string) {
+  return Object.assign(
+    new Error(`A filter on object '${object}' names a column the database could not resolve (${column}).`),
+    { code: 'INVALID_FILTER', status: 400 },
+  );
+}
+
+async function makeEngine(objects: any[]) {
+  const log = { reads: [] as string[], begun: 0 };
+  const warnings: string[] = [];
+  const logger = {
+    debug() {}, info() {}, error() {},
+    warn: (message: unknown) => void warnings.push(String(message)),
+  };
+  const engine = new ObjectQL({ logger } as any);
+  const local = makeDriver('memory', log);
+  const remote = makeDriver(REMOTE, log);
+  engine.registerDriver(local.driver, true);
+  engine.registerDriver(remote.driver);
+  await engine.init();
+  for (const o of objects) engine.registry.registerObject(o, PACKAGE_ID);
+  local.seed('sys_organization', { id: ORG_ID, name: 'Doomed Org' });
+  return { engine, local, remote, log, warnings };
+}
+
+const NOT_ATOMIC = 'cannot run as one unit of work';
+
+describe('[#21910] the cascade scan skips a federated object\'s injected tenant anchor, and nothing else', () => {
+  it('never probes a federated object on its injected organization_id, so the organization delete lands', async () => {
+    const { engine, local, remote, log } = await makeEngine([ORGANIZATION, LOCAL, FEDERATED]);
+    // PREMISE: the registered schema carries the platform's injected anchor.
+    expect(resolveInjectedColumnProvenance(engine.getSchema('ext_customer'), 'organization_id'))
+      .toBe('injected-unprovisioned');
+    // Any read of the remote table on that column is refused, as the showcase measured.
+    remote.failReads.set('ext_customer', unknownColumnRefusal('ext_customer', 'organization_id'));
+
+    log.reads.length = 0;
+    await engine.delete('sys_organization', { where: { id: ORG_ID } } as any);
+
+    expect(local.stores.get('sys_organization')?.has(ORG_ID)).toBe(false);
+    expect(log.reads).not.toContain('ext_customer');
+    // CONTROL: the scan ran for this delete, and probed the local object's injected anchor.
+    expect(log.reads).toContain('acct');
+  });
+
+  it('still probes an organization_id the AUTHOR declared on a federated object, and its failure propagates (#8895)', async () => {
+    const { engine, local, remote, log } = await makeEngine([ORGANIZATION, FEDERATED_DECLARED_ANCHOR]);
+    expect(resolveInjectedColumnProvenance(engine.getSchema('ext_tenant_customer'), 'organization_id'))
+      .toBe('author');
+    const injected = unknownColumnRefusal('ext_tenant_customer', 'organization_id');
+    remote.failReads.set('ext_tenant_customer', injected);
+
+    log.reads.length = 0;
+    const err: any = await engine.delete('sys_organization', { where: { id: ORG_ID } } as any).catch((e) => e);
+
+    expect(err).toBe(injected);
+    expect(err.code).toBe('INVALID_FILTER');
+    expect(err.status).toBe(400);
+    expect(log.reads).toContain('ext_tenant_customer');
+    expect(local.stores.get('sys_organization')?.has(ORG_ID)).toBe(true);
+  });
+
+  it('still probes any other lookup the author declared on a federated object, and its failure propagates (#8895)', async () => {
+    const { engine, local, remote, log } = await makeEngine([ORGANIZATION, FEDERATED_AUTHOR_LOOKUP]);
+    const injected = unknownColumnRefusal('ext_order', 'org_ref');
+    remote.failReads.set('ext_order', injected);
+
+    log.reads.length = 0;
+    const err: any = await engine.delete('sys_organization', { where: { id: ORG_ID } } as any).catch((e) => e);
+
+    expect(err).toBe(injected);
+    expect(err.code).toBe('INVALID_FILTER');
+    expect(err.status).toBe(400);
+    expect(log.reads).toContain('ext_order');
+    expect(local.stores.get('sys_organization')?.has(ORG_ID)).toBe(true);
+  });
+});
+
+describe('[#21910] the cascade atomicity plan agrees with the scan about who takes part', () => {
+  it('runs the organization delete as one transaction when the injected anchor was its only cross-datasource reference', async () => {
+    const { engine, local, log, warnings } = await makeEngine([ORGANIZATION, LOCAL, FEDERATED]);
+
+    await engine.delete('sys_organization', { where: { id: ORG_ID } } as any);
+
+    expect(local.stores.get('sys_organization')?.has(ORG_ID)).toBe(false);
+    expect(log.begun).toBe(1);
+    expect(warnings.filter((w) => w.includes(NOT_ATOMIC))).toEqual([]);
+  });
+
+  it('CONTROL: an author-declared lookup on a federated object still makes the plan cross-datasource', async () => {
+    const { engine, local, log, warnings } = await makeEngine([ORGANIZATION, LOCAL, FEDERATED_AUTHOR_LOOKUP]);
+
+    await engine.delete('sys_organization', { where: { id: ORG_ID } } as any);
+
+    expect(local.stores.get('sys_organization')?.has(ORG_ID)).toBe(false);
+    expect(log.reads).toContain('ext_order');
+    expect(log.begun).toBe(0);
+    expect(warnings.filter((w) => w.includes(NOT_ATOMIC))).toHaveLength(1);
+  });
+});

packages/objectql/src/engine.ts

@@ -304,7 +304,8 @@ import {
   withDeclaredColumnsOnly,
 } from './declared-read-columns.js';
 // [#21777] "Is this schema the remote's?" One predicate, shared with the boot sync.
-import { isFederatedObject } from './federated-object.js';
+// [#21910] And its tenant-anchor refinement, which both cascade walks ask.
+import { isFederatedObject, isFederatedInjectedTenantAnchor } from './federated-object.js';
 import { applyInMemoryAggregation } from './in-memory-aggregation.js';
 import {
   resolveEngineDeleteDispatch,
@@ -15832,7 +15833,7 @@ export class ObjectQL implements IObjectQLEngine {
         const childName = (child as any)?.name as string | undefined;
         const fields = (child as any)?.fields as Record<string, any> | undefined;
         if (!childName || !fields) continue;
-        for (const fdef of Object.values(fields)) {
+        for (const [fieldName, fdef] of Object.entries(fields)) {
           if (!fdef || (fdef.type !== 'master_detail' && fdef.type !== 'lookup')) continue;
           // [#18550] The carrier is read through the ONE arbiter, so a
           // `reference` no reader can read REFUSES here instead of reading as
@@ -15856,6 +15857,13 @@ export class ObjectQL implements IObjectQLEngine {
           let resolvedRef: string | undefined;
           try { resolvedRef = this.resolveObjectName(ref); } catch { resolvedRef = undefined; }
           if (ref !== name && resolvedRef !== name) continue;
+          // [#21910] The scan skips a federated object's injected tenant
+          // anchor, so this walk does too, and the participant set stays the
+          // scan's. Counting it read every organization delete on a deployment
+          // with a federated object bound as cross-datasource (`'split'`): the
+          // cascade ran unwrapped, and the warning named a datasource the
+          // cascade never touches.
+          if (isFederatedInjectedTenantAnchor(child, fieldName)) continue;
           out.push(childName);
           break;
         }
@@ -16324,6 +16332,26 @@ export class ObjectQL implements IObjectQLEngine {
         try { resolvedRef = this.resolveObjectName(ref); } catch { resolvedRef = undefined; }
         if (ref !== object && resolvedRef !== object) continue;
 
+        // [#21910] A federated object's platform-INJECTED tenant anchor is not
+        // a reference to `sys_organization`, so it is not a relation to probe.
+        // On a federated object that column exists in the registered schema
+        // and nowhere else: the probe below was refused by the driver
+        // (`INVALID_FILTER`, no such column), its catch propagated the refusal
+        // as #8895 rules for a missing column, and every organization delete
+        // answered 500 on a deployment with a federated object bound.
+        // `buildDriverOptions` and the related-record read already refuse this
+        // reading of the same column. {@link isFederatedInjectedTenantAnchor}
+        // says why it is exactly that column, and
+        // {@link ObjectQL.planCascadeAtomicity} asks it too.
+        //
+        // ⛔ The catch below is deliberately NOT widened to pass a missing
+        // column as benign. That would invert #8895's discriminate or
+        // propagate for every object, not just this injected column: an
+        // `organization_id` the author declared on a federated object, and any
+        // other lookup the author declares on one, stay in the scan, and their
+        // probe failures still propagate.
+        if (isFederatedInjectedTenantAnchor(child, fieldName)) continue;
+
         // A master-detail parent owns its children: cascade by default (the
         // child FK is typically required, so set_null would be invalid). Only
         // an explicit `restrict` deviates. A plain lookup honors its

packages/objectql/src/federated-object.ts

@@ -1,5 +1,8 @@
 // Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
 
+import { resolveInjectedColumnProvenance } from '@objectstack/spec/data';
+import { DEFAULT_TENANT_FIELD } from './tenancy/system-write-organization.js';
+
 /**
  * Is `schema` a federated object (ADR-0015 `external`), one whose schema is
  * owned by the REMOTE database?
@@ -31,3 +34,42 @@
 export function isFederatedObject(schema: unknown): boolean {
   return (schema as { external?: unknown } | null | undefined)?.external != null;
 }
+
+/**
+ * [#21910] Is `fieldName` a federated object's platform-INJECTED tenant
+ * anchor: the `organization_id` lookup to `sys_organization` that the
+ * registry adds and the remote table does not have?
+ *
+ * `applySystemFields` injects `organization_id` into every object it
+ * registers, ADR-0015 `external` ones included (the #7865 ruling, direction
+ * B), and the platform provisions no storage for a federated object. So on
+ * one, that column exists in the registered schema and nowhere else, and it
+ * is never a reference to an organization: no remote row can hold one. The
+ * engine's referential cascade asks this in both of its walks, so the two
+ * cannot disagree about which objects take part in an organization delete:
+ *
+ * - `ObjectQL.cascadeDeleteRelations` does not probe the remote table on it
+ *   (the probe was refused as an unknown column, and every organization
+ *   delete answered 500);
+ * - `ObjectQL.planCascadeAtomicity` does not count the federated object as a
+ *   participant on another datasource.
+ *
+ * Three conjuncts, and each one is the narrowing:
+ *
+ * - the column is the tenant anchor, `organization_id`. The other anchors
+ *   the registry injects (`owner_id`, `created_by`, ...) are not this
+ *   question;
+ * - the object is federated, by {@link isFederatedObject}, the same predicate
+ *   `buildDriverOptions` and the related-record read ask;
+ * - the field is the platform's own definition, by the #7865 provenance
+ *   marker. An `organization_id` the author declared answers `'author'` and
+ *   stays a relation: it may map a real remote column, and its probe keeps
+ *   #8895's discriminate or propagate.
+ */
+export function isFederatedInjectedTenantAnchor(schema: unknown, fieldName: string): boolean {
+  return (
+    fieldName === DEFAULT_TENANT_FIELD &&
+    isFederatedObject(schema) &&
+    resolveInjectedColumnProvenance(schema, fieldName) === 'injected-unprovisioned'
+  );
+}