@substrat-run/contract-tests 0.5.0 → 0.7.0

package/dist/scope-host-suite.js

@@ -1,5 +1,5 @@
 import { describe, it, expect, beforeAll, afterAll } from 'vitest';
-import { moduleManifest, platformActorId, principalId, scopeId, tenantId, } from '@substrat-run/contracts';
+import { moduleManifest, orgId, platformActorId, principalId, scopeId, tenantId, } from '@substrat-run/contracts';
 import { ulid } from '@substrat-run/kernel';
 import { billedMod, contractTestBareOps, contractTestInitialModules, gateModManifest, lateMod, testModManifest, victimModManifest, } from './modules.js';
 /**
@@ -35,12 +35,19 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
             for (const reg of contractTestInitialModules) {
                 host.registerModule(reg);
             }
+            // The connector seam's out-of-band half (K-22 §4.2). Host code, not module
+            // code: it holds platform authority, which is exactly what a module must
+            // never have. Idempotent because delivery is at-least-once.
+            host.registerExecutor('member-adder', 'member.add-requested', async (admin, event) => {
+                const p = event.payload;
+                await admin.addMember(staff, p.tenantId, p.principal, p.orgId);
+            });
             // A scope requires an existing active tenant (§4.1) — create then provision.
             await host.admin.createTenant(staff, { id: t1, slug: 'tenant-one', name: 'Tenant One' });
             await host.admin.createTenant(staff, { id: t2, slug: 'tenant-two', name: 'Tenant Two' });
             // Entitlements are default-deny (§4.3): t1 invokes these modules' operations,
             // so it must hold their SKU flags. (t2 only exercises bare, ungated ops.)
-            for (const key of ['testmod', 'flow', 'guarded', 'victim', 'late']) {
+            for (const key of ['testmod', 'flow', 'guarded', 'victim', 'late', 'connector']) {
                 await host.admin.grantEntitlement(staff, t1, key);
             }
             await host.provisionScope(staff, { tenantId: t1, scopeId: s1, jurisdiction: 'eu' });
@@ -133,6 +140,317 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
             const journal = await stub.invoke('testmod/read-journal');
             expect(journal).toContainEqual({ module_id: '@test/late', version: '0001-init' });
         });
+        // -- the connector seam (K-22 §4.2) --------------------------------------
+        // A module asks, inside its transaction, for an effect it cannot perform:
+        // membership is tenant-wide and lives in the directory, outside this scope's
+        // serialization domain. A privileged executor effects it through HostAdmin.
+        it('effects a module\'s request through an executor, and correlates the trail', async () => {
+            const org = orgId.parse(ulid());
+            const joiner = principalId.parse(ulid());
+            await host.admin.createOrg(staff, { id: org, tenantId: t1, slug: 'seam', name: 'Seam' });
+            const stub = await host.getScope(alice, t1, s1);
+            await stub.invoke('connector/request-member', { principal: joiner, orgId: org });
+            // Prompt dispatch: effected by the time the request returns, not on a timer.
+            const members = await host.admin.listMembers(staff, t1, org);
+            expect(members.map((m) => m.principal)).toEqual([joiner]);
+            // The two halves join. The executor's admin row carries the id of the event
+            // that caused it, which is what stops the split trail being unreadable —
+            // control-plane.md §3 named that as the main cost of this pattern.
+            const added = (await host.admin.auditLog(staff, { tenantId: t1 })).find((e) => e.action === 'addMember' && JSON.stringify(e.after).includes(joiner));
+            expect(added?.causedBy).toEqual(expect.any(String));
+            // A staff member acting directly caused nothing but themselves.
+            const orgRow = (await host.admin.auditLog(staff, { tenantId: t1 })).find((e) => e.action === 'createOrg');
+            expect(orgRow?.causedBy).toBeNull();
+        });
+        it('effects nothing when the emitting transaction rolls back', async () => {
+            // The property the connector is chosen FOR. `ctx.emit` commits with the
+            // domain write, so a rollback leaves no event and nothing to effect. An
+            // in-scope cross-DO write could not offer this: it could land in the
+            // directory and then be orphaned by the scope's rollback.
+            const org = orgId.parse(ulid());
+            const ghost = principalId.parse(ulid());
+            await host.admin.createOrg(staff, { id: org, tenantId: t1, slug: 'ghost', name: 'Ghost' });
+            const stub = await host.getScope(alice, t1, s1);
+            await expect(stub.invoke('connector/request-and-throw', { principal: ghost, orgId: org })).rejects.toThrow(/deliberate failure/);
+            expect(await host.admin.listMembers(staff, t1, org)).toEqual([]);
+        });
+        it('delivers each event to an executor exactly once', async () => {
+            // At-least-once with a journal, so a second dispatch pass must not re-effect.
+            // Membership is idempotent anyway; the audit trail is what would show a
+            // double-run, and it must not.
+            const org = orgId.parse(ulid());
+            const once = principalId.parse(ulid());
+            await host.admin.createOrg(staff, { id: org, tenantId: t1, slug: 'once', name: 'Once' });
+            const stub = await host.getScope(alice, t1, s1);
+            await stub.invoke('connector/request-member', { principal: once, orgId: org });
+            // Another operation on the same scope drains the outbox again.
+            await stub.invoke('connector/requests');
+            const rows = (await host.admin.auditLog(staff, { tenantId: t1 })).filter((e) => e.action === 'addMember' && JSON.stringify(e.after).includes(once));
+            expect(rows).toHaveLength(1);
+        });
+        // -- vertical + version registry (#31) -----------------------------------
+        // A scope binds to a VERSION, so dev/staging/prod are the same vertical pinned
+        // differently. The invariant that earns the registry its keep is that a push
+        // is not a deploy.
+        it('publishes a version as pending, and refuses to bind it until admitted', async () => {
+            const versionId = ulid();
+            await host.admin.registerVertical(staff, {
+                slug: 'callout',
+                name: 'Callout',
+                source: 'builtin',
+            });
+            await host.admin.publishVersion(staff, {
+                id: versionId,
+                verticalSlug: 'callout',
+                version: '1.0.0',
+                manifestDigest: 'm1',
+                permissionDigest: 'p1',
+                migrationDigest: 'g1',
+                deploymentRef: null,
+            });
+            const [published] = await host.admin.listVersions(staff, 'callout');
+            expect(published?.admission).toBe('pending');
+            // The refusal the registry exists for. Without it "a push lands pending" is
+            // a convention, and D-30's lockstep-upgrade argument is that conventions are
+            // what we cannot afford here.
+            await expect(host.admin.bindScopeVersion(staff, t1, s1, versionId)).rejects.toThrow(/pending, not admitted/);
+            await host.admin.admitVersion(staff, versionId);
+            await host.admin.bindScopeVersion(staff, t1, s1, versionId);
+            const scope = await host.admin.getScopeRecord(staff, t1, s1);
+            expect(scope?.verticalVersionId).toBe(versionId);
+            // The slug is denormalized alongside, so the console and the audit target
+            // keep reading a label that survives the version being superseded.
+            expect(scope?.vertical).toBe('callout');
+        });
+        it('refuses to bind a rejected version, and rejection is terminal', async () => {
+            const versionId = ulid();
+            await host.admin.publishVersion(staff, {
+                id: versionId,
+                verticalSlug: 'callout',
+                version: '1.1.0-bad',
+                manifestDigest: 'm2',
+                permissionDigest: 'p2',
+                migrationDigest: 'g2',
+                deploymentRef: null,
+            });
+            await host.admin.rejectVersion(staff, versionId, 'permission diff widened a role');
+            await expect(host.admin.bindScopeVersion(staff, t1, s1, versionId)).rejects.toThrow(/rejected, not admitted/);
+            // Terminal: a rejected version is not resurrected, a new one is published.
+            await expect(host.admin.admitVersion(staff, versionId)).rejects.toThrow(/was rejected/);
+            const rejected = (await host.admin.listVersions(staff, 'callout')).find((v) => v.id === versionId);
+            expect(rejected?.admissionNote).toContain('widened a role');
+        });
+        it('carries the digests promotion compares', async () => {
+            // "Has the permission surface changed between what is in prod and what I am
+            // promoting?" is a string comparison here. Today it is a person remembering
+            // to look, and a checkpoint that can be skipped is not a checkpoint.
+            const versions = await host.admin.listVersions(staff, 'callout');
+            for (const v of versions) {
+                expect(v.manifestDigest).toEqual(expect.any(String));
+                expect(v.permissionDigest).toEqual(expect.any(String));
+                expect(v.migrationDigest).toEqual(expect.any(String));
+            }
+        });
+        it('refuses a version for a vertical nobody registered', async () => {
+            await expect(host.admin.publishVersion(staff, {
+                id: ulid(),
+                verticalSlug: 'ghost',
+                version: '1.0.0',
+                manifestDigest: 'm',
+                permissionDigest: 'p',
+                migrationDigest: 'g',
+                deploymentRef: null,
+            })).rejects.toThrow(/unknown vertical/);
+        });
+        // -- channels and promotion-time checkpoints (#31 step 2) ----------------
+        // Promotion is the moment a change reaches anyone, so it is where §4's two
+        // human checkpoints belong. Today they are a merge-time convention: CI renders
+        // the diffs and a human is expected to look, but nothing ties that looking to
+        // the moment of exposure.
+        const publish = async (version, digests) => {
+            const id = ulid();
+            await host.admin.publishVersion(staff, {
+                id,
+                verticalSlug: 'callout',
+                version,
+                manifestDigest: `man-${version}`,
+                permissionDigest: digests.perm,
+                migrationDigest: digests.mig,
+                deploymentRef: null,
+            });
+            await host.admin.admitVersion(staff, id);
+            return id;
+        };
+        it('promotes a first version with nothing to acknowledge', async () => {
+            // The gate is about CHANGE, not existence. A first promotion has no
+            // predecessor to diff against, so demanding an acknowledgement would be
+            // ceremony rather than review.
+            const v1 = await publish('2.0.0', { perm: 'pA', mig: 'gA' });
+            await host.admin.promoteVersion(staff, 'callout', 'prod', v1);
+            const channels = await host.admin.listChannels(staff, 'callout');
+            expect(channels.find((c) => c.channel === 'prod')?.versionId).toBe(v1);
+        });
+        it('refuses a promotion that changes permissions until it is acknowledged', async () => {
+            const v2 = await publish('2.1.0', { perm: 'pB', mig: 'gA' }); // permissions moved
+            await expect(host.admin.promoteVersion(staff, 'callout', 'prod', v2)).rejects.toThrow(/changes the permission surface/);
+            // Still pointing at the old one — a refused promotion changes nothing.
+            const before = await host.admin.listChannels(staff, 'callout');
+            expect(before.find((c) => c.channel === 'prod')?.versionId).not.toBe(v2);
+            await host.admin.promoteVersion(staff, 'callout', 'prod', v2, { permissionChange: true });
+            const after = await host.admin.listChannels(staff, 'callout');
+            expect(after.find((c) => c.channel === 'prod')?.versionId).toBe(v2);
+        });
+        it('refuses a promotion that changes migrations until it is acknowledged', async () => {
+            const v3 = await publish('2.2.0', { perm: 'pB', mig: 'gB' }); // migrations moved
+            await expect(host.admin.promoteVersion(staff, 'callout', 'prod', v3)).rejects.toThrow(/changes migrations/);
+            await host.admin.promoteVersion(staff, 'callout', 'prod', v3, { migrationChange: true });
+            expect((await host.admin.listChannels(staff, 'callout')).find((c) => c.channel === 'prod')
+                ?.versionId).toBe(v3);
+        });
+        it('records the acknowledgement, so review is evidence rather than a claim', async () => {
+            const promotions = (await host.admin.auditLog(staff, {})).filter((e) => e.action === 'promoteVersion');
+            const acknowledged = promotions.filter((e) => JSON.stringify(e.after).includes('"permissionChange":true'));
+            // D-32's compliance product has to produce evidence that a control operated.
+            // "Someone reviewed the permission change" is exactly such a control, and
+            // this row is what makes it checkable after the fact.
+            expect(acknowledged.length).toBeGreaterThan(0);
+            expect(acknowledged[0].actor).toBe(staff);
+        });
+        it('promotes per channel — dev moving does not move prod', async () => {
+            // The whole point of channels: the same vertical at different versions.
+            const preview = await publish('2.3.0-preview', { perm: 'pC', mig: 'gC' });
+            const prodBefore = (await host.admin.listChannels(staff, 'callout')).find((c) => c.channel === 'prod')?.versionId;
+            await host.admin.promoteVersion(staff, 'callout', 'dev', preview);
+            const channels = await host.admin.listChannels(staff, 'callout');
+            expect(channels.find((c) => c.channel === 'dev')?.versionId).toBe(preview);
+            expect(channels.find((c) => c.channel === 'prod')?.versionId).toBe(prodBefore);
+        });
+        it('refuses to promote a version that was never admitted', async () => {
+            const pending = ulid();
+            await host.admin.publishVersion(staff, {
+                id: pending,
+                verticalSlug: 'callout',
+                version: '9.9.9',
+                manifestDigest: 'm',
+                permissionDigest: 'p',
+                migrationDigest: 'g',
+                deploymentRef: null,
+            });
+            await expect(host.admin.promoteVersion(staff, 'callout', 'dev', pending)).rejects.toThrow(/pending, not admitted/);
+        });
+        // -- the hostname map (K-26) ---------------------------------------------
+        // §4.2 provisions a scope; this is what finally gives it a URL. The router
+        // resolves against these rows before dispatching to a vertical's worker.
+        it('binds a hostname as pending, and resolves nothing until it is active', async () => {
+            await host.admin.bindHostname(staff, {
+                hostname: 'acme.example.com',
+                tenantId: t1,
+                scopeId: s1,
+                surface: 'app',
+                region: null,
+                canonical: true,
+            });
+            // A custom domain is DNS validation and cert issuance, not a string somebody
+            // sets — so it does not serve until those finish.
+            expect(await host.admin.resolveHostname('acme.example.com')).toBeUndefined();
+            await host.admin.setHostnameStatus(staff, 'acme.example.com', 'verifying');
+            expect(await host.admin.resolveHostname('acme.example.com')).toBeUndefined();
+            await host.admin.setHostnameStatus(staff, 'acme.example.com', 'active');
+            expect(await host.admin.resolveHostname('acme.example.com')).toMatchObject({
+                tenantId: t1,
+                scopeId: s1,
+                surface: 'app',
+            });
+        });
+        it('routes two surfaces of ONE scope to different hostnames', async () => {
+            // The reason §5.5's one-hostname-per-scope was not enough: the shop fronts a
+            // storefront and a back office from the same data, and RallyPoint a player
+            // app and a manager console.
+            for (const [hostname, surface] of [
+                ['shop.example.com', 'storefront'],
+                ['admin.shop.example.com', 'back-office'],
+            ]) {
+                await host.admin.bindHostname(staff, {
+                    hostname: hostname,
+                    tenantId: t1,
+                    scopeId: s1,
+                    surface: surface,
+                    region: null,
+                    canonical: true,
+                });
+                await host.admin.setHostnameStatus(staff, hostname, 'active');
+            }
+            expect((await host.admin.resolveHostname('shop.example.com'))?.surface).toBe('storefront');
+            expect((await host.admin.resolveHostname('admin.shop.example.com'))?.surface).toBe('back-office');
+        });
+        it('keeps exactly one canonical hostname per surface', async () => {
+            // "Which one do certs and redirects use" has to have one answer, so a new
+            // canonical demotes the old rather than producing two.
+            await host.admin.bindHostname(staff, {
+                hostname: 'alias.example.com',
+                tenantId: t1,
+                scopeId: s1,
+                surface: 'app',
+                region: null,
+                canonical: true,
+            });
+            const forApp = (await host.admin.listHostnames(staff, { scopeId: s1 })).filter((h) => h.surface === 'app');
+            expect(forApp.filter((h) => h.canonical).map((h) => h.hostname)).toEqual([
+                'alias.example.com',
+            ]);
+            // The demoted one is still bound — an alias, not a deletion.
+            expect(forApp.map((h) => h.hostname)).toContain('acme.example.com');
+        });
+        it('treats hostname case as insignificant, because DNS does', async () => {
+            // Otherwise two scopes could each hold "the same" name and a request would
+            // resolve to whichever casing it arrived in.
+            await host.admin.bindHostname(staff, {
+                hostname: 'MiXeD.Example.COM',
+                tenantId: t1,
+                scopeId: s1,
+                surface: 'app',
+                region: null,
+                canonical: false,
+            });
+            await host.admin.setHostnameStatus(staff, 'mixed.EXAMPLE.com', 'active');
+            expect((await host.admin.resolveHostname('MIXED.example.com'))?.scopeId).toBe(s1);
+            expect((await host.admin.listHostnames(staff, { scopeId: s1 })).map((h) => h.hostname)).toContain('mixed.example.com');
+        });
+        it('refuses to move a hostname to another scope', async () => {
+            // A hostname routes to exactly one place. Silently rebinding would move
+            // another tenant's traffic.
+            await expect(host.admin.bindHostname(staff, {
+                hostname: 'acme.example.com',
+                tenantId: t2,
+                scopeId: s2,
+                surface: 'app',
+                region: null,
+                canonical: false,
+            })).rejects.toThrow(/already bound to another scope/);
+        });
+        it('carries the region, which is what Regional Services is set from', async () => {
+            // Residency is per hostname, which is why it lives here rather than in a
+            // router deployed per jurisdiction (K-26).
+            await host.admin.bindHostname(staff, {
+                hostname: 'eu.example.com',
+                tenantId: t1,
+                scopeId: s1,
+                surface: 'app',
+                region: 'eu',
+                canonical: false,
+            });
+            await host.admin.setHostnameStatus(staff, 'eu.example.com', 'active');
+            expect((await host.admin.resolveHostname('eu.example.com'))?.region).toBe('eu');
+        });
+        it('records a failed hostname with the reason, rather than losing it', async () => {
+            await host.admin.setHostnameStatus(staff, 'eu.example.com', 'failed', 'DNS validation timed out');
+            const row = (await host.admin.listHostnames(staff, { scopeId: s1 })).find((h) => h.hostname === 'eu.example.com');
+            expect(row?.status).toBe('failed');
+            expect(row?.statusNote).toContain('DNS validation');
+            // And it stops serving — "broken" and "not yet working" are different states,
+            // but neither of them routes traffic.
+            expect(await host.admin.resolveHostname('eu.example.com')).toBeUndefined();
+        });
         it('rejects duplicate module registration', () => {
             expect(() => host.registerModule({ manifest: testModManifest })).toThrow(/already registered/);
         });
@@ -228,14 +546,14 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
         it('creates a tenant record, idempotently; only real creates are audited', async () => {
             await host.admin.createTenant(staff, { id: t3, slug: 'acme-co', name: 'Acme Co' });
             await host.admin.createTenant(staff, { id: t3, slug: 'acme-co', name: 'Acme Co' }); // no-op
-            expect(await host.admin.getTenant(t3)).toMatchObject({
+            expect(await host.admin.getTenant(staff, t3)).toMatchObject({
                 id: t3,
                 slug: 'acme-co',
                 name: 'Acme Co',
                 status: 'active',
             });
-            expect((await host.admin.listTenants()).filter((x) => x.id === t3)).toHaveLength(1);
-            const creates = (await host.admin.auditLog({ tenantId: t3 })).filter((r) => r.action === 'createTenant');
+            expect((await host.admin.listTenants(staff)).filter((x) => x.id === t3)).toHaveLength(1);
+            const creates = (await host.admin.auditLog(staff, { tenantId: t3 })).filter((r) => r.action === 'createTenant');
             expect(creates).toHaveLength(1); // the idempotent no-op left no row
             expect(creates[0].actor).toBe(staff);
         });
@@ -248,7 +566,7 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
             await expect(host.getScope(alice, t3, s3)).resolves.toBeDefined();
         });
         it('records setTenantStatus with before/after status', async () => {
-            const transitions = (await host.admin.auditLog({ tenantId: t3 })).filter((r) => r.action === 'setTenantStatus');
+            const transitions = (await host.admin.auditLog(staff, { tenantId: t3 })).filter((r) => r.action === 'setTenantStatus');
             expect(transitions.length).toBeGreaterThanOrEqual(2);
             const suspend = transitions.find((r) => r.after.status === 'suspended');
             expect(suspend.before.status).toBe('active');
@@ -274,7 +592,7 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
             await expect(host.getScope(alice, t3, s3)).rejects.toThrow(/scope not active/);
             await host.admin.unarchiveScope(staff, t3, s3);
             await expect(host.getScope(alice, t3, s3)).resolves.toBeDefined();
-            const transitions = (await host.admin.auditLog({ tenantId: t3 })).filter((r) => r.action === 'archiveScope' || r.action === 'unarchiveScope');
+            const transitions = (await host.admin.auditLog(staff, { tenantId: t3 })).filter((r) => r.action === 'archiveScope' || r.action === 'unarchiveScope');
             expect(transitions.map((r) => r.action)).toEqual(expect.arrayContaining(['archiveScope', 'unarchiveScope']));
             for (const r of transitions) {
                 expect(r.scopeId).toBe(s3);
@@ -299,22 +617,22 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
             // Granting the flag loads the module for this tenant.
             await host.admin.grantEntitlement(staff, t4, 'billed');
             await expect(stub.invoke('billed/act')).resolves.toBe('ran');
-            expect(await host.admin.listEntitlements(t4)).toContain('billed');
+            expect(await host.admin.listEntitlements(staff, t4)).toContain('billed');
             // Revoking it takes the operation away again — as if never registered.
             await host.admin.revokeEntitlement(staff, t4, 'billed');
             await expect(stub.invoke('billed/act')).rejects.toThrow(/not entitled/);
-            expect(await host.admin.listEntitlements(t4)).not.toContain('billed');
+            expect(await host.admin.listEntitlements(staff, t4)).not.toContain('billed');
         });
         it('audits grant/revoke idempotently and records the SKU flag', async () => {
             // Re-grant twice: only the first is a real change, so only one row.
             await host.admin.grantEntitlement(staff, t4, 'audited-sku');
             await host.admin.grantEntitlement(staff, t4, 'audited-sku');
-            const grants = (await host.admin.auditLog({ tenantId: t4 })).filter((r) => r.action === 'grantEntitlement' &&
+            const grants = (await host.admin.auditLog(staff, { tenantId: t4 })).filter((r) => r.action === 'grantEntitlement' &&
                 r.after.entitlementKey === 'audited-sku');
             expect(grants).toHaveLength(1);
             expect(grants[0].actor).toBe(staff);
             await host.admin.revokeEntitlement(staff, t4, 'audited-sku');
-            const revokes = (await host.admin.auditLog({ tenantId: t4 })).filter((r) => r.action === 'revokeEntitlement');
+            const revokes = (await host.admin.auditLog(staff, { tenantId: t4 })).filter((r) => r.action === 'revokeEntitlement');
             expect(revokes.length).toBeGreaterThanOrEqual(1);
             expect(revokes[revokes.length - 1].before.entitlementKey).toBe('audited-sku');
         });
@@ -332,7 +650,7 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
             await host.admin.createTenant(staff, { id: t5, slug: 'directory-co', name: 'Directory Co' });
             const bare = scopeId.parse(ulid());
             await host.provisionScope(staff, { tenantId: t5, scopeId: bare });
-            const rec = await host.admin.getScopeRecord(t5, bare);
+            const rec = await host.admin.getScopeRecord(staff, t5, bare);
             // A ULID lowercases into a valid slug, so the placeholder is unique by
             // construction — every pre-existing caller provisions without naming.
             expect(rec).toMatchObject({
@@ -358,7 +676,7 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
                 vertical: 'housing',
                 jurisdiction: 'eu',
             });
-            expect(await host.admin.getScopeRecord(t5, named)).toMatchObject({
+            expect(await host.admin.getScopeRecord(staff, t5, named)).toMatchObject({
                 slug: 'brf-vasastan',
                 kind: 'brf',
                 name: 'Brf Vasastan',
@@ -371,7 +689,7 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
             await expect(host.provisionScope(staff, { tenantId: t5, scopeId: other, slug: 'brf-vasastan' })).rejects.toThrow(/already taken/);
             // Idempotency is keyed on the scope id, so re-provisioning the SAME scope
             // must not collide with its own slug.
-            const named = (await host.admin.listScopes({ tenantId: t5 })).find((s) => s.slug === 'brf-vasastan');
+            const named = (await host.admin.listScopes(staff, { tenantId: t5 })).find((s) => s.slug === 'brf-vasastan');
             await expect(host.provisionScope(staff, { tenantId: t5, scopeId: named.id, slug: 'brf-vasastan' })).resolves.toBeUndefined();
         });
         it('scopes slug uniqueness to the tenant, not the fleet (§3.2)', async () => {
@@ -390,108 +708,108 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
             })).rejects.toThrow(/already taken/);
         });
         it('enumerates the scopes under a tenant, and filters by status (§4.5)', async () => {
-            const all = await host.admin.listScopes({ tenantId: t5 });
+            const all = await host.admin.listScopes(staff, { tenantId: t5 });
             expect(all.length).toBeGreaterThanOrEqual(2);
             expect(all.every((s) => s.tenantId === t5)).toBe(true);
             // Ordered by scope id — ULID order is chronological.
             expect(all.map((s) => s.id)).toEqual([...all.map((s) => s.id)].sort());
             const target = all[0];
             await host.admin.suspendScope(staff, t5, target.id);
-            const suspended = await host.admin.listScopes({ tenantId: t5, status: 'suspended' });
+            const suspended = await host.admin.listScopes(staff, { tenantId: t5, status: 'suspended' });
             expect(suspended.map((s) => s.id)).toEqual([target.id]);
             // Several statuses at once — the console's All / Suspended / Archived tabs.
-            const both = await host.admin.listScopes({
+            const both = await host.admin.listScopes(staff, {
                 tenantId: t5,
                 status: ['active', 'suspended'],
             });
             expect(both.length).toBe(all.length);
             // An empty status list means "no status is acceptable" — it must match
             // nothing, never degenerate into an unfiltered read of the whole fleet.
-            expect(await host.admin.listScopes({ tenantId: t5, status: [] })).toEqual([]);
+            expect(await host.admin.listScopes(staff, { tenantId: t5, status: [] })).toEqual([]);
             await host.admin.unsuspendScope(staff, t5, target.id);
         });
         it('lists the whole fleet across tenants when unfiltered (§4.5)', async () => {
-            const fleet = await host.admin.listScopes();
+            const fleet = await host.admin.listScopes(staff);
             const tenants = new Set(fleet.map((s) => s.tenantId));
             expect(tenants.size).toBeGreaterThan(1);
-            expect(fleet.length).toBeGreaterThanOrEqual((await host.admin.listScopes({ tenantId: t5 })).length);
+            expect(fleet.length).toBeGreaterThanOrEqual((await host.admin.listScopes(staff, { tenantId: t5 })).length);
         });
         it('filters the fleet by vertical (§4.5)', async () => {
-            const housing = await host.admin.listScopes({ vertical: 'housing' });
+            const housing = await host.admin.listScopes(staff, { vertical: 'housing' });
             expect(housing.length).toBeGreaterThanOrEqual(1);
             expect(housing.every((s) => s.vertical === 'housing')).toBe(true);
         });
         it('fails closed reading a scope record on a mismatched pair (K-3)', async () => {
-            const [any] = await host.admin.listScopes({ tenantId: t5 });
+            const [any] = await host.admin.listScopes(staff, { tenantId: t5 });
             // The scope exists — but not under t1. It must read as absent, never as
             // itself: the same rule getScope applies when minting a stub.
-            expect(await host.admin.getScopeRecord(t1, any.id)).toBeUndefined();
-            expect(await host.admin.getScopeRecord(t5, scopeId.parse(ulid()))).toBeUndefined();
+            expect(await host.admin.getScopeRecord(staff, t1, any.id)).toBeUndefined();
+            expect(await host.admin.getScopeRecord(staff, t5, scopeId.parse(ulid()))).toBeUndefined();
         });
         it('projects the applied-migration count into the directory (§5.4)', async () => {
             // schema_version shipped as a column and was written by nothing — always
             // '0'. Registered modules carry migrations, so a provisioned scope must
             // report a count, which is what makes "which scopes are behind" answerable
             // from the index without fanning out.
-            const [any] = await host.admin.listScopes({ tenantId: t5 });
+            const [any] = await host.admin.listScopes(staff, { tenantId: t5 });
             expect(Number(any.schemaVersion)).toBeGreaterThan(0);
         });
         it('stamps the audit target with the scope vertical for lifecycle actions (§4.4)', async () => {
             // `vertical` was plumbed end-to-end and passed by no call site — every row
             // was null. A lifecycle action on a scope that names one must carry it.
-            const named = (await host.admin.listScopes({ tenantId: t5 })).find((s) => s.vertical === 'housing');
+            const named = (await host.admin.listScopes(staff, { tenantId: t5 })).find((s) => s.vertical === 'housing');
             await host.admin.suspendScope(staff, t5, named.id);
-            const rows = (await host.admin.auditLog({ tenantId: t5, scopeId: named.id })).filter((r) => r.action === 'suspendScope');
+            const rows = (await host.admin.auditLog(staff, { tenantId: t5, scopeId: named.id })).filter((r) => r.action === 'suspendScope');
             expect(rows).toHaveLength(1);
             expect(rows[0].vertical).toBe('housing');
             await host.admin.unsuspendScope(staff, t5, named.id);
         });
         // -- the admin audit log, read side (control-plane.md §4.4/§4.5) ----------
         it('narrows the audit log by scope, actor and action (§4.5)', async () => {
-            const [any] = await host.admin.listScopes({ tenantId: t5 });
-            const byScope = await host.admin.auditLog({ tenantId: t5, scopeId: any.id });
+            const [any] = await host.admin.listScopes(staff, { tenantId: t5 });
+            const byScope = await host.admin.auditLog(staff, { tenantId: t5, scopeId: any.id });
             expect(byScope.length).toBeGreaterThan(0);
             expect(byScope.every((r) => r.scopeId === any.id)).toBe(true);
-            const byActor = await host.admin.auditLog({ tenantId: t5, actor: staff });
+            const byActor = await host.admin.auditLog(staff, { tenantId: t5, actor: staff });
             expect(byActor.length).toBeGreaterThan(0);
             expect(byActor.every((r) => r.actor === staff)).toBe(true);
             // A different actor shares the log and must not see these rows.
-            expect(await host.admin.auditLog({ actor: platformActorId.parse(ulid()) })).toEqual([]);
-            const lifecycle = await host.admin.auditLog({
+            expect(await host.admin.auditLog(staff, { actor: platformActorId.parse(ulid()) })).toEqual([]);
+            const lifecycle = await host.admin.auditLog(staff, {
                 tenantId: t5,
                 action: ['suspendScope', 'unsuspendScope'],
             });
             expect(lifecycle.length).toBeGreaterThan(0);
             expect(lifecycle.every((r) => r.action === 'suspendScope' || r.action === 'unsuspendScope')).toBe(true);
             // Single action, not an array — both spellings are accepted.
-            const provisions = await host.admin.auditLog({ tenantId: t5, action: 'provisionScope' });
+            const provisions = await host.admin.auditLog(staff, { tenantId: t5, action: 'provisionScope' });
             expect(provisions.every((r) => r.action === 'provisionScope')).toBe(true);
             // Empty action list matches nothing rather than everything.
-            expect(await host.admin.auditLog({ tenantId: t5, action: [] })).toEqual([]);
+            expect(await host.admin.auditLog(staff, { tenantId: t5, action: [] })).toEqual([]);
         });
         it('orders oldest-first by default and newest-first on request (§4.5)', async () => {
-            const asc = await host.admin.auditLog({ tenantId: t5 });
-            const desc = await host.admin.auditLog({ tenantId: t5, order: 'desc' });
+            const asc = await host.admin.auditLog(staff, { tenantId: t5 });
+            const desc = await host.admin.auditLog(staff, { tenantId: t5, order: 'desc' });
             expect(asc.length).toBe(desc.length);
             expect(asc.length).toBeGreaterThan(1);
             // The default preserves the ordering the log shipped with; the console reads desc.
             expect(desc.map((r) => r.id)).toEqual([...asc.map((r) => r.id)].reverse());
         });
         it('limits and pages the audit log by cursor (§4.5)', async () => {
-            const all = await host.admin.auditLog({ tenantId: t5 });
+            const all = await host.admin.auditLog(staff, { tenantId: t5 });
             expect(all.length).toBeGreaterThan(2);
-            const first = await host.admin.auditLog({ tenantId: t5, limit: 2 });
+            const first = await host.admin.auditLog(staff, { tenantId: t5, limit: 2 });
             expect(first.map((r) => r.id)).toEqual(all.slice(0, 2).map((r) => r.id));
             // The cursor IS the last entry's id — ULID order is chronological, so no
             // separate encoding is needed. Paging forward resumes strictly after it.
-            const next = await host.admin.auditLog({
+            const next = await host.admin.auditLog(staff, {
                 tenantId: t5,
                 limit: 2,
                 cursor: first[first.length - 1].id,
             });
             expect(next.map((r) => r.id)).toEqual(all.slice(2, 4).map((r) => r.id));
             // Descending pages backward from the cursor.
-            const descPage = await host.admin.auditLog({
+            const descPage = await host.admin.auditLog(staff, {
                 tenantId: t5,
                 order: 'desc',
                 limit: 2,
@@ -503,13 +821,13 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
                 .reverse());
         });
         it('bounds the audit log by time (§4.5)', async () => {
-            const all = await host.admin.auditLog({ tenantId: t5 });
+            const all = await host.admin.auditLog(staff, { tenantId: t5 });
             const pivot = all[1].at;
             // `since` is inclusive, `until` exclusive.
-            const since = await host.admin.auditLog({ tenantId: t5, since: pivot });
+            const since = await host.admin.auditLog(staff, { tenantId: t5, since: pivot });
             expect(since.every((r) => r.at >= pivot)).toBe(true);
             expect(since.some((r) => r.id === all[1].id)).toBe(true);
-            const until = await host.admin.auditLog({ tenantId: t5, until: pivot });
+            const until = await host.admin.auditLog(staff, { tenantId: t5, until: pivot });
             expect(until.every((r) => r.at < pivot)).toBe(true);
         });
     });