@voltro/testing 0.33.0 → 0.34.0

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { AppContext } from '@voltro/runtime';
+import { AuthStrategy } from '@voltro/protocol';
 import { changeDelete } from '@voltro/database';
 import { ChangeEvent } from '@voltro/database';
 import { changeInsert } from '@voltro/database';
@@ -13,18 +14,31 @@ import { InspectedWorkflow } from '@voltro/workflow';
 import { Layer } from 'effect';
 import { ParseResult } from 'effect';
 import { ProcedureDescriptor } from '@voltro/protocol';
+import { PublicApiDescriptor } from '@voltro/protocol/rest';
 import { RelationsSpec } from '@voltro/database';
+import { RestRouteDescriptor } from '@voltro/protocol/rest';
+import { RestServeBindings } from '@voltro/protocol/rest';
 import { Row } from '@voltro/database';
 import { RowFilter } from '@voltro/runtime';
 import { RpcInterceptor } from '@voltro/protocol';
 import { RpcKind } from '@voltro/protocol';
 import { Schema } from 'effect';
+import { Scope } from 'effect';
 import { Subject } from '@voltro/protocol';
 import { SubscribeContext } from '@voltro/runtime';
 import { SyncLogger } from '@voltro/logger';
 import { TableLike } from '@voltro/database';
 import { VoltroPlugin } from '@voltro/protocol';
 
+/** An unauthenticated caller, optionally carrying a tenant (what the
+ *  `x-tenant` header resolves to when no auth strategy matches). Delegates to
+ *  the protocol's own constructor so the harness cannot drift from it. */
+export declare const anonymous: (tenantId?: string | null) => Subject;
+
+/** An API-key subject — what a `Authorization: Bearer <key>` call resolves to.
+ *  Same shape as `user()`; the `type` is what an app's own branching reads. */
+export declare const apiKey: (id: string, options?: TestSubjectOptions) => Subject;
+
 export { changeDelete }
 
 export { ChangeEvent }
@@ -35,6 +49,47 @@ export { changeSoftDelete }
 
 export { changeUpdate }
 
+/**
+ * A named factory for `table`.
+ *
+ * ```ts
+ * const users = defineFactory(usersTable, {
+ *   defaults: { email: (seq) => `user-${seq}@test.local`, role: 'member' },
+ *   traits:   { admin: { role: 'admin' } },
+ * })
+ * const posts = defineFactory(postsTable, { associations: { authorId: users } })
+ *
+ * const admin = await users.with('admin').create(ctx.store)
+ * const post  = await posts.create(ctx.store, { authorId: admin.id })  // no extra user
+ * const orphanFree = await posts.create(ctx.store)                     // an author IS created
+ * ```
+ */
+export declare const defineFactory: (table: TableLike, options?: DefineFactoryOptions) => Factory;
+
+export declare interface DefineFactoryOptions {
+    /** Column defaults applied before the caller's per-call overrides. */
+    readonly defaults?: FactoryDefaults;
+    /** Named override bundles, selected with `.with('name')`. */
+    readonly traits?: Readonly<Record<string, FactoryDefaults>>;
+    /**
+     * Factories for this table's ancestors, keyed by the REFERENCE COLUMN name.
+     * `create()` uses one when it has to build a parent, so the parent gets its
+     * own defaults and its own ancestors rather than a bare `fixtureRow`.
+     *
+     * ```ts
+     * const posts = defineFactory(postsTable, {
+     *   associations: { authorId: users },   // `users` is another factory
+     * })
+     * ```
+     *
+     * Omitted for a column → the parent is built with a plain `fixtureRow` (plus
+     * ITS own required ancestors, recursively). That is enough for a parent
+     * nothing asserts on, and the escape hatch when it is not is to pass the id
+     * explicitly, which always wins over both.
+     */
+    readonly associations?: Readonly<Record<string, Factory>>;
+}
+
 /**
  * `describe` a suite whose dependency is checked by ITS OWN probe.
  *
@@ -82,6 +137,66 @@ export declare interface EmittedWebhook {
  *  ergonomic without an `any` in the public type. */
 declare type ErasedWorkflowEffect = Effect.Effect<unknown, unknown, never>;
 
