docs(qa): state the org-wall boundary at the dogfood autoconnect assertion (#7834)

[hotlong]

Fixes #7834

Executes the maintainer's 2026-08-12 ruling (issue comment 5261737155) — option 2: accept that the federated-read × org-walled intersection is covered at the unit/seam tier only, and write that boundary onto the dogfood test. Comment-only: +44 lines, 1 file, 0 deletions, no behaviour change and no new assertion.

Why a comment is the whole deliverable

This card exists because a green required test that names a path but boots it inert reads as coverage and is not. So a vague "see also #7833" note would reproduce the original problem in comment form. The comment states four things concretely — what IS covered, what is NOT, where the real defence lives, and why it is deliberately left this way.

Before / after

Before — the assertion carried no boundary statement at all:

  it('federated customer object is queryable (auto-connected, seeded fixture rows returned)', async () => {
    const res = await stack.apiAs(admin, 'GET', '/data/showcase_ext_customer');
    expect(res.status, 'federated object must be queryable — driver auto-connected').toBe(200);
    const rows = listOf(await res.json());
    expect(rows.length).toBeGreaterThanOrEqual(3);
    expect(rows.map((r) => r.name)).toContain('Aurora Labs');
  });

After — 44 comment lines inserted immediately above expect(rows.length).toBeGreaterThanOrEqual(3); the assertions themselves are byte-identical:

    const rows = listOf(await res.json());
    // [#7834] ⛔ THIS ASSERTION IS NOT ORG-WALL COVERAGE — read this before
    // treating a green run of this file as proof of anything about tenancy.
    //
    // What it DOES cover (real, which is why this test is not skipped): the
    // ADR-0062 D8 auto-connect path — a declared external datasource connects
    // at boot with no `onEnable` driver bridge, and its federated objects
    // answer a genuine authenticated read through the real REST stack.
    //
    // What it does NOT cover: the organization wall. `bootStack(showcaseStack)`
    // above passes NO options, and `bootStack` requests
    // `OS_TENANCY_POSTURE = 'isolated'` only when `opts.multiTenant` is truthy
    // (`packages/verify/src/harness.ts`, `requestIsolatedPosture`). It also
    // boots AuthPlugin with `autoDefaultOrganization: false` and registers no
    // organization plugin. So this fixture boots posture `single` — the boot
    // log says so: `[security] tenancy posture 'single' — Layer 0 is inert` —
    // with no active org. `execCtx.tenantId` is therefore undefined, which is
    // the FIRST conjunct of `hasTenant` in `ObjectQLEngine.buildDriverOptions`
    // (`packages/objectql/src/engine.ts`); it short-circuits false before the
    // `isFederated` exemption is even reached, and the driver is handed no
    // `tenantId` to scope by. **The org predicate is never emitted here, in
    // either direction.** Measured on #7738: `engine.ts` was checked back out
    // at pre-fix `main`, `@objectstack/objectql` rebuilt, and this file re-run
    // — 3 passed / 3 both WITH the fix and WITHOUT it. This assertion sat green
    // while a correctly-bound federated object answered 0 rows under a real
    // org wall, and it cannot catch a regression of that.
    //
    // Where the regression defence actually lives: the seam pin in
    // `packages/objectql/src/engine-external-tenant-scope.test.ts` (#7833). It
    // asserts on `DriverOptions` in both directions — an external object gets
    // no `tenantId`/`tenantIds`, an ordinary one still does — and is reachable
    // without the enterprise package. ⛔ That is a UNIT/SEAM pin, not
    // end-to-end proof: it pins what the engine hands the driver, never what a
    // walled deployment returns over HTTP.
    //
    // Why this is deliberately left as-is (maintainer ruling, 2026-08-12 on
    // #7834): the federated-read × org-walled intersection is accepted as
    // covered at the unit/seam tier ONLY. The single honest walled harness is
    // `multiTenant: true` with the cloud-private `@objectstack/organizations`
    // (`'posture-only'` stamps nothing and scopes no query — see
    // `BootOptions.multiTenant` — so it would assert nothing here); its
    // feasibility in this repo is untested, and one intersection does not
    // justify building that fixture. ⛔ Do not "fix" this by asserting tenancy
    // on this single-tenant boot — that pins the inert path and makes the
    // false reading of coverage worse.
    expect(rows.length).toBeGreaterThanOrEqual(3);
    expect(rows.map((r) => r.name)).toContain('Aurora Labs');

Every factual claim in the comment, and the measurement behind it

The card's own failure class is pointing at coverage that is not there, so no claim below is inherited — each was re-measured on this branch's origin/main base (d447939).

1. The premise still holds at both cited sites

claim	measurement
the rows.length >= 3 assertion still exists at the cited site	expect(rows.length).toBeGreaterThanOrEqual(3) present in showcase-external-autoconnect.dogfood.test.ts, in the federated customer object is queryable case
bootStack requests isolated only when opts.multiTenant is truthy	packages/verify/src/harness.ts: const requestIsolatedPosture = !!opts.multiTenant && !prevTenancyPosture; / if (requestIsolatedPosture) process.env.OS_TENANCY_POSTURE = 'isolated';
this fixture passes no options	stack = await bootStack(showcaseStack); — single argument
the harness mints no default org either	packages/verify/src/harness.ts: new AuthPlugin({ …, autoDefaultOrganization: false })
no organization plugin is registered without multiTenant	packages/verify/src/harness.ts: the SimulatedOrgScopingPlugin / OrganizationsPlugin mounts sit behind if (opts.multiTenant === 'posture-only') … else if (opts.multiTenant)

2. The boot really is single-tenant — quoted from this test's own boot log

2026-08-12T04:15:42.572Z INFO [security] tenancy posture 'single' — Layer 0 is inert; the platform's own tenant-scoped RLS policies are stripped (app-authored ones are retained and fail closed, ADR-0105 D3)

Corroborated in the same run by [security] org-admin grant backfill complete {…,"posture":"single"}.

3. The predicate does not fire — re-measured directly, not inferred

The comment's central claim is that the org predicate is never emitted here, in either direction. Two independent measurements, both run on this branch:

(a) The fix is a no-op for this file. #7833's !isFederated guard was temporarily removed from buildDriverOptions locally and @objectstack/objectql rebuilt. The file still passed 3 passed / 3, reproducing #7738's dev's result. A test that could catch the defect would have gone red here.

(b) A probe on the real call site. With the guard still removed, a temporary probe in buildDriverOptions logged every call in the whole boot:

object=showcase_ext_customer tenantId=undefined isFederated=true hasTenant=false
object=showcase_ext_order    tenantId=undefined isFederated=true hasTenant=false

isFederated=true yet hasTenant=false — because execCtx?.tenantId !== undefined is the first conjunct and short-circuits, exactly as the comment says. Across the entire boot: 1069 buildDriverOptions calls, 0 with hasTenant=true, and tenantId=undefined the only value ever observed. There is no active org anywhere in this fixture, so the wall cannot be crossed by any assertion in this file.

Both the guard removal and the probe were reverted; git status is clean apart from the comment, and @objectstack/objectql was rebuilt from unmodified source before the gates below.

4. What #7833's pin actually covers — read from the merged code, not from its PR body

packages/objectql/src/engine-external-tenant-scope.test.ts exists on main (PR #7833, merged 2026-08-11). Read directly, it asserts on DriverOptions, in both directions:

• external object: expect(call!.options?.tenantId ?? undefined).toBeUndefined() and the same for tenantIds, over it.each(READ_DOORS);
• ordinary object: expect(call!.options?.tenantId).toBe('org_msoroxgurm6423gz'), and tenantIds still threaded under the group posture;
• caller-supplied tenantId by name still wins.

It builds its own ExecutionContext with a literal tenantId and a fake driver, so it is reachable without @objectstack/organizations — which is what makes it a usable defence here. It is a unit/seam pin: it constrains what the engine hands the driver, not what a walled deployment returns over HTTP. The comment says exactly that, in those words, with the ⛔ attached.

5. The structural claim, corroborated by the suite itself

The card says the one honest walled harness is unavailable in this repo. That is observable in the run: test/rls-multitenant.dogfood.test.ts — the file that would exercise cross-tenant isolation — skips entirely here (1 skipped (1) file / 2 skipped (2) tests) because @objectstack/organizations is absent. It is the whole of the "1 skipped" file in the suite result below. Pre-existing and unrelated to this change.

Verification

There is no behaviour to pin here. The deliverable is a comment; adding a test to assert that a comment exists would be theatre, and every alternative the card lists is explicitly forbidden by the ruling (no posture-aware fixture, no assertion on the single-tenant boot, no skip). So the verification obligation is: the claims are true (above), and the test still passes unchanged.

gate	result
showcase-external-autoconnect.dogfood.test.ts (post-change, clean build)	3 passed / 3, 1 file
packages/qa/dogfood full suite	92 passed / 1 skipped (93 files), 588 passed / 3 skipped (591 tests), 0 failed — the skips are the org-gated rls-multitenant file and are pre-existing
eslint on the changed file	exit 0, clean
packages/qa/dogfood tsc --noEmit	exit 0
pnpm build (full workspace)	exit 0 — 71/71 tasks
node scripts/pm/dispatch-gates.mjs packages/qa/dogfood/test/showcase-external-autoconnect.dogfood.test.ts	"No check family names the given paths in its own source" — no path-scoped gate family; 25 repo-wide families left to CI

Nothing skipped, baselined or ratcheted by this change. Per the dispatch instruction the full lint.yml farm was not run locally — CI runs it once.

Changeset

Comment-only, no publishable change ⇒ skip-changeset label rather than an empty changeset.

Scope held

• Only packages/qa/dogfood/test/showcase-external-autoconnect.dogfood.test.ts is changed.
• ⛔ No posture-aware fixture; packages/verify/src/harness.ts posture logic untouched.
• ⛔ No assertion added to the single-tenant boot.
• ⛔ Not skipped — the autoconnect half is genuine coverage.
• ⛔ fix(objectql): withhold the org-scope predicate from federated objects (#7738) #7833's pin is described as seam/unit only, never as end-to-end proof.
• packages/rest/**, packages/runtime/**, packages/mcp/**, docs/qa/platform-checklist/**, content/docs/releases/** — untouched.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 12, 2026 4:21am

[github-actions]

📓 Docs Drift Check

No hand-written docs reference the 0 changed package(s). ✅