@classytic/arc 2.41.1 → 2.44.0

package/dist/testing/index.d.mts

@@ -1,10 +1,10 @@
 
 import { i as RequestScope } from "../types-Ddl9OjmE.mjs";
-import { l as PermissionCheck, t as AnyRecord } from "../base-CxrV1LmG.mjs";
-import { V as ResourceDefinition } from "../index-DHbyPo5j.mjs";
-import { n as ArcModuleInput, o as ModuleDisposer, s as ModuleSetupContext } from "../types-DfVDvkdP.mjs";
-import "../index-CFfLKMH4.mjs";
-import { n as preloadResourcesAsync, r as CreateAppOptions, t as preloadResources } from "../preloadResources-CjS2OfpU.mjs";
+import { l as PermissionCheck, t as AnyRecord } from "../base-CZyixEQR.mjs";
+import { F as ResourceDefinition } from "../index-WH7xgvxS.mjs";
+import { h as ModuleSetupContext, m as ModuleDisposer, o as ArcPorts, p as PortName, r as ArcModuleInput, u as ModuleName } from "../types-BJ-2XqVF.mjs";
+import "../index-CUJvoyw3.mjs";
+import { n as CreateAppOptions } from "../index-BkV55WlV.mjs";
 import { StorageContractSetup, StorageContractSetupResult, runStorageContract } from "./storageContract.mjs";
 import { StandardRepo } from "@classytic/repo-core/repository";
 import { FastifyInstance, FastifyServerOptions } from "fastify";
@@ -72,7 +72,181 @@ interface ArcAssertion {
   /** Assert a specific key on `body.meta` or flattened top-level (matches sendControllerResponse flattening). */
   hasMeta(key: string, value?: unknown): ArcAssertion;
 }
