@classytic/arc 2.28.0 → 2.31.0

package/dist/testing/index.mjs

@@ -1,7 +1,13 @@
-import { t as CRUD_OPERATIONS } from "../constants-DNre0wRg.mjs";
-import { n as createApp } from "../createApp-Du5G54TM.mjs";
-import { n as getModuleExports } from "../module-_-M7C5ES.mjs";
-import { n as preloadResourcesAsync, t as preloadResources } from "../preloadResources-DSY5HGpS.mjs";
+/*! @classytic/arc v2.31.0 | MIT | https://classytic.com */
+import { t as CRUD_OPERATIONS } from "../constants-D3Dv4LAV.mjs";
+import { g as getUserId } from "../types-Cys0ko9Z.mjs";
+import { t as BaseController } from "../BaseController-De7GqHck.mjs";
+import { t as defineResource } from "../defineResource-Bv6EtN1x.mjs";
+import { t as defineAggregation } from "../defineAggregation-DbPPS8RI.mjs";
+import { S as requireOrgRole } from "../permissions-L--QDAir.mjs";
+import { n as createApp } from "../createApp-Df89BEni.mjs";
+import { n as getModuleExports } from "../module-0pFJA6YW.mjs";
+import { n as preloadResourcesAsync, t as preloadResources } from "../preloadResources-Dz6BjzM6.mjs";
 import { runStorageContract } from "./storageContract.mjs";
 import Fastify from "fastify";
 import { afterAll, describe, expect, it, vi } from "vitest";
@@ -125,6 +131,339 @@ function expectArc(response) {
 	return assertion;
 }
 //#endregion
