@classytic/arc 2.30.0 → 2.31.0

package/dist/{schemaConverter-DJvodiHj.mjs → schemaConverter-D--wdJM-.mjs}

@@ -1,3 +1,4 @@
+/*! @classytic/arc v2.31.0 | MIT | https://classytic.com */
 import { arcLog } from "./logger/index.mjs";
 //#region src/utils/schemaConverter.ts
 /**
@@ -25,12 +26,53 @@ import { arcLog } from "./logger/index.mjs";
 *   Using `draft-7` fixes `.positive() / .negative() / .gt() / .lt()` out of the box.
 * - **`openapi-3.0`** — for OpenAPI doc generation (arc emits OpenAPI 3.0.3). Keeps
 *   the boolean exclusive form that 3.0 tooling expects.
+*
+* ## Input vs output (`io`)
+*
+* A Zod schema has TWO shapes and `z.toJSONSchema()` emits one of them. Getting
+* this wrong is not cosmetic — it rejects legal traffic:
+*
+* ```ts
+* z.object({ title: z.string(), status: z.string().default("draft") })
+* // io: "output" → required: ["title", "status"]   ← a client omitting `status` is REJECTED
+* // io: "input"  → required: ["title"]             ← correct: the default fills it in
+* ```
+*
+* The same applies to `.transform()`: in output mode the node is unrepresentable
+* and degrades to `{}` (no validation at all), while input mode emits the real
+* input type. So arc converts by DIRECTION:
+*
+* - **request** (`body`, `querystring`, `params`, `headers`) → `io: "input"` —
+*   validates what the client SENDS, before defaults/transforms/coercion apply.
+* - **response** (and the `entity` doc shape) → `io: "output"` — describes what
+*   the server RETURNS, after they apply.
+*
+* One deliberate consequence: a plain `z.object()` emits
+* `additionalProperties: false` in output mode but NOT in input mode, because
+* `z.object()` STRIPS unknown keys rather than rejecting them — so extra keys
+* are legal input. Use `z.strictObject()` when the wire contract must reject
+* them; it keeps `additionalProperties: false` in both modes.
 */
 const log = arcLog("schema");
 /** Default target for Fastify-consumed schemas (matches Fastify v5's default AJV draft). */
 const DEFAULT_FASTIFY_TARGET = "draft-7";
 /** Default target for OpenAPI document generation (matches arc's emitted OpenAPI version). */
 const DEFAULT_OPENAPI_TARGET = "openapi-3.0";
