fix(plugin-auth): report at error when a single-posture deployment holds more than one organization (#17010) (#17460)

* fix(plugin-auth): report at error when a `single`-posture deployment holds more than one organization

ADR-0131 §1.2(3) states that "many organizations under `single`" is today a
refused boot. It is not: `resolveDefaultOrgId` answers the bootstrap org, else
the sole org when exactly one exists, else `null` — silently — and the harm
surfaces far away as a platform admin reading zero rows and system writes
refused `ambiguous-organization`.

Take a `count(sys_organization)` census on the seam that was silent and that
already reads the object, and report at `error` when a non-walled deployment
holds more than one, naming the posture, the count and both remedies. Boot
PROCEEDS — this only reports; the refuse-vs-report fork stays with the
maintainer. The per-write refusal (#8844) is untouched.

Reached at boot: AuthPlugin runs `backfillMemberships` from `kernel:ready`
with `resolveTargetOrg: () => tenancy.defaultOrgId()` under a membership
policy that defaults to `auto`. Cost is one `count()` per process, downstream
of the walled early return and of the memoized resolution.

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

* refactor(plugin-auth): keep the organization census module-private — one in-file caller, no new published symbol

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

* docs(changeset): single-posture organization census

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

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: claude[bot]

.changeset/single-posture-organization-census.md

@@ -0,0 +1,13 @@
+---
+"@objectstack/plugin-auth": minor
+---
+
+fix(plugin-auth): a `single`-posture deployment holding more than one organization is reported at `error` instead of booting silently (#17010)
+
+ADR-0131 §1.2(3) states that its precondition — many organizations with the organization wall inert — 「is today a refused boot」. It is not. A deployment that never REQUESTS a walled posture and simply HOLDS more than one `sys_organization` row under `single` boots, serves, and says nothing: `resolveDefaultOrgId` answers the bootstrap org, else the sole org when exactly one exists, else `null` — silently. The harm then surfaces far away and looks like an unrelated data outage: users reconciled from then on are bound to no organization, a platform admin reads zero rows of every organization-stamped object while analytics still counts them, and system-context writes are refused `ambiguous-organization` by the per-write guard.
+
+The tenancy service now takes a `count(sys_organization)` census on that same seam and reports at `error` when a non-walled deployment holds more than one, naming the posture it DECLARED, the count it HOLDS, and the two ways out: declare a walled posture (`OS_TENANCY_POSTURE=group` / `isolated`, plus the `@objectstack/organizations` package that activates it), or hold one organization and model the sub-units as business units.
+
+**The boot is not refused.** This change only reports; whether the boot should instead be refused stays open for the maintainer, and nothing here has to be undone if that is the answer. The per-write `ambiguous-organization` refusal is untouched.
+
+Cost is one `count()` per process: the census sits downstream of the walled-posture early return (a `group`/`isolated` deployment pays nothing and says nothing) and downstream of the memoized resolution, and an engine that cannot answer stays silent rather than guessing. A healthy install — exactly one organization, or none bootstrapped yet — is silent by construction.

packages/plugins/plugin-auth/src/tenancy-service.test.ts

@@ -2,6 +2,7 @@
 
 import { describe, it, expect, vi } from 'vitest';
 import { createTenancyService, resolveDefaultOrgId } from './tenancy-service.js';
+import { backfillMemberships } from './reconcile-membership.js';
 
 function makeEngine(orgs: Array<{ id: string; slug?: string }>) {
   return {
@@ -294,3 +295,252 @@ describe('posture entitlement declared by the org-scoping runtime', () => {
     expect(entitle).not.toHaveBeenCalled();
   });
 });
+
+// ---------------------------------------------------------------------------
+// [#17010] The organization census — a `single`-posture deployment that HOLDS
+// more than one organization stops booting silently.
+//
+// ADR-0131 §1.2(3) calls that precondition 「a refused boot」 and it is not.
+// ⛔ Boot still PROCEEDS here (ruled 2026-09-10): this suite pins the REPORT,
+// its level, the subjects it must name — and, just as load-bearing, the
+// NEGATIVE CONTROL, because a check that fires on a healthy install is worse
+// than no check at all.
+// ---------------------------------------------------------------------------
+describe('single-posture organization census (#17010)', () => {
+  /** An engine that answers the census — `count` is what makes the reading exact. */
+  function makeCensusEngine(orgs: Array<{ id: string; slug?: string }>) {
+    return {
+      find: vi.fn(async (object: string, query: any) => {
+        if (object !== 'sys_organization') return [];
+        const where = query?.where ?? {};
+        let rows = orgs;
+        if (where.slug !== undefined) rows = rows.filter((o) => o.slug === where.slug);
+        return rows.slice(0, query?.limit ?? rows.length);
+      }),
+      count: vi.fn(async (object: string) => (object === 'sys_organization' ? orgs.length : 0)),
+      insert: vi.fn(async () => ({ id: 'ignored' })),
+    };
+  }
+
+  const makeSink = () => ({ info: vi.fn(), warn: vi.fn(), error: vi.fn() });
+
+  // Spelled here rather than imported: the census is module-private (it has one
+  // in-file caller), so this literal is the pin — rename the token and this
+  // suite says so, which is the whole point of a grep token an operator keys on.
+  const SINGLE_POSTURE_MANY_ORGANIZATIONS = 'single_posture_holds_many_organizations';
+
+  const orgs = (n: number) => Array.from({ length: n }, (_, i) => ({ id: `org_${i + 1}` }));
+
+  it('reports at ERROR, naming the posture, the COUNT and both remedies', async () => {
+    const engine = makeCensusEngine(orgs(3));
+    const logger = makeSink();
+    const t = createTenancyService({
+      requested: 'single',
+      probeIsolation: () => false,
+      getEngine: () => engine,
+      logger,
+    });
+
+    expect(await t.defaultOrgId()).toBeNull();
+
+    expect(logger.error).toHaveBeenCalledTimes(1);
+    expect(logger.warn).not.toHaveBeenCalled();
+    const [message, meta] = logger.error.mock.calls[0]!;
+    // The grep token an operator keys on.
+    expect(message).toContain(SINGLE_POSTURE_MANY_ORGANIZATIONS);
+    // ① the posture it DECLARED, ② the count it HOLDS — the two facts the card asks for.
+    expect(message).toContain("'single'");
+    expect(message).toContain('3');
+    expect(meta).toEqual({ posture: 'single', organizationCount: 3 });
+    // ③ both remedies, named: declare a walled posture, or hold one organization.
+    expect(message).toContain('OS_TENANCY_POSTURE=group');
+    expect(message).toContain('OS_TENANCY_POSTURE=isolated');
+    expect(message).toContain('HOLD ONE ORGANIZATION');
+    // ④ the consequence, including that the deployment keeps looking healthy
+    //    (AGENTS.md → "Degradation log levels": what an `error` owes its reader).
+    expect(message).toContain('KEEP LOOKING HEALTHY');
+  });
+
+  it('NEGATIVE CONTROL: exactly one organization under `single` stays SILENT', async () => {
+    const engine = makeCensusEngine([{ id: 'org_1', slug: 'default' }]);
+    const logger = makeSink();
+    const t = createTenancyService({
+      requested: 'single',
+      probeIsolation: () => false,
+      getEngine: () => engine,
+      logger,
+    });
+
+    expect(await t.defaultOrgId()).toBe('org_1');
+    expect(logger.error).not.toHaveBeenCalled();
+    expect(logger.warn).not.toHaveBeenCalled();
+  });
+
+  it('NEGATIVE CONTROL: a store with NO organization yet stays SILENT', async () => {
+    const engine = makeCensusEngine([]);
+    const logger = makeSink();
+    const t = createTenancyService({
+      requested: 'single',
+      probeIsolation: () => false,
+      getEngine: () => engine,
+      logger,
+    });
+
+    expect(await t.defaultOrgId()).toBeNull();
+    expect(logger.error).not.toHaveBeenCalled();
+    expect(logger.warn).not.toHaveBeenCalled();
+  });
+
+  it('a WALLED posture pays nothing and says nothing — the organizations are declared', async () => {
+    for (const requested of ['group', 'isolated'] as const) {
+      const engine = makeCensusEngine(orgs(3));
+      const logger = makeSink();
+      const t = createTenancyService({
+        requested,
+        probeIsolation: () => true,
+        getEngine: () => engine,
+        logger,
+      });
+
+      expect(await t.defaultOrgId(), requested).toBeNull();
+      expect(engine.count, requested).not.toHaveBeenCalled();
+      expect(logger.error, requested).not.toHaveBeenCalled();
+      expect(logger.warn, requested).not.toHaveBeenCalled();
+    }
+  });
+
+  it('COST: the census costs ONE count() per process, however often it is asked', async () => {
+    const engine = makeCensusEngine(orgs(4));
+    const logger = makeSink();
+    const t = createTenancyService({
+      requested: 'single',
+      probeIsolation: () => false,
+      getEngine: () => engine,
+      logger,
+    });
+
+    await t.defaultOrgId();
+    await t.defaultOrgId();
+    await t.defaultOrgId();
+
+    expect(engine.count).toHaveBeenCalledTimes(1);
+    expect(engine.count).toHaveBeenCalledWith('sys_organization', {}, { context: { isSystem: true } });
+    // Said ONCE, at the first degradation — not once per failed resolution.
+    expect(logger.error).toHaveBeenCalledTimes(1);
+  });
+
+  it('falls back to warn on a sink that declares no error, and never emits both', async () => {
+    const engine = makeCensusEngine(orgs(2));
+    const logger = { info: vi.fn(), warn: vi.fn() };
+    const t = createTenancyService({
+      requested: 'single',
+      probeIsolation: () => false,
+      getEngine: () => engine,
+      logger,
+    });
+
+    await t.defaultOrgId();
+    expect(logger.warn).toHaveBeenCalledTimes(1);
+    expect(logger.warn.mock.calls[0]![0]).toContain(SINGLE_POSTURE_MANY_ORGANIZATIONS);
+  });
+
+  it('an engine that cannot answer stays silent AND does not latch the census', async () => {
+    // No `count`: every reduced mock embedding. An absence of measurement is
+    // not evidence of a defect — and it must not disable the census either.
+    const countless: any = makeCensusEngine(orgs(3));
+    delete countless.count;
+    const logger = makeSink();
+    let engine: any = countless;
+    const t = createTenancyService({
+      requested: 'single',
+      probeIsolation: () => false,
+      getEngine: () => engine,
+      logger,
+    });
+
+    await t.defaultOrgId();
+    expect(logger.error).not.toHaveBeenCalled();
+    expect(logger.warn).not.toHaveBeenCalled();
+
+    // The engine becomes answerable later (the store came up after this seam
+    // was first reached): the census must still be takeable.
+    engine = makeCensusEngine(orgs(3));
+    await t.defaultOrgId();
+    expect(logger.error).toHaveBeenCalledTimes(1);
+  });
+
+  it('a throwing count, and a throwing logger, never break the resolution', async () => {
+    const engine: any = makeCensusEngine([{ id: 'org_1', slug: 'default' }]);
+    engine.count = vi.fn(async () => {
+      throw new Error('store unreachable');
+    });
+    expect(await createTenancyService({
+      requested: 'single',
+      probeIsolation: () => false,
+      getEngine: () => engine,
+      logger: makeSink(),
+    }).defaultOrgId()).toBe('org_1');
+
+    const loud = makeCensusEngine(orgs(3));
+    const thrower = {
+      warn: vi.fn(),
+      error: vi.fn(() => {
+        throw new Error('sink exploded');
+      }),
+    };
+    expect(await createTenancyService({
+      requested: 'single',
+      probeIsolation: () => false,
+      getEngine: () => loud,
+      logger: thrower,
+    }).defaultOrgId()).toBeNull();
+    expect(thrower.error).toHaveBeenCalledTimes(1);
+  });
+
+  it('a sink with no warn channel at all drops the report instead of throwing', async () => {
+    // The declared sink types both members as optional, so a host CAN inject
+    // `{ info }` alone. The narrowing proves `warn` before it claims the sink,
+    // so such a host gets nothing — quietly, from inside a diagnostic.
+    const engine = makeCensusEngine(orgs(3));
+    const infoOnly = { info: vi.fn() };
+    const t = createTenancyService({
+      requested: 'single',
+      probeIsolation: () => false,
+      getEngine: () => engine,
+      logger: infoOnly,
+    });
+
+    expect(await t.defaultOrgId()).toBeNull();
+    expect(infoOnly.info).not.toHaveBeenCalled();
+  });
+
+  // -------------------------------------------------------------------------
+  // The claim that makes this a BOOT-time reading rather than a lazy one:
+  // `AuthPlugin` runs `backfillMemberships` from its `kernel:ready` hook with
+  // `resolveTargetOrg: () => tenancy.defaultOrgId()`, under a membership policy
+  // that defaults to `auto`. Pinned against the real pass, so the day that
+  // wiring stops reaching this seam, this test says so.
+  // -------------------------------------------------------------------------
+  it('is taken AT BOOT: the kernel:ready membership backfill reaches this seam', async () => {
+    const engine = makeCensusEngine(orgs(3));
+    const logger = makeSink();
+    const tenancy = createTenancyService({
+      requested: 'single',
+      probeIsolation: () => false,
+      getEngine: () => engine,
+      logger,
+    });
+
+    const res = await backfillMemberships(engine, {
+      policy: 'auto',
+      resolveTargetOrg: () => tenancy.defaultOrgId(),
+      logger,
+    });
+
+    // The backfill itself correctly declines to guess (ADR-0093 D6) …
+    expect(res.reason).toBe('no-target-org');
+    // … and THAT is the boot moment the census is taken in.
+    expect(logger.error).toHaveBeenCalledTimes(1);
+    expect(logger.error.mock.calls[0]![0]).toContain(SINGLE_POSTURE_MANY_ORGANIZATIONS);
+  });
+});