+//#region src/testing/mocks.ts
+/**
+* Create a mock repository for testing
+*
+* @example
+* const mockRepo = createMockRepository<Product>({
+*   getById: vi.fn().mockResolvedValue({ id: '1', name: 'Test' }),
+*   create: vi.fn().mockImplementation(data => Promise.resolve({ id: '1', ...data })),
+* });
+*
+* await mockRepo.getById('1'); // Returns mocked product
+*/
+function createMockRepository(overrides = {}) {
+	return {
+		getAll: vi.fn().mockResolvedValue({
+			method: "offset",
+			data: [],
+			total: 0,
+			page: 1,
+			limit: 20,
+			pages: 0,
+			hasNext: false,
+			hasPrev: false
+		}),
+		getById: vi.fn().mockResolvedValue(null),
+		create: vi.fn().mockImplementation((data) => Promise.resolve({
+			_id: "mock-id",
+			...data
+		})),
+		update: vi.fn().mockImplementation((_id, data) => Promise.resolve({
+			_id: "mock-id",
+			...data
+		})),
+		delete: vi.fn().mockResolvedValue({
+			success: true,
+			message: "Deleted"
+		}),
+		updateMany: vi.fn().mockResolvedValue({
+			acknowledged: true,
+			matchedCount: 0,
+			modifiedCount: 0
+		}),
+		deleteMany: vi.fn().mockResolvedValue({
+			acknowledged: true,
+			deletedCount: 0
+		}),
+		claim: vi.fn().mockResolvedValue(null),
+		claimVersion: vi.fn().mockResolvedValue(null),
+		capabilities: {
+			transactions: false,
+			nestedTransactions: false,
+			upsert: false,
+			duplicateKeyError: false,
+			distinct: false,
+			aggregate: false,
+			getOrCreate: false,
+			countAndExists: false
+		},
+		getBySlug: vi.fn().mockResolvedValue(null),
+		getDeleted: vi.fn().mockResolvedValue([]),
+		restore: vi.fn().mockResolvedValue(null),
+		getTree: vi.fn().mockResolvedValue([]),
+		getChildren: vi.fn().mockResolvedValue([]),
+		...overrides
+	};
+}
+/**
+* Create a mock user for authentication testing
+*/
+function createMockUser(overrides = {}) {
+	return {
+		_id: "mock-user-id",
+		id: "mock-user-id",
+		email: "test@example.com",
+		roles: ["user"],
+		organizationId: null,
+		...overrides
+	};
+}
+/**
+* Create a mock Fastify request
+*/
+function createMockRequest(overrides = {}) {
+	return {
+		body: {},
+		params: {},
+		query: {},
+		headers: {},
+		user: createMockUser(),
+		context: {},
+		log: {
+			info: vi.fn(),
+			warn: vi.fn(),
+			error: vi.fn(),
+			debug: vi.fn()
+		},
+		...overrides
+	};
+}
+/**
+* Create a mock Fastify reply
+*/
+function createMockReply() {
+	return {
+		code: vi.fn().mockReturnThis(),
+		send: vi.fn().mockReturnThis(),
+		header: vi.fn().mockReturnThis(),
+		headers: vi.fn().mockReturnThis(),
+		status: vi.fn().mockReturnThis(),
+		type: vi.fn().mockReturnThis(),
+		redirect: vi.fn().mockReturnThis(),
+		callNotFound: vi.fn().mockReturnThis(),
+		sent: false
+	};
+}
+/**
+* Create a mock controller for testing
+*/
+function createMockController(repository) {
+	return {
+		repository,
+		list: vi.fn(),
+		get: vi.fn(),
+		create: vi.fn(),
+		update: vi.fn(),
+		delete: vi.fn()
+	};
+}
+/**
+* Create mock data factory
+*
+* @example
+* const productFactory = createDataFactory<Product>({
+*   name: () => faker.commerce.productName(),
+*   price: () => faker.number.int({ min: 10, max: 1000 }),
+*   sku: (i) => `SKU-${i}`,
+* });
+*
+* const product = productFactory.build();
+* const products = productFactory.buildMany(10);
+*/
+function createDataFactory(template) {
+	let counter = 0;
+	return {
+		build(overrides = {}) {
+			const index = counter++;
+			const data = {};
+			for (const [key, generator] of Object.entries(template)) data[key] = generator(index);
+			return {
+				...data,
+				...overrides
+			};
+		},
+		buildMany(count, overrides = {}) {
+			return Array.from({ length: count }, () => this.build(overrides));
+		},
+		reset() {
+			counter = 0;
+		}
+	};
+}
+/**
+* Create a spy that tracks function calls
+*
+* Useful for testing side effects without full mocking
+*/
+function createSpy(_name = "spy") {
+	const calls = [];
+	const spy = vi.fn((...args) => {
+		calls.push(args);
+	});
+	spy.getCalls = () => calls;
+	spy.getLastCall = () => calls[calls.length - 1] || [];
+	return spy;
+}
+/**
+* Wait until `condition` holds — the standard way to assert on asynchronous
+* effects in arc's suites.
+*
+* **Prefer this over `await sleep(n)` + assert.** A fixed delay encodes a guess
+* about scheduling: too short and it flakes the moment the pool is busy, too
+* long and every run pays for the worst case. Polling returns as soon as the
+* effect lands, so the fast path stays fast and a loaded machine simply waits —
+* and the failure mode becomes "this never happened", which is the thing worth
+* asserting.
+*
+* Supply `label`: without it a timeout reports only its own duration, which is
+* the least useful sentence a flaky test can print.
+*
+* @example
+* await waitFor(() => runs >= 3, { label: "3 scheduler ticks" });
+*/
+async function waitFor(condition, options = {}) {
+	const { timeout = 5e3, interval = 25, label } = options;
+	const startTime = Date.now();
+	while (Date.now() - startTime < timeout) {
+		if (await condition()) return;
+		await new Promise((resolve) => setTimeout(resolve, interval));
+	}
+	throw new Error(label ? `Timed out after ${timeout}ms waiting for: ${label}` : `Timed out after ${timeout}ms waiting for a condition (pass "label" to name it)`);
+}
+/**
+* Create a test timer that can be controlled
+*/
+function createTestTimer() {
+	let time = Date.now();
+	return {
+		now: () => time,
+		advance: (ms) => {
+			time += ms;
+		},
+		set: (timestamp) => {
+			time = timestamp;
+		},
+		reset: () => {
+			time = Date.now();
+		}
+	};
+}
+//#endregion
+//#region src/testing/authorizationConformance.ts
+/**
+* Cross-surface authorization conformance (arc 2.30).
+*
+* The regression wall that keeps "partial enforcement" from ever coming back:
+* run the SAME permission through more than one arc surface and prove it enforces
+* identically. Reviews kept finding aggregation (and MCP) drifting from CRUD —
+* this makes that a one-call assertion for arc AND for host resources.
+*
+* `runAuthorizationConformance` boots a throwaway Fastify app with one resource
+* whose `list` op AND an `aggregation` share the given permission, backed by a
+* capturing mock repo (no DB). It returns, per surface, the HTTP status and the
+* exact filter arc handed the repository — so the caller asserts:
+*   - deny → both surfaces fail closed with the SAME status;
+*   - allow + `policy` → the row policy reaches BOTH the list query and the
+*     aggregation `$match`, identically.
+*
+* Runner-agnostic: it returns data, it does not assert. Pair with your test
+* framework's expectations (see `tests/core/authorization-conformance.test.ts`).
+*/
+/**
+* Boot a one-resource app gated by `permission` on both list + an aggregation,
+* hit both surfaces anonymously, and report what arc enforced on each.
+*/
+async function runAuthorizationConformance(opts) {
+	const rows = opts.rows ?? [{ _id: "1" }];
+	let listFilter;
+	let getFilter;
+	let aggFilter;
+	const repo = createMockRepository({
+		getAll: (async (params = {}) => {
+			listFilter = params.filters;
+			return {
+				method: "offset",
+				data: rows,
+				total: rows.length,
+				page: 1,
+				limit: 20,
+				pages: 1,
+				hasNext: false,
+				hasPrev: false
+			};
+		}),
+		getOne: (async (filter) => {
+			getFilter = filter;
+			return rows[0] ?? null;
+		}),
+		aggregate: (async (req = {}) => {
+			aggFilter = req.filter;
+			return { rows: [{ tally: rows.length }] };
+		}),
+		capabilities: {
+			count: false,
+			exists: false,
+			distinct: false,
+			aggregate: true,
+			transactions: false,
+			lookup: false,
+			softDelete: false
+		}
+	});
+	const resource = defineResource({
+		name: "conf",
+		prefix: "/confs",
+		adapter: { repository: repo },
+		controller: new BaseController(repo, {
+			resourceName: "conf",
+			tenantField: false
+		}),
+		permissions: {
+			list: opts.permission,
+			get: opts.permission,
+			create: opts.permission,
+			update: opts.permission,
+			delete: opts.permission
+		},
+		aggregations: { tally: defineAggregation({
+			measures: { tally: { op: "count" } },
+			permissions: opts.permission
+		}) }
+	});
+	const app = Fastify({ logger: false });
+	await app.register(resource.toPlugin());
+	await app.ready();
+	const list = await app.inject({
+		method: "GET",
+		url: "/confs"
+	});
+	const get = await app.inject({
+		method: "GET",
+		url: "/confs/1"
+	});
+	const aggregation = await app.inject({
+		method: "GET",
+		url: "/confs/aggregations/tally"
+	});
+	return {
+		list: {
+			status: list.statusCode,
+			filter: listFilter
+		},
+		get: {
+			status: get.statusCode,
+			filter: getFilter
+		},
+		aggregation: {
+			status: aggregation.statusCode,
+			filter: aggFilter
+		},
+		close: () => app.close()
+	};
+}
+//#endregion
 //#region src/testing/authSession.ts
 function buildHeaders(token, orgId, extra) {
 	const headers = { authorization: `Bearer ${token}` };
@@ -464,6 +803,127 @@ async function setupBetterAuthTestApp(input) {
 	};
 }
 //#endregion