+export declare interface Factory {
+    /** The table this factory builds rows for. */
+    readonly table: TableLike;
+    /** A complete row — defaults, then traits, then `overrides`, then
+     *  `fixtureRow` for whatever is still required. Pure: writes nothing, and
+     *  therefore creates NO parent rows (a `reference()` column with no override
+     *  gets `fixtureRow`'s placeholder). Use `create` when the relations matter. */
+    readonly build: (overrides?: Row) => Row;
+    /** `count` built rows. `overrides` may be a function of the index when the
+     *  rows must differ. */
+    readonly buildList: (count: number, overrides?: Row | ((index: number) => Row)) => ReadonlyArray<Row>;
+    /**
+     * Insert a row AND every ancestor it requires, in dependency order, and
+     * return the inserted row (the store's, so auto-stamped ids/audit columns are
+     * on it).
+     *
+     * An ancestor is created only for a required `reference()` column the merged
+     * overrides leave unset — pass `{ authorId: existing.id }` and nothing extra
+     * is written.
+     */
+    readonly create: (store: FactoryStore, overrides?: Row) => Promise<Row>;
+    /** `count` created rows. Each gets its OWN ancestors unless the override
+     *  pins them, which is usually what a list test wants — pass the parent id in
+     *  `overrides` to share one. */
+    readonly createList: (store: FactoryStore, count: number, overrides?: Row | ((index: number) => Row)) => Promise<ReadonlyArray<Row>>;
+    /** A derived factory with these traits' defaults merged in, in the order
+     *  named (later wins). Throws for a trait this factory does not declare —
+     *  a mistyped trait name silently building the BASE row is the failure mode
+     *  this rules out. */
+    readonly with: (...traits: ReadonlyArray<string>) => Factory;
+    /** A derived factory with extra defaults merged in — the ad-hoc form of a
+     *  trait, for a one-off variation not worth naming. */
+    readonly extend: (defaults: FactoryDefaults) => Factory;
+}
+
+/** Column → default. Every key is optional; anything omitted falls through to
+ *  `fixtureRow`'s placeholder or, for a `reference()`, to an association. */
+export declare type FactoryDefaults = Readonly<Record<string, FactoryValue>>;
+
+/** The narrow slice of a store a factory writes through — `ctx.store` and any
+ *  transactional view of it satisfy it structurally. Typed as a shape rather
+ *  than as `DataStore` so a factory can also be handed the mixin-wrapped store
+ *  a handler sees, which is the one a test actually holds. */
+export declare interface FactoryStore {
+    insert(table: string, row: Row): Promise<Row>;
+}
+
+/**
+ * One column's default: a function handed a monotonic sequence number
+ * (`(seq) => \`user-${seq}@test.local\``) for a unique column, or a plain value.
+ *
+ * The arms are spelled out rather than written `unknown | ((seq: number) => …)`,
+ * which is the obvious version and is silently WRONG: `unknown` absorbs every
+ * other member of a union, so that type collapses to `unknown`, the function
+ * arm disappears, and a caller writing `(seq) => …` gets `seq: any` with no
+ * contextual type at all. The function arm is FIRST so it wins contextual
+ * typing for an arrow literal.
+ */
+export declare type FactoryValue = ((sequence: number) => unknown) | string | number | boolean | bigint | Date | null | undefined | ReadonlyArray<unknown> | Readonly<Record<string, unknown>>;
+
 /**
  * Complete a partial row for `table` so it satisfies the required-column insert
  * validation. Fills every NOT-NULL, no-default, non-auto-stamped column that
@@ -91,6 +206,20 @@ declare type ErasedWorkflowEffect = Effect.Effect<unknown, unknown, never>;
  */
 export declare const fixtureRow: (table: TableLike, overrides?: Row) => Row;
 