-declare function expectArc(response: ArcResponseLike): ArcAssertion;
+export declare function expectArc(response: ArcResponseLike): ArcAssertion;
+//#endregion
+//#region src/testing/testActor.d.ts
+/** The header the testing harness uses to carry a request's actor. */
+export 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) });
+ * ```
+ */
+export 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.
+ */
+export 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.
+ */
+export 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. */
+/**
+ * A provisioned test database — what the `database` seam yields. Arc
+ * core never names a driver: kits ship factories (`mongoMemoryDatabase`
+ * is the built-in default; a sqlitekit/pgkit testkit ships its own) and
+ * the connection flows through as an opaque generic.
+ */
+interface TestDatabase<TConn = unknown> {
+  /** Connection string, when the backend has one (informational). */
+  uri: string;
+  /** Driver connection handle passed to the modules factory. */
+  connection: TConn;
+  /** Stop/disconnect everything this factory started. MUST be idempotent-safe to call once. */
+  teardown(): Promise<void>;
+}
+/** The DB-provisioning seam — `bootModuleApp({ database })`. */
+type TestDatabaseFactory<TConn = unknown> = (opts: {
+  replset?: boolean;
+}) => Promise<TestDatabase<TConn>>;
+interface TestkitContext<TConn = unknown> {
+  /** The provisioned database's connection string. */
+  uri: string;
+  /**
+   * Driver connection handle (the default factory yields mongoose's
+   * DEFAULT connection). Generic so DB-typed wrappers assert the driver
+   * type ONCE: `bootModuleApp<Connection>(...)`. Arc core stays DB-agnostic.
+   */
+  connection: TConn;
+}
+type BootModulesInput<TConn = unknown> = ArcModuleInput | readonly ArcModuleInput[] | ((ctx: TestkitContext<TConn>) => ArcModuleInput | readonly ArcModuleInput[] | Promise<ArcModuleInput | readonly ArcModuleInput[]>);
+interface BootModuleAppOptions<TConn = unknown> {
+  /**
+   * DB provisioner. Default: `mongoMemoryDatabase` (in-memory MongoDB —
+   * lazy devDep imports, nothing Mongo touches arc's runtime). Kits for
+   * other stores inject their own factory here; the rest of the harness
+   * (module resolution, app boot, teardown ordering) is DB-agnostic.
+   */
+  database?: TestDatabaseFactory<TConn>;
+  /** Single-node replica set (transactions). Default: standalone. Passed to the database factory. */
+  replset?: boolean;
+  /**
+   * Extra `createApp` options merged over the testing defaults
+   * (`preset: 'testing'`, `auth: false`, `sensible: false` — utility
+   * plugins stay off so the testkit is dependency-light; re-enable per
+   * 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;
+  /** Host ports for the booted modules — typed and checked exactly as `createApp({ ports })`. */
+  ports?: ArcPorts;
+}
+interface ModuleTestApp<TConn = unknown> {
+  app: FastifyInstance;
+  /** The provisioned database's connection string. */
+  uri: string;
+  /** The mongoose `Connection` handed to the modules factory. */
+  connection: TConn;
+  /**
+   * Typed module-export accessor — `t.exports<CatalogEngine>('catalog')`
+   * instead of reaching through `(t.app as ...).arc.modules.catalog`.
+   * Delegates to `getModuleExports` (throws with the registered-module
+   * list when the name is unknown — same contract hosts get).
+   */
+  exports<TExports = unknown>(name: string): TExports;
+  /** Close app → disconnect mongoose → stop the in-memory server. Idempotent. */
+  close(): Promise<void>;
+}
+/**
+ * The built-in DB factory: in-memory MongoDB via lazy devDep imports.
+ * Everything Mongo-specific about the harness lives HERE — the harness
+ * itself is driver-blind and any kit can replace this via `database`.
+ */
+export declare function mongoMemoryDatabase(opts: {
+  replset?: boolean;
+}): Promise<TestDatabase<unknown>>;
+export declare function bootModuleApp<TConn = unknown>(modules: BootModulesInput<TConn>, options?: BootModuleAppOptions<TConn>): Promise<ModuleTestApp<TConn>>;
+//#endregion
+//#region src/testing/assertModuleBootsAlone.d.ts
+interface ModuleBootsAloneOptions<TConn = unknown> extends BootModuleAppOptions<TConn> {
+  /** Runs against the booted closure before it closes — drive the module's cross-module ports. */
+  probe?: (t: ModuleTestApp<TConn>) => void | Promise<void>;
+}
+interface ModuleBootsAloneResult {
+  /** The closure's modules (bridges excluded), in input order. */
+  readonly closure: readonly string[];
+}
+export declare function assertModuleBootsAlone<TConn = unknown>(modules: BootModulesInput<TConn>,
+/** The module — or several roots booted together, when a deployment rule pairs them. */
+name: ModuleName | readonly ModuleName[], options?: ModuleBootsAloneOptions<TConn>): Promise<ModuleBootsAloneResult>;
 //#endregion
 //#region src/testing/authorizationConformance.d.ts
 /** One surface's observed enforcement: the HTTP status + the filter arc passed the repo. */
@@ -107,7 +281,7 @@ interface AuthorizationConformance {
  * Boot a one-resource app gated by `permission` on both list + an aggregation,
  * hit both surfaces anonymously, and report what arc enforced on each.
  */
-declare function runAuthorizationConformance(opts: {
+export declare function runAuthorizationConformance(opts: {
   /** The permission under test — applied to `list` and the aggregation alike. */
   permission: PermissionCheck;
   /** Rows the mock repo returns for list (aggregation returns a count). */
@@ -166,21 +340,21 @@ interface TestAuthProvider {
  * Accepts both `user` (payload to sign) and `token` (pre-signed) role configs,
  * so the same provider handles mixed flows in a single test.
  */
-declare function createJwtAuthProvider(app: FastifyInstance, opts?: {
+export declare function createJwtAuthProvider(app: FastifyInstance, opts?: {
   defaultOrgId?: string;
 }): TestAuthProvider;
 /**
  * Better Auth provider — uses pre-signed tokens (from signUp/signIn flows).
  * No signing: role configs MUST carry `token`. A `user` alone will throw.
  */
-declare function createBetterAuthProvider(opts?: {
+export declare function createBetterAuthProvider(opts?: {
   defaultOrgId?: string;
 }): TestAuthProvider;
 /**
  * Custom provider — plug in your own token minting logic. Useful for
  * mocked external issuers, session-cookie flows, or fixtures that pre-mint.
  */
-declare function createCustomAuthProvider(mintToken: (role: string, config: RoleConfig) => string, opts?: {
+export declare function createCustomAuthProvider(mintToken: (role: string, config: RoleConfig) => string, opts?: {
   defaultOrgId?: string;
 }): TestAuthProvider;
 //#endregion
@@ -313,13 +487,13 @@ interface SetupBetterAuthTestAppResult {
  * Auth endpoints occasionally emit empty 204 bodies (e.g. set-active) and
  * tests shouldn't crash on the parse.
  */
-declare function safeParseBody<T = unknown>(body: string | undefined): T | null;
+export declare function safeParseBody<T = unknown>(body: string | undefined): T | null;
 /**
  * Stateless Better Auth helpers. Each function takes the app as a positional
  * argument, so a single helper instance works across multiple test apps in
  * the same suite.
  */
-declare function createBetterAuthTestHelpers(options?: BetterAuthTestHelpersOptions): BetterAuthTestHelpers;
+export declare function createBetterAuthTestHelpers(options?: BetterAuthTestHelpersOptions): BetterAuthTestHelpers;
 /**
  * Composite setup for Better Auth apps. Replaces the pre-v2.11
  * `setupBetterAuthOrg` with a tighter contract:
@@ -339,183 +513,24 @@ declare function createBetterAuthTestHelpers(options?: BetterAuthTestHelpersOpti
  * creators are supplied (ambiguous ownership is a boot-time bug, not a
  * runtime one).
  */
-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. */
-/**
- * A provisioned test database — what the `database` seam yields. Arc
- * core never names a driver: kits ship factories (`mongoMemoryDatabase`
- * is the built-in default; a sqlitekit/pgkit testkit ships its own) and
- * the connection flows through as an opaque generic.
- */
-interface TestDatabase<TConn = unknown> {
-  /** Connection string, when the backend has one (informational). */
-  uri: string;
-  /** Driver connection handle passed to the modules factory. */
-  connection: TConn;
-  /** Stop/disconnect everything this factory started. MUST be idempotent-safe to call once. */
-  teardown(): Promise<void>;
-}
-/** The DB-provisioning seam — `bootModuleApp({ database })`. */
-type TestDatabaseFactory<TConn = unknown> = (opts: {
-  replset?: boolean;
-}) => Promise<TestDatabase<TConn>>;
-interface TestkitContext<TConn = unknown> {
-  /** The provisioned database's connection string. */
-  uri: string;
-  /**
-   * Driver connection handle (the default factory yields mongoose's
-   * DEFAULT connection). Generic so DB-typed wrappers assert the driver
-   * type ONCE: `bootModuleApp<Connection>(...)`. Arc core stays DB-agnostic.
-   */
-  connection: TConn;
-}
-type BootModulesInput<TConn = unknown> = ArcModuleInput | readonly ArcModuleInput[] | ((ctx: TestkitContext<TConn>) => ArcModuleInput | readonly ArcModuleInput[] | Promise<ArcModuleInput | readonly ArcModuleInput[]>);
-interface BootModuleAppOptions<TConn = unknown> {
-  /**
-   * DB provisioner. Default: `mongoMemoryDatabase` (in-memory MongoDB —
-   * lazy devDep imports, nothing Mongo touches arc's runtime). Kits for
-   * other stores inject their own factory here; the rest of the harness
-   * (module resolution, app boot, teardown ordering) is DB-agnostic.
-   */
-  database?: TestDatabaseFactory<TConn>;
-  /** Single-node replica set (transactions). Default: standalone. Passed to the database factory. */
-  replset?: boolean;
-  /**
-   * Extra `createApp` options merged over the testing defaults
-   * (`preset: 'testing'`, `auth: false`, `sensible: false` — utility
-   * plugins stay off so the testkit is dependency-light; re-enable per
-   * 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;
-  /** The mongoose `Connection` handed to the modules factory. */
-  connection: TConn;
-  /**
-   * Typed module-export accessor — `t.exports<CatalogEngine>('catalog')`
-   * instead of reaching through `(t.app as ...).arc.modules.catalog`.
-   * Delegates to `getModuleExports` (throws with the registered-module
-   * list when the name is unknown — same contract hosts get).
-   */
-  exports<TExports = unknown>(name: string): TExports;
-  /** Close app → disconnect mongoose → stop the in-memory server. Idempotent. */
-  close(): Promise<void>;
-}
-/**
- * The built-in DB factory: in-memory MongoDB via lazy devDep imports.
- * Everything Mongo-specific about the harness lives HERE — the harness
- * itself is driver-blind and any kit can replace this via `database`.
- */
-declare function mongoMemoryDatabase(opts: {
-  replset?: boolean;
-}): Promise<TestDatabase<unknown>>;
-declare function bootModuleApp<TConn = unknown>(modules: BootModulesInput<TConn>, options?: BootModuleAppOptions<TConn>): Promise<ModuleTestApp<TConn>>;
+export declare function setupBetterAuthTestApp(input: SetupBetterAuthTestAppInput): Promise<SetupBetterAuthTestAppResult>;
 //#endregion
 //#region src/testing/fixtures.d.ts
-type FixtureFactory<T extends AnyRecord = AnyRecord> = (data: Partial<T>) => Promise<T>;
+type FixtureFactory<T extends object = AnyRecord> = (data: Partial<T>) => Promise<T>;
 /** Delete hook invoked by `clear()` for records that were created through a factory. */
-type FixtureDestroyer<T extends AnyRecord = AnyRecord> = (record: T) => Promise<void>;
-interface FixtureRegistration<T extends AnyRecord = AnyRecord> {
+type FixtureDestroyer<T extends object = AnyRecord> = (record: T) => Promise<void>;
+interface FixtureRegistration<T extends object = AnyRecord> {
   create: FixtureFactory<T>;
   /** Optional cleanup. Defaults to a no-op; adapters that support deletion should provide one. */
   destroy?: FixtureDestroyer<T>;
 }
 interface TestFixtures {
   /** Register a named factory. Later calls replace the earlier registration. */
-  register<T extends AnyRecord = AnyRecord>(name: string, factoryOrRegistration: FixtureFactory<T> | FixtureRegistration<T>): void;
+  register<T extends object = AnyRecord>(name: string, factoryOrRegistration: FixtureFactory<T> | FixtureRegistration<T>): void;
   /** Create one record through the named factory. Tracked for cleanup. */
-  create<T extends AnyRecord = AnyRecord>(name: string, data?: Partial<T>): Promise<T>;
+  create<T extends object = AnyRecord>(name: string, data?: Partial<T>): Promise<T>;
   /** Create many records with a shared template. Tracked for cleanup. */
-  createMany<T extends AnyRecord = AnyRecord>(name: string, count: number, template?: Partial<T>): Promise<T[]>;
+  createMany<T extends object = AnyRecord>(name: string, count: number, template?: Partial<T>): Promise<T[]>;
   /**
    * Run every registered `destroy` hook over the records this instance
    * created, then forget them. Safe to call multiple times (idempotent).
@@ -524,11 +539,11 @@ interface TestFixtures {
    */
   clear(): Promise<void>;
   /** All records ever created by a given factory name (read-only snapshot). */
-  all<T extends AnyRecord = AnyRecord>(name: string): readonly T[];
+  all<T extends object = AnyRecord>(name: string): readonly T[];
   /** Registered factory names. */
   readonly names: readonly string[];
 }
-declare function createTestFixtures(): TestFixtures;
+export declare function createTestFixtures(): TestFixtures;
 //#endregion
 //#region src/testing/HttpTestHarness.d.ts
 interface HttpTestHarnessOptions<T = unknown> {
@@ -548,7 +563,7 @@ interface HttpTestHarnessOptions<T = unknown> {
   apiPrefix?: string;
 }
 type OptionsOrGetter<T> = HttpTestHarnessOptions<T> | (() => HttpTestHarnessOptions<T>);
-declare class HttpTestHarness<T = unknown> {
+export declare class HttpTestHarness<T = unknown> {
   private resource;
   private optionsOrGetter;
   private enabledRoutes;
@@ -566,7 +581,7 @@ declare class HttpTestHarness<T = unknown> {
  * Create an HTTP test harness. `optionsOrGetter` may be a plain object
  * (for eager app setup) or a getter function (for async `beforeAll` apps).
  */
-declare function createHttpTestHarness<T = unknown>(resource: ResourceDefinition<unknown>, optionsOrGetter: HttpTestHarnessOptions<T> | (() => HttpTestHarnessOptions<T>)): HttpTestHarness<T>;
+export declare function createHttpTestHarness<T = unknown>(resource: ResourceDefinition<unknown>, optionsOrGetter: HttpTestHarnessOptions<T> | (() => HttpTestHarnessOptions<T>)): HttpTestHarness<T>;
 //#endregion
 //#region src/testing/mocks.d.ts
 /**
@@ -591,11 +606,11 @@ interface MockRepository<T> extends StandardRepo<T> {
  *
  * await mockRepo.getById('1'); // Returns mocked product
  */
-declare function createMockRepository<T extends AnyRecord = AnyRecord>(overrides?: Partial<MockRepository<T>>): MockRepository<T>;
+export declare function createMockRepository<T extends object = AnyRecord>(overrides?: Partial<MockRepository<T>>): MockRepository<T>;
 /**
  * Create a mock user for authentication testing
  */
-declare function createMockUser(overrides?: Partial<AnyRecord>): {
+export declare function createMockUser(overrides?: Partial<AnyRecord>): {
   _id: string;
   id: string;
   email: string;
@@ -605,11 +620,11 @@ declare function createMockUser(overrides?: Partial<AnyRecord>): {
 /**
  * Create a mock Fastify request
  */
-declare function createMockRequest(overrides?: Partial<AnyRecord>): unknown;
+export declare function createMockRequest(overrides?: Partial<AnyRecord>): unknown;
 /**
  * Create a mock Fastify reply
  */
-declare function createMockReply(): unknown;
+export declare function createMockReply(): unknown;
 /**
  * Create a mock controller for testing.
  *
@@ -625,7 +640,7 @@ declare function createMockReply(): unknown;
  * arguments) while naming only `vitest`, which arc does declare. Same shape
  * `MockRepository` above uses.
  */
-declare function createMockController(repository: StandardRepo<AnyRecord>): {
+export declare function createMockController(repository: StandardRepo<AnyRecord>): {
   repository: StandardRepo<AnyRecord>;
   list: Mock;
   get: Mock;
@@ -646,7 +661,7 @@ declare function createMockController(repository: StandardRepo<AnyRecord>): {
  * const product = productFactory.build();
  * const products = productFactory.buildMany(10);
  */
-declare function createDataFactory<T extends AnyRecord>(template: Record<keyof T, (index: number) => unknown>): {
+export declare function createDataFactory<T extends AnyRecord>(template: Record<keyof T, (index: number) => unknown>): {
   build(overrides?: Partial<T>): T;
   buildMany(count: number, overrides?: Partial<T>): T[];
   reset(): void;
@@ -656,7 +671,7 @@ declare function createDataFactory<T extends AnyRecord>(template: Record<keyof T
  *
  * Useful for testing side effects without full mocking
  */
-declare function createSpy<T extends (...args: unknown[]) => unknown>(_name?: string): Mock<T> & {
+export declare function createSpy<T extends (...args: unknown[]) => unknown>(_name?: string): Mock<T> & {
   getCalls(): unknown[][];
   getLastCall(): unknown[];
 };
@@ -677,7 +692,7 @@ declare function createSpy<T extends (...args: unknown[]) => unknown>(_name?: st
  * @example
  * await waitFor(() => runs >= 3, { label: "3 scheduler ticks" });
  */
-declare function waitFor(condition: () => boolean | Promise<boolean>, options?: {
+export declare function waitFor(condition: () => boolean | Promise<boolean>, options?: {
   timeout?: number;
   interval?: number;
   label?: string;
@@ -685,7 +700,7 @@ declare function waitFor(condition: () => boolean | Promise<boolean>, options?:
 /**
  * Create a test timer that can be controlled
  */
-declare function createTestTimer(): {
+export declare function createTestTimer(): {
   now: () => number;
   advance: (ms: number) => void;
   set: (timestamp: number) => void;
@@ -695,7 +710,7 @@ declare function createTestTimer(): {
 //#region src/testing/moduleSetup.d.ts
 interface TestModuleSetup {
   /** Pass this as the second argument to `bootstrap` / `plugins` / `afterResources`. */
-  readonly context: ModuleSetupContext;
+  readonly context: ModuleSetupContext<PortName, PortName>;
   /**
    * Disposers the module registered, in REGISTRATION order (`dispose()` runs
    * them backwards). Assert on `.length` to prove a phase registered teardown
@@ -712,7 +727,10 @@ interface TestModuleSetup {
    */
   dispose(): Promise<void>;
 }
-declare function createTestModuleSetup(): TestModuleSetup;
+export declare function createTestModuleSetup(options?: {
+  /** The `context.ports` the phases see — supply what the module declares. */
+  readonly ports?: ArcPorts;
+}): TestModuleSetup;
 //#endregion
 //#region src/testing/scopeRoleGate.d.ts
 /**
@@ -737,7 +755,7 @@ declare function createTestModuleSetup(): TestModuleSetup;
  * 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;
+export declare function scopeRoleGate(...allowed: string[]): PermissionCheck;
 //#endregion
 //#region src/testing/testApp.d.ts
 type DbMode = "in-memory" | {
@@ -808,12 +826,12 @@ interface TestAppContext {
    */
   close(): Promise<void>;
 }
-declare function createTestApp(options?: CreateTestAppOptions): Promise<TestAppContext>;
+export declare function createTestApp(options?: CreateTestAppOptions): Promise<TestAppContext>;
 /**
  * Minimal Fastify instance — no arc plugins, no auth, no db. Use when a test
  * needs bare Fastify (e.g. plugin unit tests that manually register their
  * dependencies).
  */
-declare function createMinimalTestApp(options?: FastifyServerOptions): FastifyInstance;
+export 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, TEST_ACTOR_HEADER, type TestActor, type TestAppContext, type TestAuthProvider, type TestAuthSession, type TestDatabase, type TestDatabaseFactory, type TestFixtures, type TestModuleSetup, type TestkitContext, bootModuleApp, createBetterAuthProvider, createBetterAuthTestHelpers, createCustomAuthProvider, createDataFactory, createHttpTestHarness, createJwtAuthProvider, createMinimalTestApp, createMockController, createMockReply, createMockRepository, createMockRequest, createMockUser, createSpy, createTestApp, createTestFixtures, createTestModuleSetup, createTestTimer, expectArc, mongoMemoryDatabase, preloadResources, preloadResourcesAsync, runAuthorizationConformance, runStorageContract, safeParseBody, scopeFromTestActor, scopeRoleGate, setupBetterAuthTestApp, testActorAuth, testActorHeaders, 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, type HttpTestHarnessOptions, type MockRepository, type ModuleBootsAloneOptions, type ModuleBootsAloneResult, type ModuleTestApp, type OrgResponse, type RoleConfig, type SetupBetterAuthTestAppInput, type SetupBetterAuthTestAppResult, type SignInInput, type SignUpInput, type StorageContractSetup, type StorageContractSetupResult, type SurfaceObservation, type TestActor, type TestAppContext, type TestAuthProvider, type TestAuthSession, type TestDatabase, type TestDatabaseFactory, type TestFixtures, type TestModuleSetup, type TestkitContext, runStorageContract };