+//#region src/testing/testActor.ts
+/**
+* Test-only actor installation — how a package's HTTP tests say "run this
+* request as a manager in org X".
+*
+* Identity in arc comes from `request.scope` and only from `request.scope`;
+* headers like `x-role` are not identity. That rule left tests with no seam —
+* `bootModuleApp` boots with `auth: false`, so every injected request arrived as
+* `PUBLIC_SCOPE` and any role-gated route answered 401 with no supported way to
+* be somebody.
+*
+* The `x-test-actor` header is a TRANSPORT for the test's intent, not a trusted
+* claim. The authenticator that reads it is installed by `bootModuleApp` alone,
+* behind the `@classytic/arc/testing` entrypoint; `createApp` never registers
+* it, so no production build turns a forged header into identity. It is
+* per-request rather than boot-only because the interesting authorization tests
+* are the ones where a cashier is refused what a manager is allowed.
+*
+* Gate the routes under test with arc's own primitives — `requireRoles`,
+* `requireOrgMembership`, `allOf(...)`. A test-specific gate would be a second
+* implementation of authorization whose semantics could drift from the one
+* actually shipping.
+*/
+/** The header the testing harness uses to carry a request's actor. */
+const TEST_ACTOR_HEADER = "x-test-actor";
+/**
+* Build the headers that make an injected request act as `actor`.
+*
+* A string is shorthand for a single role. `null` means "stay public", so a test
+* can prove an endpoint is reachable anonymously.
+*
+* @example
+* ```ts
+* t.app.inject({ method: 'GET', url: '/pos/shifts/current',
+*   headers: testActorHeaders('manager', ORG) });
+* ```
+*/
+function testActorHeaders(actor, organizationId) {
+	if (actor === null) return {};
+	const org = organizationId !== void 0 ? { organizationId } : {};
+	const spec = typeof actor === "string" ? {
+		roles: [actor],
+		...org
+	} : {
+		...actor,
+		...org
+	};
+	return { [TEST_ACTOR_HEADER]: JSON.stringify(spec) };
+}
+/**
+* Turn a spec into a `RequestScope`.
+*
+* `orgRoles` defaults to `roles`: a test that says "manager" means it at both
+* levels, and making the caller repeat itself only produces tests that pass a
+* global gate and mysteriously fail an org one.
+*/
+function scopeFromTestActor(spec) {
+	const roles = spec.roles ?? [];
+	const userId = spec.userId ?? `test-${roles.join("-") || "anon"}`;
+	if (spec.elevated !== void 0 && spec.elevated !== false) return {
+		kind: "elevated",
+		userId,
+		elevatedBy: spec.elevated === true ? "test" : spec.elevated,
+		...spec.organizationId !== void 0 ? { organizationId: spec.organizationId } : {},
+		...spec.context !== void 0 ? { context: Object.freeze({ ...spec.context }) } : {}
+	};
+	if (spec.organizationId !== void 0) return {
+		kind: "member",
+		userId,
+		userRoles: roles,
+		organizationId: spec.organizationId,
+		orgRoles: spec.orgRoles ?? roles,
+		...spec.teamId !== void 0 ? { teamId: spec.teamId } : {},
+		...spec.context !== void 0 ? { context: Object.freeze({ ...spec.context }) } : {}
+	};
+	return {
+		kind: "authenticated",
+		userId,
+		userRoles: roles
+	};
+}
+/**
+* Build the `auth` option that makes the test actor arc's authenticator.
+*
+* It must be an authenticator, not a hook. Fastify encapsulates plugins and
+* modules register DURING `createApp`, so a hook added to the root instance
+* afterwards never runs for their routes — every request still resolves as
+* public and every role gate still answers 401, which reads exactly like a
+* broken authorization rule in the code under test. Registering as
+* `auth: { type: 'authenticator' }` puts the scope where arc's own auth would,
+* at the phase arc expects, so tenant filtering and permission checks behave
+* identically to production.
+*
+* `defaultActor` applies to requests carrying no header. A malformed header
+* REJECTS rather than falling back to public — a test that meant to be an admin
+* and got quietly demoted is the most expensive way to fail.
+*/
+function testActorAuth(defaultActor) {
+	const authenticate = async (request) => {
+		const req = request;
+		const raw = req.headers[TEST_ACTOR_HEADER];
+		let spec = defaultActor;
+		if (typeof raw === "string") try {
+			spec = JSON.parse(raw);
+		} catch {
+			throw new Error(`[arc-testing] malformed ${TEST_ACTOR_HEADER} header: ${raw}. Build it with testActorHeaders() rather than by hand.`);
+		}
+		if (spec === void 0) return;
+		req.scope = scopeFromTestActor(spec);
+		req.user = {
+			id: getUserId(req.scope) ?? "test-anon",
+			...spec.roles !== void 0 ? { role: spec.roles } : {},
+			...spec.organizationId !== void 0 ? { organizationId: spec.organizationId } : {}
+		};
+	};
+	return {
+		type: "authenticator",
+		authenticate
+	};
+}
+//#endregion
 //#region src/testing/bootModuleApp.ts
 /**
 * The built-in DB factory: in-memory MongoDB via lazy devDep imports.
@@ -496,7 +956,6 @@ async function bootModuleApp(modules, options = {}) {
 	const db = await (options.database ?? mongoMemoryDatabase)({ replset: options.replset ?? false });
 	const ctx = {
 		uri: db.uri,
-		mongoUri: db.uri,
 		connection: db.connection
 	};
 	const resolved = typeof modules === "function" ? await modules(ctx) : modules;
@@ -505,7 +964,17 @@ async function bootModuleApp(modules, options = {}) {
 	try {
 		app = await createApp({
 			preset: "testing",
-			auth: false,
+			/**
+			* The test actor is arc's AUTHENTICATOR rather than a bolted-on hook, so the scope
+			* lands at the phase the rest of the pipeline expects — tenant filtering and
+			* permission checks then behave exactly as they do in production.
+			*
+			* This replaces the old `auth: false`. The authenticator is inert for a request
+			* carrying no `x-test-actor` header and no configured default, so a suite that
+			* never mentions an actor behaves as it did before. `options.app` still wins, so a
+			* suite exercising real auth can override it.
+			*/
+			auth: testActorAuth(options.actor),
 			sensible: false,
 			...options.app,
 			modules: list