+/**
+ * The Effect-native form: global time is frozen for the SCOPE's lifetime and
+ * restored on release — on success, on failure, and on interruption.
+ *
+ * ```ts
+ * Effect.scoped(Effect.gen(function* () {
+ *   const clock = yield* frozenTime('2026-03-01T12:00:00Z')
+ *   yield* handler                    // every `new Date()` inside reads the mock
+ *   clock.advance('1d')
+ * }))
+ * ```
+ */
+export declare const frozenTime: (at: Date | number | string | MockClock) => Effect.Effect<MockClock, never, Scope.Scope>;
+
 /**
  * What `invoke` resolves to for a handler returning `Result`: an `Effect`'s
  * SUCCESS value, an awaited `Promise`, or the value itself.
@@ -121,6 +250,7 @@ export declare type HandlerOutput<Result> = Result extends Effect.Effect<infer A
  * `makeTestContext({ plugins })` wrap the whole thing from outside.
  *
  * ```ts
+ * import { invoke, makeTestContext, user } from '@voltro/testing'
  * import { createNote } from './notes.mutation'              // descriptor
  * import { createNoteHandler } from './notes.mutation.server' // executor
  *
@@ -171,6 +301,50 @@ export declare interface MakeSubscribeContextOptions {
     readonly log?: SyncLogger;
 }
 
+/**
+ * Build a request-level harness over `ctx`.
+ *
+ * The subject a request runs under is resolved PER REQUEST — by the strategy
+ * chain from the request's own headers, or by `actingAs` — and the procedure
+ * then runs on `ctx.withSubject(resolved, …)`. That is the whole point of the
+ * layer: two calls to the same app with different headers are two different
+ * callers reading through the same store, exactly as two HTTP requests are.
+ */
+export declare const makeTestApp: (options: MakeTestAppOptions) => TestApp;
+
+export declare interface MakeTestAppOptions {
+    /** The context every request runs against. Its store is the app's store; the
+     *  request's RESOLVED subject re-scopes it per call via `withSubject`, so a
+     *  request genuinely reads through the identity the transport produced rather
+     *  than the one the context was built with. */
+    readonly ctx: TestContext;
+    /**
+     * Hand-authored `defineRestRoute` descriptors (an app's `restRoutes`).
+     *
+     * Typed `<any, any>` to match `app.config.ts`'s own `restRoutes` field and
+     * `restRoutesToHttpRoutes`'s parameter: each descriptor fixes its OWN input
+     * and output types at `defineRestRoute`, and a heterogeneous array of them
+     * has no single narrower element type — `<never, never>` rejects every real
+     * route (the handler's return type is contravariant into it).
+     */
+    readonly restRoutes?: ReadonlyArray<RestRouteDescriptor<any, any>>;
+    /** Procedures carrying a `publicApi:` annotation, with their executors. */
+    readonly publicApi?: ReadonlyArray<PublicApiBinding>;
+    /**
+     * The app's auth strategies, composed by the framework's own
+     * `composeAuthStrategies`. With none supplied the composer's DEFAULT applies:
+     * an anonymous subject carrying the `x-tenant` header's tenant — which is
+     * itself the behaviour most worth testing, and the one `invoke` cannot reach.
+     */
+    readonly strategies?: ReadonlyArray<AuthStrategy>;
+    /** Refuse an anonymous caller that carries no tenant (`Unauthenticated`).
+     *  Passed straight to `composeAuthStrategies`. */
+    readonly anonymousTenantRequired?: boolean;
+    /** HTTP idempotency binding — the same `{ store, header, ttlMs }` the serve
+     *  path builds from `app.config.ts`'s `idempotency` field. */
+    readonly idempotency?: RestServeBindings['idempotency'];
+}
+
 export declare const makeTestContext: <RowFilterCtx = unknown>(options?: MakeTestContextOptions<RowFilterCtx>) => TestContext;
 
 export declare interface MakeTestContextOptions<RowFilterCtx = unknown> {
@@ -238,11 +412,40 @@ export declare interface MakeTestContextOptions<RowFilterCtx = unknown> {
      * the CONTEXT, not on `invoke`, because production composes the chain once
      * at boot — an app cannot vary its plugin set per call, so neither can this.
      *
-     * Only the rpc interceptors are wired. Lifecycle hooks (`onActivate`),
-     * `schema`, routes and dashboard mounts are boot concerns with no meaning
-     * for a single handler call, and are ignored.
+     * Their `services:` LAYER is provided too — `invoke` builds the same handler
+     * service stack the serve pipeline does, so an Effect-mode handler that
+     * `yield* MailService`s (or `StorageService`, or any tag a plugin owns)
+     * resolves it under test instead of dying with "Service not found". That is
+     * the whole reason the mail assertion surface is the plugin's own memory
+     * provider rather than a mock this package invents:
+     *
+     * ```ts
+     * import { mailPlugin, readMailBuffer, clearMailBuffer } from '@voltro/plugin-mail'
+     *
+     * const ctx = makeTestContext({ plugins: [mailPlugin({ provider: 'memory', from: 'a@b.c' })] })
+     * await invoke(sendWelcome, sendWelcomeHandler, { to: 'x@y.z' }, ctx)
+     * expect(readMailBuffer().map((m) => m.to)).toEqual(['x@y.z'])
+     * ```
+     *
+     * Lifecycle hooks (`onActivate`), `schema`, routes and dashboard mounts are
+     * boot concerns with no meaning for a single handler call, and are ignored —
+     * so a plugin whose service is built INSIDE `onActivate` will not resolve
+     * here. Every first-party plugin builds its service eagerly in the factory.
      */
     readonly plugins?: ReadonlyArray<VoltroPlugin>;
+    /**
+     * The app's own `layers:` from `app.config.ts` — user-defined Effect
+     * services a handler `yield*`s.
+     *
+     * Passed EXPLICITLY, never discovered: the harness runs no boot, so it
+     * cannot read `app.config.ts`, and inventing a stand-in service would assert
+     * against the stand-in. Handing over the real layer is not faking — it is the
+     * same object the boot path merges.
+     *
+     * Merged LAST, so a user layer overrides a plugin layer declaring the same
+     * Tag — the ordering `makeHandlerServiceLayer` uses on both boot paths.
+     */
+    readonly layers?: ReadonlyArray<Layer.Layer<unknown, never, never>>;
     /**
      * Row-level security for this context, WITHOUT touching the process global.
      *
@@ -280,21 +483,35 @@ export declare interface MockAi {
 
 export declare class MockClock {
     private currentMs;
-    constructor(initial?: Date | number);
+    constructor(initial?: Date | number | string);
     /** Current mock time as an instant in ms. */
     now(): number;
     /** Current mock time as a Date. */
     date(): Date;
     /** Advance time by a duration (ms / seconds / minutes / hours / days). */
     advance(amount: number | string): void;
-}
-
-export declare class MockEmail {
-    readonly sent: SentEmail[];
-    send(email: Omit<SentEmail, 'sentAt'>): void;
-    /** Find the most recent email to a recipient, or undefined. */
-    lastTo(recipient: string): SentEmail | undefined;
-    clear(): void;
+    /** Jump to an ABSOLUTE instant. `advance` moves relative; this is `travel_to`. */
+    set(at: Date | number | string): void;
+    /** Is THIS clock the one currently faking global time? */
+    get installed(): boolean;
+    /**
+     * Take over `Date.now()` / `new Date()` for the whole realm. Returns the
+     * uninstall — call it, or prefer `withFrozenTime` / `frozenTime`, which call
+     * it for you even when the body throws.
+     *
+     * Throws if any clock is already installed. See the header: an inner
+     * uninstall would otherwise restore the outer FAKE and leave the realm frozen
+     * with nothing naming the cause.
+     */
+    install(): () => void;
+    /**
+     * Give the realm its real clock back.
+     *
+     * A no-op when this clock is not the installed one, so an uninstall in a
+     * `finally` is safe to run twice. The loud direction is the INSTALL — that is
+     * the one that corrupts the next test.
+     */
+    uninstall(): void;
 }
 
 export declare class MockLLM {
@@ -348,6 +565,19 @@ export declare class MockWebhooks {
     clear(): void;
 }
 
+/**
+ * The next value of that same counter — for a caller writing their OWN unique
+ * default (`email: () => \`user-${nextSequence()}@test.local\``).
+ *
+ * Sharing ONE counter with the auto-filler is the point, not an implementation
+ * detail: two sources of "unique enough" numbers in one process will collide
+ * eventually, and the collision surfaces as a constraint violation in a test
+ * that looks unrelated to either. Monotonic per process, never reset — a reset
+ * between tests would re-issue values that rows from an earlier test in the
+ * same worker still hold.
+ */
+export declare const nextSequence: () => number;
+
 /** Delivery nudges emitted through `ctx.outbox` on this context. */
 export declare const outboxNudgesOf: (ctx: TestContext) => ReadonlyArray<string>;
 
@@ -359,8 +589,22 @@ export { ParseResult }
  *  framework's contract is "async or Effect, your choice per handler", and the
  *  dispatcher runs both (`Effect.isEffect(result) ? … : …` in `servePipeline`).
  *  `E` is the handler's typed error channel; it defaults to `never` for the
- *  common `Effect.gen` that only succeeds. */
-export declare type ProcedureExecutor<Input, Output, E = never> = (input: Input, ctx: TestContext) => Output | Promise<Output> | Effect.Effect<Output, E>;
+ *  common `Effect.gen` that only succeeds. `R` is the services the handler
+ *  `yield*`s — `MailService`, a plugin Tag, one of the app's own `layers:`.
+ *  `invoke` provides those from the context's `plugins:` / `layers:`, so a
+ *  handler with a non-`never` `R` is callable; it defaults to `never` for the
+ *  common handler that resolves nothing. */
+export declare type ProcedureExecutor<Input, Output, E = never, R = never> = (input: Input, ctx: TestContext) => Output | Promise<Output> | Effect.Effect<Output, E, R>;
+
+/** One `publicApi`-annotated procedure plus the executor that implements it —
+ *  the same descriptor/handler pair `invoke` takes. The harness runs the
+ *  handler THROUGH `invoke`, so the procedure's `guards:`, input decode,
+ *  mutation transaction and plugin interceptors all still apply underneath the
+ *  REST hop. */
+export declare interface PublicApiBinding {
+    readonly descriptor: PublicApiDescriptor;
+    readonly handler: (input: never, ctx: TestContext) => unknown;
+}
 
 export declare interface ReachableTarget {
     readonly host: string;
@@ -430,12 +674,67 @@ export declare const runAfterCommit: (ctx: TestContext) => Promise<void>;
  */
 export declare const runInStoreTransaction: <T>(ctx: TestContext, work: (txCtx: TestContext) => Promise<T>) => Promise<T>;
 
-export declare interface SentEmail {
-    readonly to: string;
-    readonly template: string;
-    readonly props?: Readonly<Record<string, unknown>>;
-    readonly locale?: string;
-    readonly sentAt: Date;
+/** A machine subject scoped to ONE tenant (a per-tenant integration, a
+ *  `storeForTenant` view). NOT the cross-tenant `system()` below. */
+export declare const serviceAccount: (id: string, options?: TestSubjectOptions) => Subject;
+
+/**
+ * The handler service layer for this context — every registered plugin's
+ * `services:` layer, then the app's own `layers:`, merged in that order.
+ *
+ * The ORDER is the serve pipeline's (`makeHandlerServiceLayer`): user layers
+ * last, so an app layer declaring the same Tag as a plugin's wins here exactly
+ * as it does in production. `undefined` when the context registered neither —
+ * a handler that `yield*`s a Tag nobody provided must still die with "Service
+ * not found", because that is what it would do at runtime.
+ *
+ * What is deliberately NOT in here: `Cache` / `Kv` / `AnalyticsSink` / the
+ * aggregate + standing-primitive registries / the outbound `HttpClient`. Those
+ * are built by the CLI at boot from an app's config, and `@voltro/testing`
+ * cannot depend on the CLI. Nothing about that is faked — a handler needing one
+ * gets the honest "Service not found" instead of a stand-in whose behaviour the
+ * test would then be asserting.
+ *
+ * Exported so a test can assert the layer set a context carries without going
+ * through a handler.
+ */
+export declare const serviceLayerFor: (ctx: TestContext) => Layer.Layer<never, never, never> | undefined;
+
+/**
+ * The CROSS-TENANT machine actor — cron, workflows, backfills. `tenantId` is
+ * `null` by construction and the tenant read-scope mixin reads that as "every
+ * tenant" rather than "no rows", so this is not a tenant-less `user()`.
+ * Defaults to `['admin:full']`, matching `systemSubject`.
+ */
+export declare const system: (id?: string, scopes?: ReadonlyArray<string>) => Subject;
+
+/** The tenant every `user()` / `apiKey()` / `serviceAccount()` belongs to
+ *  unless told otherwise. Exported so a test can seed rows under the same
+ *  tenant the default subject reads through. */
+export declare const TEST_TENANT_ID = "test-tenant";
+
+export declare interface TestApp {
+    /** A view of this app that resolves EVERY request to `subject`, bypassing the
+     *  strategy chain — the same `resolveSubject` seam the serve pipeline fills
+     *  with its own auth resolver. Use it to test what a given identity may do;
+     *  use `withHeaders({ 'x-tenant': … })` (and no `actingAs`) to test how an
+     *  identity is RESOLVED. */
+    readonly actingAs: (subject: Subject) => TestApp;
+    /** A view of this app that sends `headers` on every request. Merged over
+     *  whatever is already set; later calls win per key. */
+    readonly withHeaders: (headers: Readonly<Record<string, string>>) => TestApp;
+    readonly get: (path: string, options?: TestRequestOptions) => Promise<TestResponse>;
+    readonly delete: (path: string, options?: TestRequestOptions) => Promise<TestResponse>;
+    readonly post: (path: string, body?: unknown, options?: TestRequestOptions) => Promise<TestResponse>;
+    readonly put: (path: string, body?: unknown, options?: TestRequestOptions) => Promise<TestResponse>;
+    readonly patch: (path: string, body?: unknown, options?: TestRequestOptions) => Promise<TestResponse>;
+    /** The general form the five verbs above are sugar over. */
+    readonly request: (method: string, path: string, options?: TestRequestOptions & {
+        readonly body?: unknown;
+    }) => Promise<TestResponse>;
+    /** Every path this app mounts, in mount order. A 404 names them, and a test
+     *  asserting the mounted surface can read them without one. */
+    readonly paths: ReadonlyArray<string>;
 }
 
 /** The test context IS an `AppContext` (store + request + cache), plus the
@@ -444,7 +743,6 @@ export declare interface SentEmail {
  *  `(input, ctx: AppContext) => …`. */
 export declare interface TestContext extends AppContext {
     readonly clock: MockClock;
-    readonly email: MockEmail;
     /** Outgoing webhooks, recorded. `ctx.webhooks` is a field production supplies
      *  and the harness did not, so a mutation written the documented way —
      *  `useWebhooks(ctx).emit(...)` — threw in every unit test. */
@@ -517,6 +815,38 @@ export declare interface TestEventBusOptions {
 
 export declare const TESTING_PRESET_VERSION: 1;
 
+export declare interface TestRequestOptions {
+    /** Extra headers for this call, merged over the app's (`actingAs` /
+     *  `withHeaders`) headers. Names are lowercased, as the transport delivers
+     *  them. */
+    readonly headers?: Readonly<Record<string, string>>;
+}
+
+export declare interface TestResponse {
+    readonly status: number;
+    /** Response headers, names lowercased. */
+    readonly headers: Readonly<Record<string, string>>;
+    /** The raw response body as text (empty string when there was none). */
+    readonly text: string;
+    /** The body parsed as JSON when the route answered with a JSON content-type,
+     *  otherwise `undefined`. Every framework REST response is JSON; a streaming
+     *  (SSE) route answers with neither — see `stream`. */
+    readonly body: unknown;
+    /** `true` for a streaming (SSE) route: the response has no buffered body, so
+     *  `text` is empty and `body` is `undefined`. Stated rather than silently
+     *  looking like an empty 200. */
+    readonly stream: boolean;
+}
+
+export declare interface TestSubjectOptions {
+    /** Default `TEST_TENANT_ID`. */
+    readonly tenantId?: string;
+    /** Default `[]` — no authority. Guards deny. */
+    readonly scopes?: ReadonlyArray<string>;
+    /** Strategy-specific claims (`metadata.provider`, org ids, raw JWT claims). */
+    readonly metadata?: Record<string, unknown>;
+}
+
 export declare interface TestSubscriber<P = unknown> {
     /** Payloads delivered so far, in order. */
     readonly received: ReadonlyArray<P>;
@@ -532,6 +862,33 @@ export declare interface TestSubscriber<P = unknown> {
     readonly stop: () => void;
 }
 
+/**
+ * An end-user subject — what a signed-in session resolves to.
+ *
+ * ```ts
+ * const ctx = makeTestContext({ subject: user('u1', { scopes: ['notes:write'] }) })
+ * const outsider = makeTestContext({ subject: user('u2') })   // no scopes → guards deny
+ * ```
+ */
+export declare const user: (id: string, options?: TestSubjectOptions) => Subject;
+
+/**
+ * Run `body` with global time frozen at `at`, then restore — whether the body
+ * returns, throws, resolves or rejects.
+ *
+ * ```ts
+ * withFrozenTime('2026-03-01T12:00:00Z', (clock) => {
+ *   expect(new Date().toISOString()).toBe('2026-03-01T12:00:00.000Z')
+ *   clock.advance('1h')                       // global time moves with it
+ * })
+ * ```
+ *
+ * An ASYNC body is awaited before the restore. A plain `finally` around a
+ * promise-returning call would put the clock back while the body was still
+ * running, which is the failure this helper exists to make impossible.
+ */
+export declare const withFrozenTime: <A>(at: Date | number | string | MockClock, body: (clock: MockClock) => A) => A;
+
 /** A workflow + its execute function, as the framework pairs them via
  *  `workflow.toLayer(execute)`. Structural (no `@effect/workflow` generic
  *  signature) so callers can pass the value from `workflow({ name, ... })`