+/**
+* Map arc's target onto one Zod actually branches on.
+*
+* Zod's `target` is typed `"draft-04" | "draft-07" | "draft-2020-12" |
+* "openapi-3.0" | ({} & string)` — that last member accepts ANY string without
+* narrowing, so an unrecognized value is not rejected, it just matches none of
+* the internal `target === ...` branches and silently gets draft-2020-12
+* behaviour. `"draft-7"` is safe (Zod normalizes the alias to `"draft-07"`),
+* but `"openapi-3.1"` is neither official nor normalized. Mapping it explicitly
+* keeps the fallback intentional rather than accidental — and it is the right
+* dialect, since OpenAPI 3.1 aligned its Schema Object with JSON Schema 2020-12.
+*/
+function zodTarget(target) {
+	return target === "openapi-3.1" ? "draft-2020-12" : target;
+}
 let _toJSONSchema = null;
 const zodReady = import("zod").then(({ z }) => {
 	if (typeof z?.toJSONSchema === "function") _toJSONSchema = (schema, opts) => z.toJSONSchema(schema, opts);
@@ -92,22 +134,33 @@ function unconvertible(mode, message, cause) {
 *               Pass `openapi-3.0`/`openapi-3.1` for OpenAPI document generation.
 * @param mode   Failure policy for unconvertible Zod schemas — see
 *               {@link UnconvertibleMode}. Defaults to `'warn'`.
+* @param io     Which shape to emit — see {@link SchemaIo} and the module
+*               docblock. Defaults to `'output'`, matching Zod's own default;
+*               arc's request-side call sites pass `'input'` explicitly.
 */
-function toJsonSchema(input, target = DEFAULT_FASTIFY_TARGET, mode = "warn") {
+function toJsonSchema(input, target = DEFAULT_FASTIFY_TARGET, mode = "warn", io = "output") {
 	if (input == null) return void 0;
 	if (typeof input !== "object") return void 0;
-	if (isJsonSchema(input)) return input;
+	if (isJsonSchema(input)) {
+		const plain = input;
+		if ("$schema" in plain) {
+			const { $schema: _dropped, ...rest } = plain;
+			return rest;
+		}
+		return plain;
+	}
 	if (isZodSchema(input)) {
 		if (!_toJSONSchema) return unconvertible(mode, "A Zod schema was passed but zod v4 is not installed (or not yet loaded). Install zod >=4 — arc converts via zod's native z.toJSONSchema().");
 		try {
 			const converted = _toJSONSchema(input, {
-				target,
+				target: zodTarget(target),
+				io,
 				unrepresentable: mode === "throw" ? "throw" : "any"
 			});
 			if ("$schema" in converted) delete converted.$schema;
 			return converted;
 		} catch (cause) {
-			return unconvertible(mode, `z.toJSONSchema() failed for a Zod schema (target: ${target}): ${cause instanceof Error ? cause.message : String(cause)}. Zod-only features with no JSON Schema equivalent (.refine/.transform/custom checks) cannot express wire validation — enforce those in the handler or a pipeline step.`, cause);
+			return unconvertible(mode, `z.toJSONSchema() failed for a Zod schema (target: ${target}, io: ${io}): ${cause instanceof Error ? cause.message : String(cause)}. Types with no JSON Schema equivalent cannot express wire validation. For \`z.date()\` / \`z.bigint()\` on a REQUEST schema, use the wire-shaped form (\`z.iso.datetime()\` / \`z.string()\`) and convert in a hook — JSON has no date or bigint. For \`.refine()\` / \`.transform()\` / custom checks, enforce them in the handler or a pipeline step.`, cause);
 		}
 	}
 	if (isZodV3Schema(input)) return unconvertible(mode, "A Zod v3 schema was passed (has `_def` but no v4 `_zod` marker). arc requires zod >=4 for schema conversion — upgrade zod, or pass plain JSON Schema.");
@@ -122,19 +175,19 @@ function toJsonSchema(input, target = DEFAULT_FASTIFY_TARGET, mode = "warn") {
 */
 function convertOpenApiSchemas(schemas, target = DEFAULT_OPENAPI_TARGET) {
 	const result = {};
-	const schemaFields = [
-		"entity",
-		"createBody",
-		"updateBody",
-		"params",
-		"listQuery",
-		"response"
-	];
-	for (const field of schemaFields) {
+	const schemaFields = {
+		entity: "output",
+		createBody: "input",
+		updateBody: "input",
+		params: "input",
+		listQuery: "input",
+		response: "output"
+	};
+	for (const [field, io] of Object.entries(schemaFields)) {
 		const value = schemas[field];
-		if (value !== void 0) result[field] = toJsonSchema(value, target) ?? value;
+		if (value !== void 0) result[field] = toJsonSchema(value, target, "warn", io) ?? value;
 	}
-	for (const [key, value] of Object.entries(schemas)) if (!schemaFields.includes(key)) result[key] = value;
+	for (const [key, value] of Object.entries(schemas)) if (!(key in schemaFields)) result[key] = value;
 	return result;
 }
 /**
@@ -158,11 +211,11 @@ function convertRouteSchema(schema, target = DEFAULT_FASTIFY_TARGET) {
 		"querystring",
 		"params",
 		"headers"
-	]) if (result[field] !== void 0) result[field] = toJsonSchema(result[field], target, mode) ?? result[field];
+	]) if (result[field] !== void 0) result[field] = toJsonSchema(result[field], target, mode, "input") ?? result[field];
 	if (result.response !== void 0 && typeof result.response === "object" && result.response !== null) {
 		const responseObj = result.response;
 		const convertedResponse = {};
-		for (const [statusCode, responseSchema] of Object.entries(responseObj)) convertedResponse[statusCode] = toJsonSchema(responseSchema, target, mode) ?? responseSchema;
+		for (const [statusCode, responseSchema] of Object.entries(responseObj)) convertedResponse[statusCode] = toJsonSchema(responseSchema, target, mode, "output") ?? responseSchema;
 		result.response = convertedResponse;
 	}
 	return result;

package/dist/{schemaIR-Ca7ySNPx.mjs → schemaIR-Bm2enbnh.mjs}

@@ -1,4 +1,5 @@
-import { o as toJsonSchema } from "./schemaConverter-DJvodiHj.mjs";
+/*! @classytic/arc v2.31.0 | MIT | https://classytic.com */
+import { o as toJsonSchema } from "./schemaConverter-D--wdJM-.mjs";
 //#region src/core/schemaIR.ts
 /**
 * Schema IR — one canonical representation, two adapters.

package/dist/schemas/index.d.mts

@@ -1,3 +1,4 @@
+
 import { ErrorContract, ErrorDetail } from "@classytic/repo-core/errors";
 import { Static, TObject, TSchema, TSchema as TSchema$1, Type, Type as Type$1 } from "typebox";
 import { FastifyPluginAsyncTypebox, FastifyPluginCallbackTypebox, TypeBoxTypeProvider } from "@fastify/type-provider-typebox";

package/dist/schemas/index.mjs

@@ -1,3 +1,4 @@
+/*! @classytic/arc v2.31.0 | MIT | https://classytic.com */
 import { errorContractSchema, errorDetailSchema } from "@classytic/repo-core/errors";
 import { Type, Type as Type$1 } from "typebox";
 //#region src/schemas/index.ts

package/dist/scim/index.d.mts

@@ -1,3 +1,4 @@
+
 import { FastifyPluginAsync, FastifyRequest } from "fastify";
 import { RepositoryLike } from "@classytic/repo-core/adapter";
 //#region src/scim/mapping.d.ts

package/dist/scim/index.mjs

@@ -1,4 +1,5 @@
-import { t as parseJsonBody } from "../jsonBody-BlzAoGCe.mjs";
+/*! @classytic/arc v2.31.0 | MIT | https://classytic.com */
+import { t as parseJsonBody } from "../jsonBody-BYbLDi5D.mjs";
 import fp from "fastify-plugin";
 //#region src/scim/errors.ts
 var ScimError = class extends Error {

package/dist/scope/index.d.mts

@@ -1,5 +1,6 @@
-import { A as requireOrgId, C as hasOrgAccess, D as isOrgInScope, E as isMember, M as requireUserId, N as scopeFirstCtx, O as isService, S as getUserRoles, T as isElevated, _ as getScopeContextMap, a as ScopeFirstCtx, b as getTenantFromRequest, c as getAncestorOrgIds, d as getMandate, f as getOrgContext, g as getScopeContext, h as getRequestScope, i as RequestScope, j as requireTeamId, k as requireClientId, l as getClientId, m as getOrgRoles, n as Mandate, o as ScopeFirstCtxOptions, p as getOrgId, r as PUBLIC_SCOPE, s as ScopeFirstCtxRequest, t as AUTHENTICATED_SCOPE, u as getDPoPJkt, v as getServiceScopes, w as isAuthenticated, x as getUserId, y as getTeamId } from "../types-DjC-KUCz.mjs";
-import { i as elevationPlugin, n as ElevationOptions, r as _default, t as ElevationEvent } from "../elevation-C9s5hFP_.mjs";
+
+import { A as requireOrgId, C as hasOrgAccess, D as isOrgInScope, E as isMember, M as requireUserId, N as scopeFirstCtx, O as isService, S as getUserRoles, T as isElevated, _ as getScopeContextMap, a as ScopeFirstCtx, b as getTenantFromRequest, c as getAncestorOrgIds, d as getMandate, f as getOrgContext, g as getScopeContext, h as getRequestScope, i as RequestScope, j as requireTeamId, k as requireClientId, l as getClientId, m as getOrgRoles, n as Mandate, o as ScopeFirstCtxOptions, p as getOrgId, r as PUBLIC_SCOPE, s as ScopeFirstCtxRequest, t as AUTHENTICATED_SCOPE, u as getDPoPJkt, v as getServiceScopes, w as isAuthenticated, x as getUserId, y as getTeamId } from "../types-ChuShpCP.mjs";
+import { i as elevationPlugin, n as ElevationOptions, r as _default, t as ElevationEvent } from "../elevation-BXCfVcNG.mjs";
 import { FastifyReply, FastifyRequest } from "fastify";
 //#region src/scope/rateLimitKey.d.ts
 interface RateLimitKeyContext {

package/dist/scope/index.mjs

@@ -1,5 +1,6 @@
-import { C as isService, D as requireUserId, E as requireTeamId, O as scopeFirstCtx, S as isOrgInScope, T as requireOrgId, _ as getUserRoles, a as getDPoPJkt, b as isElevated, c as getOrgId, d as getScopeContext, f as getScopeContextMap, g as getUserId, h as getTenantFromRequest, i as getClientId, l as getOrgRoles, m as getTeamId, n as PUBLIC_SCOPE, o as getMandate, p as getServiceScopes, r as getAncestorOrgIds, s as getOrgContext, t as AUTHENTICATED_SCOPE, u as getRequestScope, v as hasOrgAccess, w as requireClientId, x as isMember, y as isAuthenticated } from "../types-CSyCxl2V.mjs";
-import { n as elevation_default, t as elevationPlugin } from "../elevation-CIz1GjGm.mjs";
-import { t as createTenantKeyGenerator } from "../rateLimitKey-BoWRH3e7.mjs";
-import { t as resolveOrgFromHeader } from "../scope-DfaPntpo.mjs";
+/*! @classytic/arc v2.31.0 | MIT | https://classytic.com */
+import { C as isService, D as requireUserId, E as requireTeamId, O as scopeFirstCtx, S as isOrgInScope, T as requireOrgId, _ as getUserRoles, a as getDPoPJkt, b as isElevated, c as getOrgId, d as getScopeContext, f as getScopeContextMap, g as getUserId, h as getTenantFromRequest, i as getClientId, l as getOrgRoles, m as getTeamId, n as PUBLIC_SCOPE, o as getMandate, p as getServiceScopes, r as getAncestorOrgIds, s as getOrgContext, t as AUTHENTICATED_SCOPE, u as getRequestScope, v as hasOrgAccess, w as requireClientId, x as isMember, y as isAuthenticated } from "../types-Cys0ko9Z.mjs";
+import { n as elevation_default, t as elevationPlugin } from "../elevation-D2l1mh4g.mjs";
+import { t as createTenantKeyGenerator } from "../rateLimitKey-Dn5JNmkj.mjs";
+import { t as resolveOrgFromHeader } from "../scope-DHx5Fous.mjs";
 export { AUTHENTICATED_SCOPE, PUBLIC_SCOPE, createTenantKeyGenerator, elevation_default as elevationPlugin, elevationPlugin as elevationPluginFn, getAncestorOrgIds, getClientId, getDPoPJkt, getMandate, getOrgContext, getOrgId, getOrgRoles, getRequestScope, getScopeContext, getScopeContextMap, getServiceScopes, getTeamId, getTenantFromRequest, getUserId, getUserRoles, hasOrgAccess, isAuthenticated, isElevated, isMember, isOrgInScope, isService, requireClientId, requireOrgId, requireTeamId, requireUserId, resolveOrgFromHeader, scopeFirstCtx };

package/dist/{scope-DfaPntpo.mjs → scope-DHx5Fous.mjs}

@@ -1,6 +1,7 @@
-import { a as OrgAccessDeniedError, l as UnauthorizedError } from "./errors-DkO8Nk6-.mjs";
-import { n as requireSingleHeaderValue } from "./headers-BvlQSDMB.mjs";
-import { n as getUserRoles } from "./userHelpers-Cg_y3fBz.mjs";
+/*! @classytic/arc v2.31.0 | MIT | https://classytic.com */
+import { a as OrgAccessDeniedError, l as UnauthorizedError } from "./errors-Cj42AntO.mjs";
+import { n as requireSingleHeaderValue } from "./headers-3zvE0rM3.mjs";
+import { n as getUserRoles } from "./userHelpers-ChYJ6CdK.mjs";
 //#region src/scope/resolveOrgFromHeader.ts
 /**
 * Create a preHandler hook that resolves org scope from a header.

package/dist/{sessionManager-BHOM3N_0.d.mts → sessionManager-qimlKV0P.d.mts}

@@ -1,3 +1,4 @@
+
 import { FastifyPluginAsync, FastifyReply, FastifyRequest } from "fastify";
 //#region src/auth/sessionManager.d.ts
 /**

package/dist/{simpleEqualityMatcher-Cg05HPsn.mjs → simpleEqualityMatcher-DjQJ7FKA.mjs}

@@ -1,3 +1,4 @@
+/*! @classytic/arc v2.31.0 | MIT | https://classytic.com */
 //#region src/utils/simpleEqualityMatcher.ts
 /**
 * `simpleEqualityMatcher` — a minimal, dialect-agnostic flat-key equality

package/dist/{sse-BQ1w0dfl.mjs → sse-CUTo9y0X.mjs}

@@ -1,8 +1,9 @@
-import { t as __exportAll } from "./rolldown-runtime-8H4AJuhK.mjs";
+/*! @classytic/arc v2.31.0 | MIT | https://classytic.com */
+import { t as __exportAll } from "./rolldown-runtime-CUsjNX9R.mjs";
 import { arcLog } from "./logger/index.mjs";
-import { c as getOrgId, n as PUBLIC_SCOPE } from "./types-CSyCxl2V.mjs";
-import { a as promoteStreamTokenToHeader } from "./streaming-BQcW6_Kq.mjs";
-import { t as openSseStream } from "./sseStream-BQ7Qaynp.mjs";
+import { c as getOrgId, n as PUBLIC_SCOPE } from "./types-Cys0ko9Z.mjs";
+import { a as promoteStreamTokenToHeader } from "./streaming-PSZwi8JV.mjs";
+import { t as openSseStream } from "./sseStream-B_5XcVVd.mjs";
 import fp from "fastify-plugin";
 //#region src/plugins/sse.ts
 var sse_exports = /* @__PURE__ */ __exportAll({

package/dist/{sseStream-BQ7Qaynp.mjs → sseStream-B_5XcVVd.mjs}

@@ -1,4 +1,5 @@
-import { n as forwardedStreamHeaders } from "./streaming-BQcW6_Kq.mjs";
+/*! @classytic/arc v2.31.0 | MIT | https://classytic.com */
+import { n as forwardedStreamHeaders } from "./streaming-PSZwi8JV.mjs";
 //#region src/utils/sseStream.ts
 /**
 * Take over the reply socket and open an SSE stream. Call ONLY after every

package/dist/{storage-DLUZ04kK.d.mts → storage-Cx9Sz3Ou.d.mts}

@@ -1,3 +1,4 @@
+
 //#region src/types/storage.d.ts
 /**
  * Arc's minimal backend-agnostic storage contract.

package/dist/{store-helpers-DY6xq4sM.mjs → store-helpers-D1MP_gRG.mjs}

@@ -1,3 +1,4 @@
+/*! @classytic/arc v2.31.0 | MIT | https://classytic.com */
 //#region src/utils/store-helpers.ts
 /**
 * Classify an error thrown by `getOne` / `getById` / `update` as a

package/dist/{streaming-BQcW6_Kq.mjs → streaming-PSZwi8JV.mjs}

@@ -1,3 +1,4 @@
+/*! @classytic/arc v2.31.0 | MIT | https://classytic.com */
 import { Readable } from "node:stream";
 //#region src/utils/streaming.ts
 /**

package/dist/{subscribe-helpers-DfzsivM6.mjs → subscribe-helpers-C0Tb2aUp.mjs}

@@ -1,4 +1,5 @@
-import { n as createEvent } from "./EventTransport-C6YA8xY9.mjs";
+/*! @classytic/arc v2.31.0 | MIT | https://classytic.com */
+import { n as createEvent } from "./EventTransport-9mlTgqzE.mjs";
 //#region src/events/defineEvent.ts
 /**
 * defineEvent — Typed Event Definitions with Optional Schema Validation

package/dist/sync/changelog.d.mts

@@ -1,2 +1,3 @@
+
 import { ChangeEntry, ChangeLogAppendOptions, ChangeLogStore, ChangeOp, ChangesPage, ChangesSinceOptions, CursorExpiredError, MemoryChangeLogStore, PushMutation, PushVerdict, PushVerdictStatus } from "@classytic/repo-core/sync";
 export { type ChangeEntry, type ChangeLogAppendOptions, type ChangeLogStore, type ChangeOp, type ChangesPage, type ChangesSinceOptions, CursorExpiredError, MemoryChangeLogStore, type PushMutation, type PushVerdict, type PushVerdictStatus };

package/dist/sync/changelog.mjs

@@ -1,2 +1,3 @@
+/*! @classytic/arc v2.31.0 | MIT | https://classytic.com */
 import { CursorExpiredError, MemoryChangeLogStore } from "@classytic/repo-core/sync";
 export { CursorExpiredError, MemoryChangeLogStore };

package/dist/testing/cleanupStoreContract.d.mts

@@ -1,4 +1,5 @@
-import { D as CleanupRunStore } from "../types-C_ZZRcD6.mjs";
+
+import { D as CleanupRunStore } from "../types-C4QE8qnm.mjs";
 //#region src/testing/cleanupStoreContract.d.ts
 interface CleanupRunStoreContractSetupResult {
   store: CleanupRunStore;

package/dist/testing/cleanupStoreContract.mjs

@@ -1,3 +1,4 @@
+/*! @classytic/arc v2.31.0 | MIT | https://classytic.com */
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
 //#region src/testing/cleanupStoreContract.ts
 /**

package/dist/testing/index.d.mts

@@ -1,8 +1,10 @@
-import { V as ResourceDefinition } from "../index-Q5gzEIWY.mjs";
-import { l as AnyRecord, r as PermissionCheck } from "../types-ChvvVNP8.mjs";
-import { n as ArcModuleInput } from "../types-D_n8L6VY.mjs";
-import "../index-CCzVR-N3.mjs";
-import { n as preloadResourcesAsync, r as CreateAppOptions, t as preloadResources } from "../preloadResources-DCfa2egz.mjs";
+
+import { V as ResourceDefinition } from "../index-CpzxqePp.mjs";
+import { i as RequestScope } from "../types-ChuShpCP.mjs";
+import { l as AnyRecord, r as PermissionCheck } from "../types-B7XeLEgK.mjs";
+import { n as ArcModuleInput } from "../types-CBgvkp8O.mjs";
+import "../index-CFThn1K9.mjs";
+import { n as preloadResourcesAsync, r as CreateAppOptions, t as preloadResources } from "../preloadResources-CyoJMSiO.mjs";
 import { StorageContractSetup, StorageContractSetupResult, runStorageContract } from "./storageContract.mjs";
 import { FastifyInstance, FastifyServerOptions } from "fastify";
 import { Mock } from "vitest";
@@ -84,6 +86,13 @@ interface SurfaceObservation {
 interface AuthorizationConformance {
   /** `GET /confs` — the CRUD list surface. */
   list: SurfaceObservation;
+  /**
+   * `GET /confs/:id` — the SINGLE-RECORD surface. Its `filter` is the compound
+   * `buildIdFilter` output (route id AND policy AND tenant), so a policy that
+   * tried to redirect/widen the target would show here — the surface the
+   * filter-overwrite class of bug lives on.
+   */
+  get: SurfaceObservation;
   /** `GET /confs/aggregations/tally` — the aggregation surface. */
   aggregation: SurfaceObservation;
   /** Close the throwaway app. Always call (e.g. in `finally`). */
@@ -327,6 +336,81 @@ declare function createBetterAuthTestHelpers(options?: BetterAuthTestHelpersOpti
  */
 declare function setupBetterAuthTestApp(input: SetupBetterAuthTestAppInput): Promise<SetupBetterAuthTestAppResult>;
 //#endregion
+//#region src/testing/testActor.d.ts
+/** The header the testing harness uses to carry a request's actor. */
+declare const TEST_ACTOR_HEADER = "x-test-actor";
+/**
+ * What a test wants to be. An `organizationId` produces a `member` scope (the
+ * org-scoped case); without one the actor is `authenticated`.
+ */
+interface TestActor {
+  /**
+   * Defaults to a synthetic id derived from the roles. Pass one explicitly when
+   * a test distinguishes two actors — ownership and audit assertions do, and
+   * two actors sharing roles would otherwise share an id.
+   */
+  userId?: string;
+  /** Global roles — what `requireRoles` reads. */
+  roles?: string[];
+  /** Tenant. Present ⇒ a `member` scope. */
+  organizationId?: string;
+  /** Org-level roles from membership records. Defaults to `roles`. */
+  orgRoles?: string[];
+  teamId?: string;
+  /** App-defined dimensions (branch, project, region) read via `getScopeContext`. */
+  context?: Record<string, string>;
+  /**
+   * Elevated (platform-admin) scope. The value is the `elevatedBy` audit string
+   * arc requires — an elevated scope must record who granted it. `true` is
+   * shorthand for `'test'`.
+   *
+   * An elevated scope carries no roles: elevation is a different kind of actor,
+   * not a role. A test needing a role gate AND elevation wants `member`.
+   */
+  elevated?: string | boolean;
+}
+/**
+ * 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) });
+ * ```
+ */
+declare function testActorHeaders(actor: TestActor | string | null, organizationId?: string): Record<string, string>;
+/**
+ * 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.
+ */
+declare function scopeFromTestActor(spec: TestActor): RequestScope;
+/**
+ * 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.
+ */
+declare function testActorAuth(defaultActor?: TestActor): {
+  type: "authenticator";
+  authenticate: (request: unknown) => Promise<void>;
+};
+//#endregion
 //#region src/testing/bootModuleApp.d.ts
 /** Handed to a modules factory — the in-memory DB is live at call time. */
 /**
@@ -350,8 +434,6 @@ type TestDatabaseFactory<TConn = unknown> = (opts: {
 interface TestkitContext<TConn = unknown> {
   /** The provisioned database's connection string. */
   uri: string;
-  /** @deprecated Alias of `uri` from the Mongo-default era — prefer `uri`. */
-  mongoUri: string;
   /**
    * Driver connection handle (the default factory yields mongoose's
    * DEFAULT connection). Generic so DB-typed wrappers assert the driver
@@ -377,13 +459,20 @@ interface BootModuleAppOptions<TConn = unknown> {
    * boot when a module genuinely exercises one).
    */
   app?: Partial<CreateAppOptions>;
+  /**
+   * Default actor for every injected request that carries no `x-test-actor` header.
+   *
+   * The harness boots with `auth: false`, so without this every request is
+   * `PUBLIC_SCOPE` and role-gated routes answer 401 — correct, but it left tests with
+   * no supported way to be somebody. See `testActor.ts` for why the seam lives in the
+   * testing entrypoint and can never be reached from production.
+   */
+  actor?: TestActor;
 }
 interface ModuleTestApp<TConn = unknown> {
   app: FastifyInstance;
   /** The provisioned database's connection string. */
   uri: string;
-  /** @deprecated Alias of `uri` from the Mongo-default era — prefer `uri`. */
-  mongoUri: string;
   /** The mongoose `Connection` handed to the modules factory. */
   connection: TConn;
   /**
@@ -555,13 +644,26 @@ declare function createSpy<T extends (...args: unknown[]) => unknown>(_name?: st
   getLastCall(): unknown[];
 };
 /**
- * Wait for a condition to be true
+ * Wait until `condition` holds — the standard way to assert on asynchronous
+ * effects in arc's suites.
  *
- * Useful for async testing
+ * **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" });
  */
 declare function waitFor(condition: () => boolean | Promise<boolean>, options?: {
   timeout?: number;
   interval?: number;
+  label?: string;
 }): Promise<void>;
 /**
  * Create a test timer that can be controlled
@@ -573,6 +675,31 @@ declare function createTestTimer(): {
   reset: () => void;
 };
 //#endregion
+//#region src/testing/scopeRoleGate.d.ts
+/**
+ * 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.
+ */
+declare function scopeRoleGate(...allowed: string[]): PermissionCheck;
+//#endregion
 //#region src/testing/testApp.d.ts
 type DbMode = "in-memory" | {
   uri: string;
@@ -650,4 +777,4 @@ declare function createTestApp(options?: CreateTestAppOptions): Promise<TestAppC
  */
 declare function createMinimalTestApp(options?: FastifyServerOptions): FastifyInstance;
 //#endregion
-export { type ArcAssertion, type ArcResponseLike, type AuthMode, type AuthResponse, type AuthorizationConformance, type BetterAuthTestHelpers, type BetterAuthTestHelpersOptions, type BetterAuthTestUser, type BootModuleAppOptions, type BootModulesInput, type CreateOrgInput, type CreateTestAppOptions, type DbMode, type FixtureDestroyer, type FixtureFactory, type FixtureRegistration, HttpTestHarness, type HttpTestHarnessOptions, type MockRepository, type ModuleTestApp, type OrgResponse, type RoleConfig, type SetupBetterAuthTestAppInput, type SetupBetterAuthTestAppResult, type SignInInput, type SignUpInput, type StorageContractSetup, type StorageContractSetupResult, type SurfaceObservation, type TestAppContext, type TestAuthProvider, type TestAuthSession, type TestDatabase, type TestDatabaseFactory, type TestFixtures, type TestkitContext, bootModuleApp, createBetterAuthProvider, createBetterAuthTestHelpers, createCustomAuthProvider, createDataFactory, createHttpTestHarness, createJwtAuthProvider, createMinimalTestApp, createMockController, createMockReply, createMockRepository, createMockRequest, createMockUser, createSpy, createTestApp, createTestFixtures, createTestTimer, expectArc, mongoMemoryDatabase, preloadResources, preloadResourcesAsync, runAuthorizationConformance, runStorageContract, safeParseBody, setupBetterAuthTestApp, waitFor };
+export { type ArcAssertion, type ArcResponseLike, type AuthMode, type AuthResponse, type AuthorizationConformance, type BetterAuthTestHelpers, type BetterAuthTestHelpersOptions, type BetterAuthTestUser, type BootModuleAppOptions, type BootModulesInput, type CreateOrgInput, type CreateTestAppOptions, type DbMode, type FixtureDestroyer, type FixtureFactory, type FixtureRegistration, HttpTestHarness, type HttpTestHarnessOptions, type MockRepository, type ModuleTestApp, type OrgResponse, type RoleConfig, type SetupBetterAuthTestAppInput, type SetupBetterAuthTestAppResult, type SignInInput, type SignUpInput, type StorageContractSetup, type StorageContractSetupResult, type SurfaceObservation, TEST_ACTOR_HEADER, type TestActor, type TestAppContext, type TestAuthProvider, type TestAuthSession, type TestDatabase, type TestDatabaseFactory, type TestFixtures, type TestkitContext, 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 };