@@ -519,7 +988,6 @@ async function bootModuleApp(modules, options = {}) {
 	return {
 		app,
 		uri: db.uri,
-		mongoUri: db.uri,
 		connection: db.connection,
 		exports: (name) => getModuleExports(app, name),
 		close: async () => {
@@ -845,212 +1313,61 @@ function createHttpTestHarness(resource, optionsOrGetter) {
 	return new HttpTestHarness(resource, optionsOrGetter);
 }
 //#endregion
-//#region src/testing/mocks.ts
+//#region src/testing/scopeRoleGate.ts
 /**
-* Create a mock repository for testing
+* `scopeRoleGate` — the ONE role gate for package tests.
 *
-* @example
-* const mockRepo = createMockRepository<Product>({
-*   getById: vi.fn().mockResolvedValue({ id: '1', name: 'Test' }),
-*   create: vi.fn().mockImplementation(data => Promise.resolve({ id: '1', ...data })),
-* });
+* ## Why this is in the framework
 *
-* await mockRepo.getById('1'); // Returns mocked product
-*/
-function createMockRepository(overrides = {}) {
-	return {
-		getAll: vi.fn().mockResolvedValue({
-			method: "offset",
-			data: [],
-			total: 0,
-			page: 1,
-			limit: 20,
-			pages: 0,
-			hasNext: false,
-			hasPrev: false
-		}),
-		getById: vi.fn().mockResolvedValue(null),
-		create: vi.fn().mockImplementation((data) => Promise.resolve({
-			_id: "mock-id",
-			...data
-		})),
-		update: vi.fn().mockImplementation((_id, data) => Promise.resolve({
-			_id: "mock-id",
-			...data
-		})),
-		delete: vi.fn().mockResolvedValue({
-			success: true,
-			message: "Deleted"
-		}),
-		updateMany: vi.fn().mockResolvedValue({
-			acknowledged: true,
-			matchedCount: 0,
-			modifiedCount: 0
-		}),
-		deleteMany: vi.fn().mockResolvedValue({
-			acknowledged: true,
-			deletedCount: 0
-		}),
-		claim: vi.fn().mockResolvedValue(null),
-		claimVersion: vi.fn().mockResolvedValue(null),
-		capabilities: {
-			transactions: false,
-			nestedTransactions: false,
-			upsert: false,
-			duplicateKeyError: false,
-			distinct: false,
-			aggregate: false,
-			getOrCreate: false,
-			countAndExists: false
-		},
-		getBySlug: vi.fn().mockResolvedValue(null),
-		getDeleted: vi.fn().mockResolvedValue([]),
-		restore: vi.fn().mockResolvedValue(null),
-		getTree: vi.fn().mockResolvedValue([]),
-		getChildren: vi.fn().mockResolvedValue([]),
-		...overrides
-	};
-}
-/**
-* Create a mock user for authentication testing
-*/
-function createMockUser(overrides = {}) {
-	return {
-		_id: "mock-user-id",
-		id: "mock-user-id",
-		email: "test@example.com",
-		roles: ["user"],
-		organizationId: null,
-		...overrides
-	};
-}
-/**
-* Create a mock Fastify request
-*/
-function createMockRequest(overrides = {}) {
-	return {
-		body: {},
-		params: {},
-		query: {},
-		headers: {},
-		user: createMockUser(),
-		context: {},
-		log: {
-			info: vi.fn(),
-			warn: vi.fn(),
-			error: vi.fn(),
-			debug: vi.fn()
-		},
-		...overrides
-	};
-}
-/**
-* Create a mock Fastify reply
-*/
-function createMockReply() {
-	return {
-		code: vi.fn().mockReturnThis(),
-		send: vi.fn().mockReturnThis(),
-		header: vi.fn().mockReturnThis(),
-		headers: vi.fn().mockReturnThis(),
-		status: vi.fn().mockReturnThis(),
-		type: vi.fn().mockReturnThis(),
-		redirect: vi.fn().mockReturnThis(),
-		callNotFound: vi.fn().mockReturnThis(),
-		sent: false
-	};
-}
-/**
-* Create a mock controller for testing
-*/
-function createMockController(repository) {
-	return {
-		repository,
-		list: vi.fn(),
-		get: vi.fn(),
-		create: vi.fn(),
-		update: vi.fn(),
-		delete: vi.fn()
-	};
-}
-/**
-* Create mock data factory
+* Nine `@classytic/arc-*` packages had their own copy of this helper, and all nine were
+* wrong in the same two ways:
 *
-* @example
-* const productFactory = createDataFactory<Product>({
-*   name: () => faker.commerce.productName(),
-*   price: () => faker.number.int({ min: 10, max: 1000 }),
-*   sku: (i) => `SKU-${i}`,
-* });
+* 1. They read the role from an `x-role` HEADER and INSTALLED the request scope from
+*    inside the check — so identity came from the caller's own claim, and it arrived too
+*    late for arc's tenant-filtering pipeline to see it.
+* 2. They returned the pre-2.30 `{ granted: boolean }` shape, which is neither a boolean
+*    nor an `AuthorizationDecision`. It passed through `normalizeToDecision` untouched,
+*    arrived with `effect: undefined`, and was read as DENY — the gate said yes and arc
+*    refused anyway. Nothing type-errored, because the gate is cast at the call site.
 *
-* const product = productFactory.build();
-* const products = productFactory.buildMany(10);
-*/
-function createDataFactory(template) {
-	let counter = 0;
-	return {
-		build(overrides = {}) {
-			const index = counter++;
-			const data = {};
-			for (const [key, generator] of Object.entries(template)) data[key] = generator(index);
-			return {
-				...data,
-				...overrides
-			};
-		},
-		buildMany(count, overrides = {}) {
-			return Array.from({ length: count }, () => this.build(overrides));
-		},
-		reset() {
-			counter = 0;
-		}
-	};
-}
-/**
-* Create a spy that tracks function calls
+* Two of the nine had already been fixed by hand, each with a docstring describing this
+* exact discovery. The knowledge reached neither of the other seven. That is the whole
+* case for a shared seam: a copy does not fail, it diverges.
 *
-* Useful for testing side effects without full mocking
-*/
-function createSpy(_name = "spy") {
-	const calls = [];
-	const spy = vi.fn((...args) => {
-		calls.push(args);
-	});
-	spy.getCalls = () => calls;
-	spy.getLastCall = () => calls[calls.length - 1] || [];
-	return spy;
-}
-/**
-* Wait for a condition to be true
+* A test role gate is generic — "does the verified scope hold one of these roles" has no
+* domain in it — so it belongs here, beside the contract it depends on.
+*
+* Identity itself comes from `testActorHeaders()` + `bootModuleApp`'s authenticator
+* (see `testActor.ts`), which puts the scope where production puts it. This stays a pure
+* predicate over what arc verified.
 *
-* Useful for async testing
+* Kept in its own module rather than beside `testActor.ts` so the two can be edited
+* independently.
 */
-async function waitFor(condition, options = {}) {
-	const { timeout = 5e3, interval = 100 } = options;
-	const startTime = Date.now();
-	while (Date.now() - startTime < timeout) {
-		if (await condition()) return;
-		await new Promise((resolve) => setTimeout(resolve, interval));
-	}
-	throw new Error(`Timeout waiting for condition after ${timeout}ms`);
-}
 /**
-* Create a test timer that can be controlled
+* Grants iff the caller is an org member holding one of `allowed` as an ORG role.
+*
+* This is `requireOrgRole` under a name package tests reach for — deliberately a
+* delegation, not a reimplementation. It previously read `scope.userRoles` while
+* requiring an organization, so it disagreed with production for any actor whose
+* global and org roles differ: given
+* `{ roles: ["employee"], orgRoles: ["manager"], organizationId: "org-1" }`,
+* `requireOrgRole("manager")` allowed and this denied. The tests never caught it
+* because `scopeFromTestActor` defaults `orgRoles` to `roles`, making the two
+* dimensions identical for the common actor.
+*
+* Delegating also inherits the semantics a hand-rolled gate kept missing:
+* elevated scopes pass, and a service (API-key) identity is refused with a
+* message naming `requireServiceScope` instead of silently failing a role test.
+*
+* **Pair it with an org-bearing actor.** `testActorHeaders('manager', ORG)`
+* yields a `member` scope and passes; `testActorHeaders('manager')` yields an
+* `authenticated` scope with no tenant, which is refused — arc's generated CRUD
+* filters by tenant, so a gate that waves a tenant-less request through is how a
+* green test reads another org's rows.
 */
-function createTestTimer() {
-	let time = Date.now();
-	return {
-		now: () => time,
-		advance: (ms) => {
-			time += ms;
-		},
-		set: (timestamp) => {
-			time = timestamp;
-		},
-		reset: () => {
-			time = Date.now();
-		}
-	};
+function scopeRoleGate(...allowed) {
+	return requireOrgRole(...allowed);
 }
 //#endregion
 //#region src/testing/testApp.ts
@@ -1118,7 +1435,7 @@ function pickDefaultAuth(authMode, callerAuth) {
 	};
 }
 async function createTestApp(options = {}) {
-	const { createApp } = await import("../createApp-Du5G54TM.mjs").then((n) => n.r);
+	const { createApp } = await import("../createApp-Df89BEni.mjs").then((n) => n.r);
 	const { resources = [], db = "in-memory", connectMongoose = false, authMode = "jwt", defaultOrgId, plugins, auth: callerAuth, ...appOptions } = options;
 	let dbHandle;
 	let dbUri;
@@ -1188,4 +1505,4 @@ function createMinimalTestApp(options = {}) {
 	});
 }
 //#endregion
-export { HttpTestHarness, bootModuleApp, createBetterAuthProvider, createBetterAuthTestHelpers, createCustomAuthProvider, createDataFactory, createHttpTestHarness, createJwtAuthProvider, createMinimalTestApp, createMockController, createMockReply, createMockRepository, createMockRequest, createMockUser, createSpy, createTestApp, createTestFixtures, createTestTimer, expectArc, mongoMemoryDatabase, preloadResources, preloadResourcesAsync, runStorageContract, safeParseBody, setupBetterAuthTestApp, waitFor };
+export { HttpTestHarness, TEST_ACTOR_HEADER, bootModuleApp, createBetterAuthProvider, createBetterAuthTestHelpers, createCustomAuthProvider, createDataFactory, createHttpTestHarness, createJwtAuthProvider, createMinimalTestApp, createMockController, createMockReply, createMockRepository, createMockRequest, createMockUser, createSpy, createTestApp, createTestFixtures, createTestTimer, expectArc, mongoMemoryDatabase, preloadResources, preloadResourcesAsync, runAuthorizationConformance, runStorageContract, safeParseBody, scopeFromTestActor, scopeRoleGate, setupBetterAuthTestApp, testActorAuth, testActorHeaders, waitFor };